[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Texi2html-cvs] texi2html/test/manuals res/ccvs/cvs.2 res/ccvs_...
|
From: |
Patrice Dumas |
|
Subject: |
[Texi2html-cvs] texi2html/test/manuals res/ccvs/cvs.2 res/ccvs_... |
|
Date: |
Sun, 02 Aug 2009 13:11:10 +0000 |
CVSROOT: /cvsroot/texi2html
Module name: texi2html
Changes by: Patrice Dumas <pertusus> 09/08/02 13:11:06
Modified files:
test/manuals/res/ccvs: cvs.2
test/manuals/res/ccvs_info: cvs.2
test/manuals/res/ccvs_mediawiki: cvs.2
test/manuals/res/ccvs_mediawiki_nosplit: cvs.2
test/manuals/res/hello: hello.html
test/manuals/res/hello_nodes:
GNU-Free-Documentation-License.html
test/manuals/res/info-stnd: Copying-This-Manual.html
test/manuals/res/mini_ker: GNU-Free-Documentation-License.html
mini_ker.html
test/manuals/res/texi_cvs: cvs.2 cvs.passfirst cvs.passtexi
cvs.texi
test/manuals/res/texi_mini_ker: mini_ker.2 mini_ker.passfirst
mini_ker.passtexi mini_ker.texi
test/manuals/res/texinfo: texinfo_31.html
test/manuals/res/texinfo_nodes:
GNU-Free-Documentation-License.html
test/manuals/res/texinfo_xml: texinfo.xml
test/manuals/res_all/ccvs: cvs.2
test/manuals/res_all/ccvs_info: cvs.2
test/manuals/res_all/ccvs_mediawiki: cvs.2
test/manuals/res_all/ccvs_mediawiki_nosplit: cvs.2
test/manuals/res_all/mini_ker:
GNU-Free-Documentation-License.html
index.html
test/manuals/res_all/texi_cvs: cvs.2 cvs.passfirst cvs.passtexi
cvs.texi
test/manuals/res_all/texi_mini_ker: mini_ker.2
mini_ker.passfirst
mini_ker.passtexi
mini_ker.texi
test/manuals/res_all/texinfo_xml: texinfo.xml
test/manuals/res_info/ccvs: cvs.2
test/manuals/res_info/ccvs_info: cvs.2
test/manuals/res_info/ccvs_mediawiki: cvs.2
test/manuals/res_info/ccvs_mediawiki_nosplit: cvs.2
test/manuals/res_info/mini_ker:
GNU-Free-Documentation-License.html
index.html
test/manuals/res_info/texi_cvs: cvs.2 cvs.passfirst cvs.passtexi
cvs.texi
test/manuals/res_info/texi_mini_ker: mini_ker.2
mini_ker.passfirst
mini_ker.passtexi
mini_ker.texi
test/manuals/res_info/texinfo_xml: texinfo.xml
Added files:
test/manuals/res/texi_cvs: cvs.texi.first
test/manuals/res/texi_hello: hello.texi.first
test/manuals/res/texi_info-stnd: info-stnd.texi.first
test/manuals/res/texi_mini_ker: mini_ker.texi.first
test/manuals/res/texi_texinfo: texinfo.texi.first
test/manuals/res_all/texi_cvs: cvs.texi.first
test/manuals/res_all/texi_hello: hello.texi.first
test/manuals/res_all/texi_info-stnd: info-stnd.texi.first
test/manuals/res_all/texi_mini_ker: mini_ker.texi.first
test/manuals/res_all/texi_texinfo: texinfo.texi.first
test/manuals/res_info/texi_cvs: cvs.texi.first
test/manuals/res_info/texi_hello: hello.texi.first
test/manuals/res_info/texi_info-stnd: info-stnd.texi.first
test/manuals/res_info/texi_mini_ker: mini_ker.texi.first
test/manuals/res_info/texi_texinfo: texinfo.texi.first
Log message:
* texi2html.pl, texi2html.init: treat @alias like a normal misc
commmand.
Keep @macros definitions in output, treat them as raw
environments
that can be nested.
Warn for deprecated commands.
* texi2html.init: @syncodeindex and @finalout swallow end of
line.
* formats/html.init: Don't double in title when the @top and
@settitle are the same.
* texi2html.pl: add 0x7F as a comment character.
Still provide the default output with --macro-expand.
warning if macro with an argument number different than 1
is called without a {}.
Read TEXINFO_OUTPUT_FORMAT in env to determine the output
format,
if not overridden by a command line option.
More error and warning messages, especially for info.
Warn for superfluous @node arguments.
Remove whitespaces after formats, even in last pass.
* Makefile.am, documentlanguages.pl,
regenerate_documentlanguages.pl:
Gather language codes and regions from the iana registery file.
* formats/info.init: remove last end of line in @image file.txt
Warn if there is a float or anchor before first node.
* tests/*: run only once to generate the the texi_* output.
CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/ccvs/cvs.2?cvsroot=texi2html&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/ccvs_info/cvs.2?cvsroot=texi2html&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/ccvs_mediawiki/cvs.2?cvsroot=texi2html&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/ccvs_mediawiki_nosplit/cvs.2?cvsroot=texi2html&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/hello/hello.html?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/hello_nodes/GNU-Free-Documentation-License.html?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/info-stnd/Copying-This-Manual.html?cvsroot=texi2html&r1=1.6&r2=1.7
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/mini_ker/GNU-Free-Documentation-License.html?cvsroot=texi2html&r1=1.8&r2=1.9
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/mini_ker/mini_ker.html?cvsroot=texi2html&r1=1.9&r2=1.10
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/texi_cvs/cvs.2?cvsroot=texi2html&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/texi_cvs/cvs.passfirst?cvsroot=texi2html&r1=1.4&r2=1.5
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/texi_cvs/cvs.passtexi?cvsroot=texi2html&r1=1.5&r2=1.6
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/texi_cvs/cvs.texi?cvsroot=texi2html&r1=1.4&r2=1.5
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/texi_cvs/cvs.texi.first?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/texi_hello/hello.texi.first?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/texi_info-stnd/info-stnd.texi.first?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/texi_mini_ker/mini_ker.2?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/texi_mini_ker/mini_ker.passfirst?cvsroot=texi2html&r1=1.4&r2=1.5
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/texi_mini_ker/mini_ker.passtexi?cvsroot=texi2html&r1=1.5&r2=1.6
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/texi_mini_ker/mini_ker.texi?cvsroot=texi2html&r1=1.4&r2=1.5
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/texi_mini_ker/mini_ker.texi.first?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/texi_texinfo/texinfo.texi.first?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/texinfo/texinfo_31.html?cvsroot=texi2html&r1=1.6&r2=1.7
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/texinfo_nodes/GNU-Free-Documentation-License.html?cvsroot=texi2html&r1=1.6&r2=1.7
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res/texinfo_xml/texinfo.xml?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_all/ccvs/cvs.2?cvsroot=texi2html&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_all/ccvs_info/cvs.2?cvsroot=texi2html&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_all/ccvs_mediawiki/cvs.2?cvsroot=texi2html&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_all/ccvs_mediawiki_nosplit/cvs.2?cvsroot=texi2html&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_all/mini_ker/GNU-Free-Documentation-License.html?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_all/mini_ker/index.html?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_all/texi_cvs/cvs.2?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_all/texi_cvs/cvs.passfirst?cvsroot=texi2html&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_all/texi_cvs/cvs.passtexi?cvsroot=texi2html&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_all/texi_cvs/cvs.texi?cvsroot=texi2html&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_all/texi_cvs/cvs.texi.first?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_all/texi_hello/hello.texi.first?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_all/texi_info-stnd/info-stnd.texi.first?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_all/texi_mini_ker/mini_ker.2?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_all/texi_mini_ker/mini_ker.passfirst?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_all/texi_mini_ker/mini_ker.passtexi?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_all/texi_mini_ker/mini_ker.texi?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_all/texi_mini_ker/mini_ker.texi.first?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_all/texi_texinfo/texinfo.texi.first?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_all/texinfo_xml/texinfo.xml?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_info/ccvs/cvs.2?cvsroot=texi2html&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_info/ccvs_info/cvs.2?cvsroot=texi2html&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_info/ccvs_mediawiki/cvs.2?cvsroot=texi2html&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_info/ccvs_mediawiki_nosplit/cvs.2?cvsroot=texi2html&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_info/mini_ker/GNU-Free-Documentation-License.html?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_info/mini_ker/index.html?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_info/texi_cvs/cvs.2?cvsroot=texi2html&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_info/texi_cvs/cvs.passfirst?cvsroot=texi2html&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_info/texi_cvs/cvs.passtexi?cvsroot=texi2html&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_info/texi_cvs/cvs.texi?cvsroot=texi2html&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_info/texi_cvs/cvs.texi.first?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_info/texi_hello/hello.texi.first?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_info/texi_info-stnd/info-stnd.texi.first?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_info/texi_mini_ker/mini_ker.2?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_info/texi_mini_ker/mini_ker.passfirst?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_info/texi_mini_ker/mini_ker.passtexi?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_info/texi_mini_ker/mini_ker.texi?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_info/texi_mini_ker/mini_ker.texi.first?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_info/texi_texinfo/texinfo.texi.first?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/manuals/res_info/texinfo_xml/texinfo.xml?cvsroot=texi2html&r1=1.1&r2=1.2
Patches:
Index: res/ccvs/cvs.2
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/manuals/res/ccvs/cvs.2,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- res/ccvs/cvs.2 31 Jul 2009 11:09:36 -0000 1.2
+++ res/ccvs/cvs.2 2 Aug 2009 13:10:57 -0000 1.3
@@ -1 +1,2 @@
** macro `splitrcskeyword' already defined (l. 86) redefined (l. 97)
+** @copyleftnotice defined with 0 arguments should be invoked with {} (l. 136)
Index: res/ccvs_info/cvs.2
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/manuals/res/ccvs_info/cvs.2,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- res/ccvs_info/cvs.2 31 Jul 2009 11:09:36 -0000 1.2
+++ res/ccvs_info/cvs.2 2 Aug 2009 13:10:57 -0000 1.3
@@ -1 +1,10 @@
** macro `splitrcskeyword' already defined (l. 86) redefined (l. 103)
+** @copyleftnotice defined with 0 arguments should be invoked with {} (l. 136)
+** @copyleftnotice defined with 0 arguments should be invoked with {} (l. 153)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 8233)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 8487)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 8559)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 10123)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 10495)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 12953)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 13701)
Index: res/ccvs_mediawiki/cvs.2
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/manuals/res/ccvs_mediawiki/cvs.2,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- res/ccvs_mediawiki/cvs.2 31 Jul 2009 11:09:36 -0000 1.2
+++ res/ccvs_mediawiki/cvs.2 2 Aug 2009 13:10:57 -0000 1.3
@@ -1 +1,2 @@
** macro `splitrcskeyword' already defined (l. 86) redefined (l. 97)
+** @copyleftnotice defined with 0 arguments should be invoked with {} (l. 136)
Index: res/ccvs_mediawiki_nosplit/cvs.2
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res/ccvs_mediawiki_nosplit/cvs.2,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- res/ccvs_mediawiki_nosplit/cvs.2 31 Jul 2009 11:09:36 -0000 1.2
+++ res/ccvs_mediawiki_nosplit/cvs.2 2 Aug 2009 13:10:57 -0000 1.3
@@ -1 +1,2 @@
** macro `splitrcskeyword' already defined (l. 86) redefined (l. 97)
+** @copyleftnotice defined with 0 arguments should be invoked with {} (l. 136)
Index: res/hello/hello.html
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/manuals/res/hello/hello.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res/hello/hello.html 4 Jun 2009 22:58:05 -0000 1.1
+++ res/hello/hello.html 2 Aug 2009 13:10:57 -0000 1.2
@@ -402,7 +402,7 @@
<a name="GNU-Free-Documentation-License-1"></a>
<h1 class="appendix">A. GNU Free Documentation License</h1>
-<p align="center"> Version 1.3, 3 November 2008
+<p align="center">Version 1.3, 3 November 2008
</p>
<table><tr><td> </td><td><pre class="display">Copyright © 2000,
2001, 2002, 2007, 2008 Free Software Foundation, Inc.
Index: res/hello_nodes/GNU-Free-Documentation-License.html
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res/hello_nodes/GNU-Free-Documentation-License.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res/hello_nodes/GNU-Free-Documentation-License.html 4 Jun 2009 22:58:05
-0000 1.1
+++ res/hello_nodes/GNU-Free-Documentation-License.html 2 Aug 2009 13:10:57
-0000 1.2
@@ -76,7 +76,7 @@
<a name="GNU-Free-Documentation-License-1"></a>
<h1 class="appendix">A. GNU Free Documentation License</h1>
-<p align="center"> Version 1.3, 3 November 2008
+<p align="center">Version 1.3, 3 November 2008
</p>
<table><tr><td> </td><td><pre class="display">Copyright © 2000,
2001, 2002, 2007, 2008 Free Software Foundation, Inc.
Index: res/info-stnd/Copying-This-Manual.html
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res/info-stnd/Copying-This-Manual.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -b -r1.6 -r1.7
--- res/info-stnd/Copying-This-Manual.html 2 Apr 2009 09:15:25 -0000
1.6
+++ res/info-stnd/Copying-This-Manual.html 2 Aug 2009 13:10:58 -0000
1.7
@@ -109,7 +109,7 @@
<h2 class="appendixsec">A.1 GNU Free Documentation License</h2>
<a name="index-FDL_002c-GNU-Free-Documentation-License"></a>
-<p align="center"> Version 1.1, March 2000
+<p align="center">Version 1.1, March 2000
</p>
<table><tr><td> </td><td><pre class="display">Copyright © 2000 Free
Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
Index: res/mini_ker/GNU-Free-Documentation-License.html
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res/mini_ker/GNU-Free-Documentation-License.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -b -r1.8 -r1.9
--- res/mini_ker/GNU-Free-Documentation-License.html 2 Apr 2009 09:15:40
-0000 1.8
+++ res/mini_ker/GNU-Free-Documentation-License.html 2 Aug 2009 13:10:58
-0000 1.9
@@ -78,7 +78,7 @@
</ul>
<a name="index-FDL_002c-GNU-Free-Documentation-License"></a>
-<p align="center"> Version 1.1, March 2000
+<p align="center">Version 1.1, March 2000
</p>
<table><tr><td> </td><td><pre class="display">Copyright © 2000 Free
Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
Index: res/mini_ker/mini_ker.html
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/manuals/res/mini_ker/mini_ker.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -b -r1.9 -r1.10
--- res/mini_ker/mini_ker.html 25 Apr 2009 14:54:45 -0000 1.9
+++ res/mini_ker/mini_ker.html 2 Aug 2009 13:10:58 -0000 1.10
@@ -24,10 +24,10 @@
Send bugs and suggestions to <address@hidden>
-->
<head>
-<title>Miniker 102 manual: Miniker 102 manual</title>
+<title>Miniker 102 manual</title>
-<meta name="description" content="Miniker 102 manual: Miniker 102 manual">
-<meta name="keywords" content="Miniker 102 manual: Miniker 102 manual">
+<meta name="description" content="Miniker 102 manual">
+<meta name="keywords" content="Miniker 102 manual">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html">
Index: res/texi_cvs/cvs.2
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/manuals/res/texi_cvs/cvs.2,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- res/texi_cvs/cvs.2 31 Jul 2009 11:09:36 -0000 1.2
+++ res/texi_cvs/cvs.2 2 Aug 2009 13:10:58 -0000 1.3
@@ -1,2 +1,2 @@
** macro `splitrcskeyword' already defined (l. 86) redefined (l. 97)
-** macro `splitrcskeyword' already defined (l. 86) redefined (l. 97)
+** @copyleftnotice defined with 0 arguments should be invoked with {} (l. 136)
Index: res/texi_cvs/cvs.passfirst
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/manuals/res/texi_cvs/cvs.passfirst,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -b -r1.4 -r1.5
--- res/texi_cvs/cvs.passfirst 31 Jul 2009 11:09:36 -0000 1.4
+++ res/texi_cvs/cvs.passfirst 2 Aug 2009 13:10:58 -0000 1.5
@@ -1,5 +1,39 @@
cvs.texi(,2) @comment Documentation for CVS.
cvs.texi(,3) @setfilename cvs.info
+cvs.texi(,4) @macro copyleftnotice
+cvs.texi(,5) @noindent
+cvs.texi(,6) Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2000,
+cvs.texi(,7) 2001, 2002, 2003 Free Software Foundation,
Inc.
+cvs.texi(,8)
+cvs.texi(,9) @multitable @columnfractions .12 .88
+cvs.texi(,10) @item Portions
+cvs.texi(,11) @item @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003
Derek R. Price,
+cvs.texi(,12) @item @tab Copyright @copyright{} 2002, 2003 Ximbiot
<http://ximbiot.com>,
+cvs.texi(,13) @item @tab Copyright @copyright{} 1992, 1993, 1999 Signum
Support AB,
+cvs.texi(,14) @item @tab and Copyright @copyright{} others.
+cvs.texi(,15) @end multitable
+cvs.texi(,16)
+cvs.texi(,17) @ignore
+cvs.texi(,18) Permission is granted to process this file through Tex and print
the
+cvs.texi(,19) results, provided the printed document carries copying permission
+cvs.texi(,20) notice identical to this one except for the removal of this
paragraph
+cvs.texi(,21) (this paragraph not being relevant to the printed manual).
+cvs.texi(,22)
+cvs.texi(,23) @end ignore
+cvs.texi(,24) Permission is granted to make and distribute verbatim copies of
+cvs.texi(,25) this manual provided the copyright notice and this permission
notice
+cvs.texi(,26) are preserved on all copies.
+cvs.texi(,27)
+cvs.texi(,28) Permission is granted to copy and distribute modified versions
of this
+cvs.texi(,29) manual under the conditions for verbatim copying, provided also
that the
+cvs.texi(,30) entire resulting derived work is distributed under the terms of a
+cvs.texi(,31) permission notice identical to this one.
+cvs.texi(,32)
+cvs.texi(,33) Permission is granted to copy and distribute translations of
this manual
+cvs.texi(,34) into another language, under the above conditions for modified
versions,
+cvs.texi(,35) except that this permission notice may be stated in a translation
+cvs.texi(,36) approved by the Free Software Foundation.
+cvs.texi(,37) @end macro
cvs.texi(,38)
cvs.texi(,39) @comment This file is part of the CVS distribution.
cvs.texi(,40)
@@ -51,8 +85,14 @@
cvs.texi(,83) @c @asis when generating info and dvi, and by <i></i> in the
generated html,
cvs.texi(,84) @c such that keywords are not expanded in the generated html.
cvs.texi(,85)
+cvs.texi(,86) @macro splitrcskeyword {arg}
+cvs.texi(,87) \arg\
+cvs.texi(,88) @end macro
cvs.texi(,89)
cvs.texi(,95)
+cvs.texi(,97) @macro splitrcskeyword {arg}
+cvs.texi(,98) @i{}\arg\
+cvs.texi(,99) @end macro
cvs.texi(,101)
cvs.texi(,107)
cvs.texi(,108) @dircategory GNU Packages
Index: res/texi_cvs/cvs.passtexi
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/manuals/res/texi_cvs/cvs.passtexi,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -b -r1.5 -r1.6
--- res/texi_cvs/cvs.passtexi 31 Jul 2009 11:09:37 -0000 1.5
+++ res/texi_cvs/cvs.passtexi 2 Aug 2009 13:10:59 -0000 1.6
@@ -1,5 +1,39 @@
cvs.texi(,2) @comment Documentation for CVS.
cvs.texi(,3) @setfilename cvs.info
+cvs.texi(,4) @macro copyleftnotice
+cvs.texi(,5) @noindent
+cvs.texi(,6) Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2000,
+cvs.texi(,7) 2001, 2002, 2003 Free Software Foundation,
Inc.
+cvs.texi(,8)
+cvs.texi(,9) @multitable @columnfractions .12 .88
+cvs.texi(,10) @item Portions
+cvs.texi(,11) @item @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003
Derek R. Price,
+cvs.texi(,12) @item @tab Copyright @copyright{} 2002, 2003 Ximbiot
<http://ximbiot.com>,
+cvs.texi(,13) @item @tab Copyright @copyright{} 1992, 1993, 1999 Signum
Support AB,
+cvs.texi(,14) @item @tab and Copyright @copyright{} others.
+cvs.texi(,15) @end multitable
+cvs.texi(,16)
+cvs.texi(,17) @ignore
+cvs.texi(,18) Permission is granted to process this file through Tex and print
the
+cvs.texi(,19) results, provided the printed document carries copying permission
+cvs.texi(,20) notice identical to this one except for the removal of this
paragraph
+cvs.texi(,21) (this paragraph not being relevant to the printed manual).
+cvs.texi(,22)
+cvs.texi(,23) @end ignore
+cvs.texi(,24) Permission is granted to make and distribute verbatim copies of
+cvs.texi(,25) this manual provided the copyright notice and this permission
notice
+cvs.texi(,26) are preserved on all copies.
+cvs.texi(,27)
+cvs.texi(,28) Permission is granted to copy and distribute modified versions
of this
+cvs.texi(,29) manual under the conditions for verbatim copying, provided also
that the
+cvs.texi(,30) entire resulting derived work is distributed under the terms of a
+cvs.texi(,31) permission notice identical to this one.
+cvs.texi(,32)
+cvs.texi(,33) Permission is granted to copy and distribute translations of
this manual
+cvs.texi(,34) into another language, under the above conditions for modified
versions,
+cvs.texi(,35) except that this permission notice may be stated in a translation
+cvs.texi(,36) approved by the Free Software Foundation.
+cvs.texi(,37) @end macro
cvs.texi(,38)
cvs.texi(,39) @comment This file is part of the CVS distribution.
cvs.texi(,40)
@@ -51,8 +85,14 @@
cvs.texi(,83) @c @asis when generating info and dvi, and by <i></i> in the
generated html,
cvs.texi(,84) @c such that keywords are not expanded in the generated html.
cvs.texi(,85)
+cvs.texi(,86) @macro splitrcskeyword {arg}
+cvs.texi(,87) \arg\
+cvs.texi(,88) @end macro
cvs.texi(,89)
cvs.texi(,95)
+cvs.texi(,97) @macro splitrcskeyword {arg}
+cvs.texi(,98) @i{}\arg\
+cvs.texi(,99) @end macro
cvs.texi(,101)
cvs.texi(,107)
cvs.texi(,108) @dircategory GNU Packages
Index: res/texi_cvs/cvs.texi
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/manuals/res/texi_cvs/cvs.texi,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -b -r1.4 -r1.5
--- res/texi_cvs/cvs.texi 31 Jul 2009 11:09:37 -0000 1.4
+++ res/texi_cvs/cvs.texi 2 Aug 2009 13:10:59 -0000 1.5
@@ -1,6 +1,40 @@
\input texinfo @c -*-texinfo-*-
@comment Documentation for CVS.
@setfilename cvs.info
address@hidden copyleftnotice
address@hidden
+Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
+ 2001, 2002, 2003 Free Software Foundation, Inc.
+
address@hidden @columnfractions .12 .88
address@hidden Portions
address@hidden @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003 Derek
R. Price,
address@hidden @tab Copyright @copyright{} 2002, 2003 Ximbiot
<http://ximbiot.com>,
address@hidden @tab Copyright @copyright{} 1992, 1993, 1999 Signum Support AB,
address@hidden @tab and Copyright @copyright{} others.
address@hidden multitable
+
address@hidden
+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).
+
address@hidden ignore
+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 also 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 Free Software Foundation.
address@hidden macro
@comment This file is part of the CVS distribution.
@@ -52,8 +86,14 @@
@c @asis when generating info and dvi, and by <i></i> in the generated html,
@c such that keywords are not expanded in the generated html.
address@hidden splitrcskeyword {arg}
+ \arg\
address@hidden macro
address@hidden splitrcskeyword {arg}
address@hidden
address@hidden macro
@dircategory GNU Packages
Index: res/texi_mini_ker/mini_ker.2
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res/texi_mini_ker/mini_ker.2,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res/texi_mini_ker/mini_ker.2 18 Aug 2008 18:05:16 -0000 1.1
+++ res/texi_mini_ker/mini_ker.2 2 Aug 2009 13:10:59 -0000 1.2
@@ -1,2 +1 @@
*** Duplicate node found: Top (l. 72)
-*** Duplicate node found: Top (l. 72)
Index: res/texi_mini_ker/mini_ker.passfirst
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res/texi_mini_ker/mini_ker.passfirst,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -b -r1.4 -r1.5
--- res/texi_mini_ker/mini_ker.passfirst 25 Apr 2009 14:54:46 -0000
1.4
+++ res/texi_mini_ker/mini_ker.passfirst 2 Aug 2009 13:10:59 -0000
1.5
@@ -9,6 +9,9 @@
mini_ker.texi(,17)
mini_ker.texi(,18) @set myurl
@url{http://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}
mini_ker.texi(,19)
+mini_ker.texi(,20) @macro Minik{}
+mini_ker.texi(,21) Miniker
+mini_ker.texi(,22) @end macro
mini_ker.texi(,23)
mini_ker.texi(Minik,24) @settitle Miniker 102 manual
mini_ker.texi(,25)
Index: res/texi_mini_ker/mini_ker.passtexi
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res/texi_mini_ker/mini_ker.passtexi,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -b -r1.5 -r1.6
--- res/texi_mini_ker/mini_ker.passtexi 25 Apr 2009 14:54:47 -0000 1.5
+++ res/texi_mini_ker/mini_ker.passtexi 2 Aug 2009 13:11:00 -0000 1.6
@@ -9,6 +9,9 @@
mini_ker.texi(,17)
mini_ker.texi(,18) @set myurl
@url{http://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}
mini_ker.texi(,19)
+mini_ker.texi(,20) @macro Minik{}
+mini_ker.texi(,21) Miniker
+mini_ker.texi(,22) @end macro
mini_ker.texi(,23)
mini_ker.texi(Minik,24) @settitle mini_ker.texi(Minik,24) Miniker 102 manual
mini_ker.texi(,25)
Index: res/texi_mini_ker/mini_ker.texi
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res/texi_mini_ker/mini_ker.texi,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -b -r1.4 -r1.5
--- res/texi_mini_ker/mini_ker.texi 25 Apr 2009 14:54:47 -0000 1.4
+++ res/texi_mini_ker/mini_ker.texi 2 Aug 2009 13:11:00 -0000 1.5
@@ -10,6 +10,9 @@
@set myurl
@url{http://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}
address@hidden Minik{}
+Miniker
address@hidden macro
@settitle Miniker 102 manual
Index: res/texinfo/texinfo_31.html
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res/texinfo/texinfo_31.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -b -r1.6 -r1.7
--- res/texinfo/texinfo_31.html 2 Apr 2009 09:15:56 -0000 1.6
+++ res/texinfo/texinfo_31.html 2 Aug 2009 13:11:00 -0000 1.7
@@ -108,7 +108,7 @@
<h2 class="appendixsec">J.1 GNU Free Documentation License</h2>
<a name="index-FDL_002c-GNU-Free-Documentation-License"></a>
-<p align="center"> Version 1.1, March 2000
+<p align="center">Version 1.1, March 2000
</p>
<table><tr><td> </td><td><pre class="display">Copyright © 2000 Free
Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
Index: res/texinfo_nodes/GNU-Free-Documentation-License.html
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res/texinfo_nodes/GNU-Free-Documentation-License.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -b -r1.6 -r1.7
--- res/texinfo_nodes/GNU-Free-Documentation-License.html 2 Apr 2009
09:16:06 -0000 1.6
+++ res/texinfo_nodes/GNU-Free-Documentation-License.html 2 Aug 2009
13:11:00 -0000 1.7
@@ -82,7 +82,7 @@
<h2 class="appendixsec">J.1 GNU Free Documentation License</h2>
<a name="index-FDL_002c-GNU-Free-Documentation-License"></a>
-<p align="center"> Version 1.1, March 2000
+<p align="center">Version 1.1, March 2000
</p>
<table><tr><td> </td><td><pre class="display">Copyright © 2000 Free
Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
Index: res/texinfo_xml/texinfo.xml
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res/texinfo_xml/texinfo.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res/texinfo_xml/texinfo.xml 28 Jul 2009 18:42:45 -0000 1.1
+++ res/texinfo_xml/texinfo.xml 2 Aug 2009 13:11:00 -0000 1.2
@@ -16,9 +16,6 @@
<!-- Put everything except function (command, in this case) names in one -->
<!-- index (arbitrarily chosen to be the concept index). -->
-
-
-
<footnotestyle></footnotestyle><!-- finalout -->
<!-- %**end of header -->
@@ -19528,7 +19525,7 @@
<appendixsec>
<title>GNU Free Documentation License</title>
-<para><indexterm index="cp">FDL, GNU Free Documentation
License</indexterm></para><center><para> Version 1.1, March 2000
+<para><indexterm index="cp">FDL, GNU Free Documentation
License</indexterm></para><center><para>Version 1.1, March 2000
</para></center>
<display xml:space="preserve">Copyright ©right; 2000 Free Software
Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
Index: res_all/ccvs/cvs.2
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/manuals/res_all/ccvs/cvs.2,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- res_all/ccvs/cvs.2 31 Jul 2009 11:09:38 -0000 1.2
+++ res_all/ccvs/cvs.2 2 Aug 2009 13:11:00 -0000 1.3
@@ -0,0 +1 @@
+** @copyleftnotice defined with 0 arguments should be invoked with {} (l. 136)
Index: res_all/ccvs_info/cvs.2
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/manuals/res_all/ccvs_info/cvs.2,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- res_all/ccvs_info/cvs.2 31 Jul 2009 11:09:38 -0000 1.2
+++ res_all/ccvs_info/cvs.2 2 Aug 2009 13:11:01 -0000 1.3
@@ -1 +1,10 @@
** macro `splitrcskeyword' already defined (l. 86) redefined (l. 103)
+** @copyleftnotice defined with 0 arguments should be invoked with {} (l. 136)
+** @copyleftnotice defined with 0 arguments should be invoked with {} (l. 153)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 8233)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 8487)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 8559)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 10123)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 10495)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 12953)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 13701)
Index: res_all/ccvs_mediawiki/cvs.2
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res_all/ccvs_mediawiki/cvs.2,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- res_all/ccvs_mediawiki/cvs.2 31 Jul 2009 11:09:38 -0000 1.2
+++ res_all/ccvs_mediawiki/cvs.2 2 Aug 2009 13:11:01 -0000 1.3
@@ -1 +1,2 @@
** macro `splitrcskeyword' already defined (l. 86) redefined (l. 97)
+** @copyleftnotice defined with 0 arguments should be invoked with {} (l. 136)
Index: res_all/ccvs_mediawiki_nosplit/cvs.2
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res_all/ccvs_mediawiki_nosplit/cvs.2,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- res_all/ccvs_mediawiki_nosplit/cvs.2 31 Jul 2009 11:09:38 -0000
1.2
+++ res_all/ccvs_mediawiki_nosplit/cvs.2 2 Aug 2009 13:11:01 -0000
1.3
@@ -1 +1,2 @@
** macro `splitrcskeyword' already defined (l. 86) redefined (l. 97)
+** @copyleftnotice defined with 0 arguments should be invoked with {} (l. 136)
Index: res_all/mini_ker/GNU-Free-Documentation-License.html
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res_all/mini_ker/GNU-Free-Documentation-License.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_all/mini_ker/GNU-Free-Documentation-License.html 31 Jul 2009
10:16:56 -0000 1.1
+++ res_all/mini_ker/GNU-Free-Documentation-License.html 2 Aug 2009
13:11:01 -0000 1.2
@@ -84,7 +84,7 @@
</ul>
<a name="index-FDL_002c-GNU-Free-Documentation-License"></a>
-<p align="center"> Version 1.1, March 2000
+<p align="center">Version 1.1, March 2000
</p>
<table><tr><td> </td><td><pre class="display">Copyright © 2000 Free
Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
Index: res_all/mini_ker/index.html
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res_all/mini_ker/index.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_all/mini_ker/index.html 31 Jul 2009 10:16:58 -0000 1.1
+++ res_all/mini_ker/index.html 2 Aug 2009 13:11:01 -0000 1.2
@@ -24,10 +24,10 @@
Send bugs and suggestions to <address@hidden>
-->
<head>
-<title>Miniker 102 manual: Miniker 102 manual</title>
+<title>Miniker 102 manual</title>
-<meta name="description" content="Miniker 102 manual: Miniker 102 manual">
-<meta name="keywords" content="Miniker 102 manual: Miniker 102 manual">
+<meta name="description" content="Miniker 102 manual">
+<meta name="keywords" content="Miniker 102 manual">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html">
Index: res_all/texi_cvs/cvs.2
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/manuals/res_all/texi_cvs/cvs.2,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_all/texi_cvs/cvs.2 31 Jul 2009 10:16:58 -0000 1.1
+++ res_all/texi_cvs/cvs.2 2 Aug 2009 13:11:01 -0000 1.2
@@ -0,0 +1 @@
+** @copyleftnotice defined with 0 arguments should be invoked with {} (l. 136)
Index: res_all/texi_cvs/cvs.passfirst
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res_all/texi_cvs/cvs.passfirst,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- res_all/texi_cvs/cvs.passfirst 31 Jul 2009 11:09:38 -0000 1.2
+++ res_all/texi_cvs/cvs.passfirst 2 Aug 2009 13:11:01 -0000 1.3
@@ -1,5 +1,39 @@
cvs.texi(,2) @comment Documentation for CVS.
cvs.texi(,3) @setfilename cvs.info
+cvs.texi(,4) @macro copyleftnotice
+cvs.texi(,5) @noindent
+cvs.texi(,6) Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2000,
+cvs.texi(,7) 2001, 2002, 2003 Free Software Foundation,
Inc.
+cvs.texi(,8)
+cvs.texi(,9) @multitable @columnfractions .12 .88
+cvs.texi(,10) @item Portions
+cvs.texi(,11) @item @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003
Derek R. Price,
+cvs.texi(,12) @item @tab Copyright @copyright{} 2002, 2003 Ximbiot
<http://ximbiot.com>,
+cvs.texi(,13) @item @tab Copyright @copyright{} 1992, 1993, 1999 Signum
Support AB,
+cvs.texi(,14) @item @tab and Copyright @copyright{} others.
+cvs.texi(,15) @end multitable
+cvs.texi(,16)
+cvs.texi(,17) @ignore
+cvs.texi(,18) Permission is granted to process this file through Tex and print
the
+cvs.texi(,19) results, provided the printed document carries copying permission
+cvs.texi(,20) notice identical to this one except for the removal of this
paragraph
+cvs.texi(,21) (this paragraph not being relevant to the printed manual).
+cvs.texi(,22)
+cvs.texi(,23) @end ignore
+cvs.texi(,24) Permission is granted to make and distribute verbatim copies of
+cvs.texi(,25) this manual provided the copyright notice and this permission
notice
+cvs.texi(,26) are preserved on all copies.
+cvs.texi(,27)
+cvs.texi(,28) Permission is granted to copy and distribute modified versions
of this
+cvs.texi(,29) manual under the conditions for verbatim copying, provided also
that the
+cvs.texi(,30) entire resulting derived work is distributed under the terms of a
+cvs.texi(,31) permission notice identical to this one.
+cvs.texi(,32)
+cvs.texi(,33) Permission is granted to copy and distribute translations of
this manual
+cvs.texi(,34) into another language, under the above conditions for modified
versions,
+cvs.texi(,35) except that this permission notice may be stated in a translation
+cvs.texi(,36) approved by the Free Software Foundation.
+cvs.texi(,37) @end macro
cvs.texi(,38)
cvs.texi(,39) @comment This file is part of the CVS distribution.
cvs.texi(,40)
@@ -51,6 +85,9 @@
cvs.texi(,83) @c @asis when generating info and dvi, and by <i></i> in the
generated html,
cvs.texi(,84) @c such that keywords are not expanded in the generated html.
cvs.texi(,85)
+cvs.texi(,86) @macro splitrcskeyword {arg}
+cvs.texi(,87) \arg\
+cvs.texi(,88) @end macro
cvs.texi(,89)
cvs.texi(,95)
cvs.texi(,101)
Index: res_all/texi_cvs/cvs.passtexi
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res_all/texi_cvs/cvs.passtexi,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- res_all/texi_cvs/cvs.passtexi 31 Jul 2009 11:09:38 -0000 1.2
+++ res_all/texi_cvs/cvs.passtexi 2 Aug 2009 13:11:01 -0000 1.3
@@ -1,5 +1,39 @@
cvs.texi(,2) @comment Documentation for CVS.
cvs.texi(,3) @setfilename cvs.info
+cvs.texi(,4) @macro copyleftnotice
+cvs.texi(,5) @noindent
+cvs.texi(,6) Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2000,
+cvs.texi(,7) 2001, 2002, 2003 Free Software Foundation,
Inc.
+cvs.texi(,8)
+cvs.texi(,9) @multitable @columnfractions .12 .88
+cvs.texi(,10) @item Portions
+cvs.texi(,11) @item @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003
Derek R. Price,
+cvs.texi(,12) @item @tab Copyright @copyright{} 2002, 2003 Ximbiot
<http://ximbiot.com>,
+cvs.texi(,13) @item @tab Copyright @copyright{} 1992, 1993, 1999 Signum
Support AB,
+cvs.texi(,14) @item @tab and Copyright @copyright{} others.
+cvs.texi(,15) @end multitable
+cvs.texi(,16)
+cvs.texi(,17) @ignore
+cvs.texi(,18) Permission is granted to process this file through Tex and print
the
+cvs.texi(,19) results, provided the printed document carries copying permission
+cvs.texi(,20) notice identical to this one except for the removal of this
paragraph
+cvs.texi(,21) (this paragraph not being relevant to the printed manual).
+cvs.texi(,22)
+cvs.texi(,23) @end ignore
+cvs.texi(,24) Permission is granted to make and distribute verbatim copies of
+cvs.texi(,25) this manual provided the copyright notice and this permission
notice
+cvs.texi(,26) are preserved on all copies.
+cvs.texi(,27)
+cvs.texi(,28) Permission is granted to copy and distribute modified versions
of this
+cvs.texi(,29) manual under the conditions for verbatim copying, provided also
that the
+cvs.texi(,30) entire resulting derived work is distributed under the terms of a
+cvs.texi(,31) permission notice identical to this one.
+cvs.texi(,32)
+cvs.texi(,33) Permission is granted to copy and distribute translations of
this manual
+cvs.texi(,34) into another language, under the above conditions for modified
versions,
+cvs.texi(,35) except that this permission notice may be stated in a translation
+cvs.texi(,36) approved by the Free Software Foundation.
+cvs.texi(,37) @end macro
cvs.texi(,38)
cvs.texi(,39) @comment This file is part of the CVS distribution.
cvs.texi(,40)
@@ -51,6 +85,9 @@
cvs.texi(,83) @c @asis when generating info and dvi, and by <i></i> in the
generated html,
cvs.texi(,84) @c such that keywords are not expanded in the generated html.
cvs.texi(,85)
+cvs.texi(,86) @macro splitrcskeyword {arg}
+cvs.texi(,87) \arg\
+cvs.texi(,88) @end macro
cvs.texi(,89)
cvs.texi(,95)
cvs.texi(,101)
Index: res_all/texi_cvs/cvs.texi
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/manuals/res_all/texi_cvs/cvs.texi,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- res_all/texi_cvs/cvs.texi 31 Jul 2009 11:09:39 -0000 1.2
+++ res_all/texi_cvs/cvs.texi 2 Aug 2009 13:11:02 -0000 1.3
@@ -1,6 +1,40 @@
\input texinfo @c -*-texinfo-*-
@comment Documentation for CVS.
@setfilename cvs.info
address@hidden copyleftnotice
address@hidden
+Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
+ 2001, 2002, 2003 Free Software Foundation, Inc.
+
address@hidden @columnfractions .12 .88
address@hidden Portions
address@hidden @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003 Derek
R. Price,
address@hidden @tab Copyright @copyright{} 2002, 2003 Ximbiot
<http://ximbiot.com>,
address@hidden @tab Copyright @copyright{} 1992, 1993, 1999 Signum Support AB,
address@hidden @tab and Copyright @copyright{} others.
address@hidden multitable
+
address@hidden
+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).
+
address@hidden ignore
+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 also 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 Free Software Foundation.
address@hidden macro
@comment This file is part of the CVS distribution.
@@ -52,6 +86,9 @@
@c @asis when generating info and dvi, and by <i></i> in the generated html,
@c such that keywords are not expanded in the generated html.
address@hidden splitrcskeyword {arg}
+ \arg\
address@hidden macro
Index: res_all/texi_mini_ker/mini_ker.2
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res_all/texi_mini_ker/mini_ker.2,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_all/texi_mini_ker/mini_ker.2 31 Jul 2009 10:16:59 -0000 1.1
+++ res_all/texi_mini_ker/mini_ker.2 2 Aug 2009 13:11:02 -0000 1.2
@@ -1,2 +1 @@
*** Duplicate node found: Top (l. 72)
-*** Duplicate node found: Top (l. 72)
Index: res_all/texi_mini_ker/mini_ker.passfirst
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res_all/texi_mini_ker/mini_ker.passfirst,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_all/texi_mini_ker/mini_ker.passfirst 31 Jul 2009 10:16:59 -0000
1.1
+++ res_all/texi_mini_ker/mini_ker.passfirst 2 Aug 2009 13:11:02 -0000
1.2
@@ -9,6 +9,9 @@
mini_ker.texi(,17)
mini_ker.texi(,18) @set myurl
@url{http://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}
mini_ker.texi(,19)
+mini_ker.texi(,20) @macro Minik{}
+mini_ker.texi(,21) Miniker
+mini_ker.texi(,22) @end macro
mini_ker.texi(,23)
mini_ker.texi(Minik,24) @settitle Miniker 102 manual
mini_ker.texi(,25)
Index: res_all/texi_mini_ker/mini_ker.passtexi
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res_all/texi_mini_ker/mini_ker.passtexi,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_all/texi_mini_ker/mini_ker.passtexi 31 Jul 2009 10:16:59 -0000
1.1
+++ res_all/texi_mini_ker/mini_ker.passtexi 2 Aug 2009 13:11:02 -0000
1.2
@@ -9,6 +9,9 @@
mini_ker.texi(,17)
mini_ker.texi(,18) @set myurl
@url{http://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}
mini_ker.texi(,19)
+mini_ker.texi(,20) @macro Minik{}
+mini_ker.texi(,21) Miniker
+mini_ker.texi(,22) @end macro
mini_ker.texi(,23)
mini_ker.texi(Minik,24) @settitle mini_ker.texi(Minik,24) Miniker 102 manual
mini_ker.texi(,25)
Index: res_all/texi_mini_ker/mini_ker.texi
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res_all/texi_mini_ker/mini_ker.texi,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_all/texi_mini_ker/mini_ker.texi 31 Jul 2009 10:17:00 -0000 1.1
+++ res_all/texi_mini_ker/mini_ker.texi 2 Aug 2009 13:11:02 -0000 1.2
@@ -10,6 +10,9 @@
@set myurl
@url{http://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}
address@hidden Minik{}
+Miniker
address@hidden macro
@settitle Miniker 102 manual
Index: res_all/texinfo_xml/texinfo.xml
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res_all/texinfo_xml/texinfo.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_all/texinfo_xml/texinfo.xml 28 Jul 2009 18:42:47 -0000 1.1
+++ res_all/texinfo_xml/texinfo.xml 2 Aug 2009 13:11:03 -0000 1.2
@@ -16,9 +16,6 @@
<!-- Put everything except function (command, in this case) names in one -->
<!-- index (arbitrarily chosen to be the concept index). -->
-
-
-
<footnotestyle></footnotestyle><!-- finalout -->
<!-- %**end of header -->
@@ -19528,7 +19525,7 @@
<appendixsec>
<title>GNU Free Documentation License</title>
-<para><indexterm index="cp">FDL, GNU Free Documentation
License</indexterm></para><center><para> Version 1.1, March 2000
+<para><indexterm index="cp">FDL, GNU Free Documentation
License</indexterm></para><center><para>Version 1.1, March 2000
</para></center>
<display xml:space="preserve">Copyright ©right; 2000 Free Software
Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
Index: res_info/ccvs/cvs.2
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/manuals/res_info/ccvs/cvs.2,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- res_info/ccvs/cvs.2 31 Jul 2009 11:09:39 -0000 1.2
+++ res_info/ccvs/cvs.2 2 Aug 2009 13:11:03 -0000 1.3
@@ -1 +1,10 @@
** macro `splitrcskeyword' already defined (l. 86) redefined (l. 103)
+** @copyleftnotice defined with 0 arguments should be invoked with {} (l. 136)
+** @copyleftnotice defined with 0 arguments should be invoked with {} (l. 153)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 8233)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 8487)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 8559)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 10123)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 10495)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 12953)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 13701)
Index: res_info/ccvs_info/cvs.2
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/manuals/res_info/ccvs_info/cvs.2,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- res_info/ccvs_info/cvs.2 31 Jul 2009 11:09:39 -0000 1.2
+++ res_info/ccvs_info/cvs.2 2 Aug 2009 13:11:03 -0000 1.3
@@ -1 +1,10 @@
** macro `splitrcskeyword' already defined (l. 86) redefined (l. 103)
+** @copyleftnotice defined with 0 arguments should be invoked with {} (l. 136)
+** @copyleftnotice defined with 0 arguments should be invoked with {} (l. 153)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 8233)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 8487)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 8559)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 10123)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 10495)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 12953)
+** @strong{Note...} produces a spurious cross-reference in Info; reword to
avoid that. (l. 13701)
Index: res_info/ccvs_mediawiki/cvs.2
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res_info/ccvs_mediawiki/cvs.2,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- res_info/ccvs_mediawiki/cvs.2 31 Jul 2009 11:09:39 -0000 1.2
+++ res_info/ccvs_mediawiki/cvs.2 2 Aug 2009 13:11:03 -0000 1.3
@@ -1 +1,2 @@
** macro `splitrcskeyword' already defined (l. 86) redefined (l. 97)
+** @copyleftnotice defined with 0 arguments should be invoked with {} (l. 136)
Index: res_info/ccvs_mediawiki_nosplit/cvs.2
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res_info/ccvs_mediawiki_nosplit/cvs.2,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- res_info/ccvs_mediawiki_nosplit/cvs.2 31 Jul 2009 11:09:39 -0000
1.2
+++ res_info/ccvs_mediawiki_nosplit/cvs.2 2 Aug 2009 13:11:03 -0000
1.3
@@ -1 +1,2 @@
** macro `splitrcskeyword' already defined (l. 86) redefined (l. 97)
+** @copyleftnotice defined with 0 arguments should be invoked with {} (l. 136)
Index: res_info/mini_ker/GNU-Free-Documentation-License.html
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res_info/mini_ker/GNU-Free-Documentation-License.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_info/mini_ker/GNU-Free-Documentation-License.html 31 Jul 2009
10:17:17 -0000 1.1
+++ res_info/mini_ker/GNU-Free-Documentation-License.html 2 Aug 2009
13:11:03 -0000 1.2
@@ -84,7 +84,7 @@
</ul>
<a name="index-FDL_002c-GNU-Free-Documentation-License"></a>
-<p align="center"> Version 1.1, March 2000
+<p align="center">Version 1.1, March 2000
</p>
<table><tr><td> </td><td><pre class="display">Copyright © 2000 Free
Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
Index: res_info/mini_ker/index.html
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res_info/mini_ker/index.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_info/mini_ker/index.html 31 Jul 2009 10:17:19 -0000 1.1
+++ res_info/mini_ker/index.html 2 Aug 2009 13:11:03 -0000 1.2
@@ -24,10 +24,10 @@
Send bugs and suggestions to <address@hidden>
-->
<head>
-<title>Miniker 102 manual: Miniker 102 manual</title>
+<title>Miniker 102 manual</title>
-<meta name="description" content="Miniker 102 manual: Miniker 102 manual">
-<meta name="keywords" content="Miniker 102 manual: Miniker 102 manual">
+<meta name="description" content="Miniker 102 manual">
+<meta name="keywords" content="Miniker 102 manual">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html">
Index: res_info/texi_cvs/cvs.2
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/manuals/res_info/texi_cvs/cvs.2,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- res_info/texi_cvs/cvs.2 31 Jul 2009 11:09:39 -0000 1.2
+++ res_info/texi_cvs/cvs.2 2 Aug 2009 13:11:04 -0000 1.3
@@ -1,2 +1,3 @@
** macro `splitrcskeyword' already defined (l. 86) redefined (l. 103)
-** macro `splitrcskeyword' already defined (l. 86) redefined (l. 103)
+** @copyleftnotice defined with 0 arguments should be invoked with {} (l. 136)
+** @copyleftnotice defined with 0 arguments should be invoked with {} (l. 153)
Index: res_info/texi_cvs/cvs.passfirst
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res_info/texi_cvs/cvs.passfirst,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- res_info/texi_cvs/cvs.passfirst 31 Jul 2009 11:09:39 -0000 1.2
+++ res_info/texi_cvs/cvs.passfirst 2 Aug 2009 13:11:04 -0000 1.3
@@ -1,5 +1,39 @@
cvs.texi(,2) @comment Documentation for CVS.
cvs.texi(,3) @setfilename cvs.info
+cvs.texi(,4) @macro copyleftnotice
+cvs.texi(,5) @noindent
+cvs.texi(,6) Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2000,
+cvs.texi(,7) 2001, 2002, 2003 Free Software Foundation,
Inc.
+cvs.texi(,8)
+cvs.texi(,9) @multitable @columnfractions .12 .88
+cvs.texi(,10) @item Portions
+cvs.texi(,11) @item @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003
Derek R. Price,
+cvs.texi(,12) @item @tab Copyright @copyright{} 2002, 2003 Ximbiot
<http://ximbiot.com>,
+cvs.texi(,13) @item @tab Copyright @copyright{} 1992, 1993, 1999 Signum
Support AB,
+cvs.texi(,14) @item @tab and Copyright @copyright{} others.
+cvs.texi(,15) @end multitable
+cvs.texi(,16)
+cvs.texi(,17) @ignore
+cvs.texi(,18) Permission is granted to process this file through Tex and print
the
+cvs.texi(,19) results, provided the printed document carries copying permission
+cvs.texi(,20) notice identical to this one except for the removal of this
paragraph
+cvs.texi(,21) (this paragraph not being relevant to the printed manual).
+cvs.texi(,22)
+cvs.texi(,23) @end ignore
+cvs.texi(,24) Permission is granted to make and distribute verbatim copies of
+cvs.texi(,25) this manual provided the copyright notice and this permission
notice
+cvs.texi(,26) are preserved on all copies.
+cvs.texi(,27)
+cvs.texi(,28) Permission is granted to copy and distribute modified versions
of this
+cvs.texi(,29) manual under the conditions for verbatim copying, provided also
that the
+cvs.texi(,30) entire resulting derived work is distributed under the terms of a
+cvs.texi(,31) permission notice identical to this one.
+cvs.texi(,32)
+cvs.texi(,33) Permission is granted to copy and distribute translations of
this manual
+cvs.texi(,34) into another language, under the above conditions for modified
versions,
+cvs.texi(,35) except that this permission notice may be stated in a translation
+cvs.texi(,36) approved by the Free Software Foundation.
+cvs.texi(,37) @end macro
cvs.texi(,38)
cvs.texi(,39) @comment This file is part of the CVS distribution.
cvs.texi(,40)
@@ -51,9 +85,15 @@
cvs.texi(,83) @c @asis when generating info and dvi, and by <i></i> in the
generated html,
cvs.texi(,84) @c such that keywords are not expanded in the generated html.
cvs.texi(,85)
+cvs.texi(,86) @macro splitrcskeyword {arg}
+cvs.texi(,87) \arg\
+cvs.texi(,88) @end macro
cvs.texi(,89)
cvs.texi(,95)
cvs.texi(,101)
+cvs.texi(,103) @macro splitrcskeyword {arg}
+cvs.texi(,104) \arg\
+cvs.texi(,105) @end macro
cvs.texi(,107)
cvs.texi(,108) @dircategory GNU Packages
cvs.texi(,109) @direntry
Index: res_info/texi_cvs/cvs.passtexi
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res_info/texi_cvs/cvs.passtexi,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- res_info/texi_cvs/cvs.passtexi 31 Jul 2009 11:09:39 -0000 1.2
+++ res_info/texi_cvs/cvs.passtexi 2 Aug 2009 13:11:04 -0000 1.3
@@ -1,5 +1,39 @@
cvs.texi(,2) @comment Documentation for CVS.
cvs.texi(,3) @setfilename cvs.info
+cvs.texi(,4) @macro copyleftnotice
+cvs.texi(,5) @noindent
+cvs.texi(,6) Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2000,
+cvs.texi(,7) 2001, 2002, 2003 Free Software Foundation,
Inc.
+cvs.texi(,8)
+cvs.texi(,9) @multitable @columnfractions .12 .88
+cvs.texi(,10) @item Portions
+cvs.texi(,11) @item @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003
Derek R. Price,
+cvs.texi(,12) @item @tab Copyright @copyright{} 2002, 2003 Ximbiot
<http://ximbiot.com>,
+cvs.texi(,13) @item @tab Copyright @copyright{} 1992, 1993, 1999 Signum
Support AB,
+cvs.texi(,14) @item @tab and Copyright @copyright{} others.
+cvs.texi(,15) @end multitable
+cvs.texi(,16)
+cvs.texi(,17) @ignore
+cvs.texi(,18) Permission is granted to process this file through Tex and print
the
+cvs.texi(,19) results, provided the printed document carries copying permission
+cvs.texi(,20) notice identical to this one except for the removal of this
paragraph
+cvs.texi(,21) (this paragraph not being relevant to the printed manual).
+cvs.texi(,22)
+cvs.texi(,23) @end ignore
+cvs.texi(,24) Permission is granted to make and distribute verbatim copies of
+cvs.texi(,25) this manual provided the copyright notice and this permission
notice
+cvs.texi(,26) are preserved on all copies.
+cvs.texi(,27)
+cvs.texi(,28) Permission is granted to copy and distribute modified versions
of this
+cvs.texi(,29) manual under the conditions for verbatim copying, provided also
that the
+cvs.texi(,30) entire resulting derived work is distributed under the terms of a
+cvs.texi(,31) permission notice identical to this one.
+cvs.texi(,32)
+cvs.texi(,33) Permission is granted to copy and distribute translations of
this manual
+cvs.texi(,34) into another language, under the above conditions for modified
versions,
+cvs.texi(,35) except that this permission notice may be stated in a translation
+cvs.texi(,36) approved by the Free Software Foundation.
+cvs.texi(,37) @end macro
cvs.texi(,38)
cvs.texi(,39) @comment This file is part of the CVS distribution.
cvs.texi(,40)
@@ -51,9 +85,15 @@
cvs.texi(,83) @c @asis when generating info and dvi, and by <i></i> in the
generated html,
cvs.texi(,84) @c such that keywords are not expanded in the generated html.
cvs.texi(,85)
+cvs.texi(,86) @macro splitrcskeyword {arg}
+cvs.texi(,87) \arg\
+cvs.texi(,88) @end macro
cvs.texi(,89)
cvs.texi(,95)
cvs.texi(,101)
+cvs.texi(,103) @macro splitrcskeyword {arg}
+cvs.texi(,104) \arg\
+cvs.texi(,105) @end macro
cvs.texi(,107)
cvs.texi(,108) @dircategory GNU Packages
cvs.texi(,109) @direntry
Index: res_info/texi_cvs/cvs.texi
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/manuals/res_info/texi_cvs/cvs.texi,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- res_info/texi_cvs/cvs.texi 31 Jul 2009 11:09:40 -0000 1.2
+++ res_info/texi_cvs/cvs.texi 2 Aug 2009 13:11:04 -0000 1.3
@@ -1,6 +1,40 @@
\input texinfo @c -*-texinfo-*-
@comment Documentation for CVS.
@setfilename cvs.info
address@hidden copyleftnotice
address@hidden
+Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
+ 2001, 2002, 2003 Free Software Foundation, Inc.
+
address@hidden @columnfractions .12 .88
address@hidden Portions
address@hidden @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003 Derek
R. Price,
address@hidden @tab Copyright @copyright{} 2002, 2003 Ximbiot
<http://ximbiot.com>,
address@hidden @tab Copyright @copyright{} 1992, 1993, 1999 Signum Support AB,
address@hidden @tab and Copyright @copyright{} others.
address@hidden multitable
+
address@hidden
+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).
+
address@hidden ignore
+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 also 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 Free Software Foundation.
address@hidden macro
@comment This file is part of the CVS distribution.
@@ -52,9 +86,15 @@
@c @asis when generating info and dvi, and by <i></i> in the generated html,
@c such that keywords are not expanded in the generated html.
address@hidden splitrcskeyword {arg}
+ \arg\
address@hidden macro
address@hidden splitrcskeyword {arg}
+ \arg\
address@hidden macro
@dircategory GNU Packages
@direntry
Index: res_info/texi_mini_ker/mini_ker.2
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res_info/texi_mini_ker/mini_ker.2,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_info/texi_mini_ker/mini_ker.2 31 Jul 2009 10:17:21 -0000 1.1
+++ res_info/texi_mini_ker/mini_ker.2 2 Aug 2009 13:11:05 -0000 1.2
@@ -1,2 +1 @@
*** Duplicate node found: Top (l. 72)
-*** Duplicate node found: Top (l. 72)
Index: res_info/texi_mini_ker/mini_ker.passfirst
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res_info/texi_mini_ker/mini_ker.passfirst,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_info/texi_mini_ker/mini_ker.passfirst 31 Jul 2009 10:17:21 -0000
1.1
+++ res_info/texi_mini_ker/mini_ker.passfirst 2 Aug 2009 13:11:05 -0000
1.2
@@ -9,6 +9,9 @@
mini_ker.texi(,17)
mini_ker.texi(,18) @set myurl
@url{http://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}
mini_ker.texi(,19)
+mini_ker.texi(,20) @macro Minik{}
+mini_ker.texi(,21) Miniker
+mini_ker.texi(,22) @end macro
mini_ker.texi(,23)
mini_ker.texi(Minik,24) @settitle Miniker 102 manual
mini_ker.texi(,25)
Index: res_info/texi_mini_ker/mini_ker.passtexi
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res_info/texi_mini_ker/mini_ker.passtexi,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_info/texi_mini_ker/mini_ker.passtexi 31 Jul 2009 10:17:21 -0000
1.1
+++ res_info/texi_mini_ker/mini_ker.passtexi 2 Aug 2009 13:11:05 -0000
1.2
@@ -9,6 +9,9 @@
mini_ker.texi(,17)
mini_ker.texi(,18) @set myurl
@url{http://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}
mini_ker.texi(,19)
+mini_ker.texi(,20) @macro Minik{}
+mini_ker.texi(,21) Miniker
+mini_ker.texi(,22) @end macro
mini_ker.texi(,23)
mini_ker.texi(Minik,24) @settitle mini_ker.texi(Minik,24) Miniker 102 manual
mini_ker.texi(,25)
Index: res_info/texi_mini_ker/mini_ker.texi
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res_info/texi_mini_ker/mini_ker.texi,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_info/texi_mini_ker/mini_ker.texi 31 Jul 2009 10:17:21 -0000
1.1
+++ res_info/texi_mini_ker/mini_ker.texi 2 Aug 2009 13:11:05 -0000
1.2
@@ -10,6 +10,9 @@
@set myurl
@url{http://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}
address@hidden Minik{}
+Miniker
address@hidden macro
@settitle Miniker 102 manual
Index: res_info/texinfo_xml/texinfo.xml
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/manuals/res_info/texinfo_xml/texinfo.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_info/texinfo_xml/texinfo.xml 28 Jul 2009 18:42:48 -0000 1.1
+++ res_info/texinfo_xml/texinfo.xml 2 Aug 2009 13:11:06 -0000 1.2
@@ -16,9 +16,6 @@
<!-- Put everything except function (command, in this case) names in one -->
<!-- index (arbitrarily chosen to be the concept index). -->
-
-
-
<footnotestyle></footnotestyle><!-- finalout -->
<!-- %**end of header -->
@@ -19528,7 +19525,7 @@
<appendixsec>
<title>GNU Free Documentation License</title>
-<para><indexterm index="cp">FDL, GNU Free Documentation
License</indexterm></para><center><para> Version 1.1, March 2000
+<para><indexterm index="cp">FDL, GNU Free Documentation
License</indexterm></para><center><para>Version 1.1, March 2000
</para></center>
<display xml:space="preserve">Copyright ©right; 2000 Free Software
Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
Index: res/texi_cvs/cvs.texi.first
===================================================================
RCS file: res/texi_cvs/cvs.texi.first
diff -N res/texi_cvs/cvs.texi.first
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ res/texi_cvs/cvs.texi.first 2 Aug 2009 13:10:59 -0000 1.1
@@ -0,0 +1,14380 @@
+\input texinfo @c -*-texinfo-*-
address@hidden Documentation for CVS.
address@hidden cvs.info
address@hidden copyleftnotice
address@hidden
+Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
+ 2001, 2002, 2003 Free Software Foundation, Inc.
+
address@hidden @columnfractions .12 .88
address@hidden Portions
address@hidden @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003 Derek
R. Price,
address@hidden @tab Copyright @copyright{} 2002, 2003 Ximbiot
<http://ximbiot.com>,
address@hidden @tab Copyright @copyright{} 1992, 1993, 1999 Signum Support AB,
address@hidden @tab and Copyright @copyright{} others.
address@hidden multitable
+
address@hidden
+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).
+
address@hidden ignore
+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 also 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 Free Software Foundation.
address@hidden macro
+
address@hidden This file is part of the CVS distribution.
+
address@hidden CVS is free software; you can redistribute it and/or modify
address@hidden it under the terms of the GNU General Public License as
published by
address@hidden the Free Software Foundation; either version 2, or (at your
option)
address@hidden any later version.
+
address@hidden CVS is distributed in the hope that it will be useful,
address@hidden but WITHOUT ANY WARRANTY; without even the implied warranty of
address@hidden MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
address@hidden GNU General Public License for more details.
+
address@hidden See ../README for A4 vs. US letter size.
address@hidden When we provided A4 postscript, and people tried to
address@hidden print it on US letter, the usual complaint was that the
address@hidden page numbers would get cut off.
address@hidden If one prints US letter on A4, reportedly there is
address@hidden some extra space at the top and/or bottom, and the side
address@hidden margins are a bit narrow, but no text is lost.
address@hidden
address@hidden See
address@hidden http://www.ft.uni-erlangen.de/~mskuhn/iso-paper.html
address@hidden for more on paper sizes. Insuring that margins are
address@hidden big enough to print on either A4 or US letter does
address@hidden indeed seem to be the usual approach (RFC2346).
+
address@hidden This document seems to get overfull hboxes with some
address@hidden frequency (probably because the tendency is to
address@hidden sanity-check it with "make info" and run TeX less
address@hidden often). The big ugly boxes just seem to add insult
address@hidden to injury, and I'm not aware of them helping to fix
address@hidden the overfull hboxes at all.
address@hidden
+
address@hidden UPDATED 28 March 2002
address@hidden UPDATED-MONTH March 2002
address@hidden EDITION 4.2
address@hidden VERSION 4.2
address@hidden CVS---Concurrent Versions System v4.2
address@hidden odd
+
address@hidden -- TODO list:
address@hidden -- Fix all lines that match "address@hidden -- "
address@hidden -- Also places marked with FIXME should be manual
address@hidden problems (as opposed to FIXCVS for CVS problems).
+
address@hidden @splitrcskeyword{} is used to avoid keyword expansion. It is
replaced by
address@hidden @asis when generating info and dvi, and by <i></i> in the
generated html,
address@hidden such that keywords are not expanded in the generated html.
+
address@hidden splitrcskeyword {arg}
+ \arg\
address@hidden macro
+
+
address@hidden splitrcskeyword {arg}
address@hidden
address@hidden macro
+
+
address@hidden GNU Packages
address@hidden
+* CVS: (cvs). Concurrent Versions System
address@hidden direntry
address@hidden Individual utilities
address@hidden
+* cvs: (cvs)CVS commands. Concurrent Versions System
address@hidden direntry
+
address@hidden The titlepage section does not appear in the Info file.
+
address@hidden ================================================================
address@hidden The real text starts here
address@hidden ================================================================
+
address@hidden
---------------------------------------------------------------------
address@hidden Top
address@hidden
+
+This info manual describes how to use and administer
address@hidden version 4.2.
+
+
address@hidden This menu is pretty long. Not sure how easily that
address@hidden can be fixed (no brilliant ideas right away)...
address@hidden
+* Overview:: An introduction to CVS
+* Repository:: Where all your sources are stored
+* Starting a new project:: Starting a project with CVS
+* Revisions:: Numeric and symbolic names for revisions
+* Branching and merging:: Diverging/rejoining branches of development
+* Recursive behavior:: CVS descends directories
+* Adding and removing:: Adding/removing/renaming files/directories
+* History browsing:: Viewing the history of files in various ways
+
+CVS and the Real World.
+-----------------------
+* Binary files:: CVS can handle binary files
+* Multiple developers:: How CVS helps a group of developers
+* Revision management:: Policy questions for revision management
+* Keyword substitution:: CVS can include the revision inside the file
+* Tracking sources:: Tracking third-party sources
+* Builds:: Issues related to CVS and builds
+* Special Files:: Devices, links and other non-regular files
+
+References.
+-----------
+* CVS commands:: CVS commands share some things
+* Invoking CVS:: Quick reference to CVS commands
+* Administrative files:: Reference manual for the Administrative files
+* Environment variables:: All environment variables which affect CVS
+* Compatibility:: Upgrading CVS versions
+* Troubleshooting:: Some tips when nothing works
+* Credits:: Some of the contributors to this manual
+* BUGS:: Dealing with bugs in CVS or this manual
+* Index:: Index
address@hidden menu
+
address@hidden
---------------------------------------------------------------------
address@hidden Overview
address@hidden Overview
address@hidden Overview
+
+This chapter is for people who have never used
address@hidden, and perhaps have never used version control
+software before.
+
+If you are already familiar with @sc{cvs} and are just
+trying to learn a particular feature or remember a
+certain command, you can probably skip everything here.
+
address@hidden
+* What is CVS?:: What you can do with @sc{cvs}
+* What is CVS not?:: Problems @sc{cvs} doesn't try to solve
+* A sample session:: A tour of basic @sc{cvs} usage
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden What is CVS?
address@hidden What is CVS?
address@hidden What is CVS?
address@hidden Introduction to CVS
address@hidden CVS, introduction to
+
address@hidden is a version control system. Using it, you can
+record the history of your source files.
+
address@hidden -- ///
address@hidden -- ///Those who cannot remember the past are condemned to repeat
it.
address@hidden -- /// -- George Santayana
address@hidden -- //////
+
address@hidden -- Insert history quote here!
+For example, bugs sometimes creep in when
+software is modified, and you might not detect the bug
+until a long time after you make the modification.
+With @sc{cvs}, you can easily retrieve old versions to see
+exactly which change caused the bug. This can
+sometimes be a big help.
+
+You could of course save every version of every file
+you have ever created. This would
+however waste an enormous amount of disk space. @sc{cvs}
+stores all the versions of a file in a single file in a
+clever way that only stores the differences between
+versions.
+
address@hidden also helps you if you are part of a group of people working
+on the same project. It is all too easy to overwrite
+each others' changes unless you are extremely careful.
+Some editors, like @sc{gnu} Emacs, try to make sure that
+the same file is never modified by two people at the
+same time. Unfortunately, if someone is using another
+editor, that safeguard will not work. @sc{cvs} solves this problem
+by insulating the different developers from each other. Every
+developer works in his own directory, and @sc{cvs} merges
+the work when each developer is done.
+
address@hidden History of CVS
address@hidden CVS, history of
address@hidden Credits (CVS program)
address@hidden Contributors (CVS program)
address@hidden started out as a bunch of shell scripts written by
+Dick Grune, posted to the newsgroup
address@hidden in the volume 6
+release of July, 1986. While no actual code from
+these shell scripts is present in the current version
+of @sc{cvs} much of the @sc{cvs} conflict resolution algorithms
+come from them.
+
+In April, 1989, Brian Berliner designed and coded @sc{cvs}.
+Jeff Polk later helped Brian with the design of the @sc{cvs}
+module and vendor branch support.
+
address@hidden Source, getting CVS source
+You can get @sc{cvs} in a variety of ways, including
+free download from the internet. For more information
+on downloading @sc{cvs} and other @sc{cvs} topics, see:
+
address@hidden
+http://www.cvshome.org/
+http://www.loria.fr/~molli/cvs-index.html
address@hidden example
+
address@hidden Mailing list
address@hidden List, mailing list
address@hidden Newsgroups
+There is a mailing list, known as @address@hidden,
+devoted to @sc{cvs}. To subscribe or
+unsubscribe
+write to
address@hidden@code{info-cvs-request@@gnu.org}}.
+If you prefer a usenet group, the right
+group is @code{comp.software.config-mgmt} which is for
address@hidden discussions (along with other configuration
+management systems). In the future, it might be
+possible to create a
address@hidden, but probably only
+if there is sufficient @sc{cvs} traffic on
address@hidden
address@hidden Other random data is that past attempts to create a
address@hidden gnu.* group have failed (the relevant authorities
address@hidden say they'll do it, but don't), and that tale was very
address@hidden skeptical of comp.software.config-mgmt.cvs when the
address@hidden subject came up around 1995 or so (for one
address@hidden thing, because creating it would be a "reorg" which
address@hidden would need to take a more comprehensive look at the
address@hidden whole comp.software.config-mgmt.* hierarchy).
+
+You can also subscribe to the @code{bug-cvs} mailing list,
+described in more detail in @ref{BUGS}. To subscribe
+send mail to @code{bug-cvs-request@@gnu.org}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden What is CVS not?
address@hidden What is CVS not?
address@hidden What is CVS not?
+
address@hidden can do a lot of things for you, but it does
+not try to be everything for everyone.
+
address@hidden @asis
address@hidden @sc{cvs} is not a build system.
+
+Though the structure of your repository and modules
+file interact with your build system
+(e.g. @file{Makefile}s), they are essentially
+independent.
+
address@hidden does not dictate how you build anything. It
+merely stores files for retrieval in a tree structure
+you devise.
+
address@hidden does not dictate how to use disk space in the
+checked out working directories. If you write your
address@hidden or scripts in every directory so they
+have to know the relative positions of everything else,
+you wind up requiring the entire repository to be
+checked out.
+
+If you modularize your work, and construct a build
+system that will share files (via links, mounts,
address@hidden in @file{Makefile}s, etc.), you can
+arrange your disk usage however you like.
+
+But you have to remember that @emph{any} such system is
+a lot of work to construct and maintain. @sc{cvs} does
+not address the issues involved.
+
+Of course, you should place the tools created to
+support such a build system (scripts, @file{Makefile}s,
+etc) under @sc{cvs}.
+
+Figuring out what files need to be rebuilt when
+something changes is, again, something to be handled
+outside the scope of @sc{cvs}. One traditional
+approach is to use @code{make} for building, and use
+some automated tool for generating the dependencies which
address@hidden uses.
+
+See @ref{Builds}, for more information on doing builds
+in conjunction with @sc{cvs}.
+
address@hidden @sc{cvs} is not a substitute for management.
+
+Your managers and project leaders are expected to talk
+to you frequently enough to make certain you are aware
+of schedules, merge points, branch names and release
+dates. If they don't, @sc{cvs} can't help.
+
address@hidden is an instrument for making sources dance to
+your tune. But you are the piper and the composer. No
+instrument plays itself or writes its own music.
+
address@hidden @sc{cvs} is not a substitute for developer communication.
+
+When faced with conflicts within a single file, most
+developers manage to resolve them without too much
+effort. But a more general definition of ``conflict''
+includes problems too difficult to solve without
+communication between developers.
+
address@hidden cannot determine when simultaneous changes
+within a single file, or across a whole collection of
+files, will logically conflict with one another. Its
+concept of a @dfn{conflict} is purely textual, arising
+when two changes to the same base file are near enough
+to spook the merge (i.e. @code{diff3}) command.
+
address@hidden does not claim to help at all in figuring out
+non-textual or distributed conflicts in program logic.
+
+For example: Say you change the arguments to function
address@hidden defined in file @file{A}. At the same time,
+someone edits file @file{B}, adding new calls to
+function @code{X} using the old arguments. You are
+outside the realm of @sc{cvs}'s competence.
+
+Acquire the habit of reading specs and talking to your
+peers.
+
+
address@hidden @sc{cvs} does not have change control
+
+Change control refers to a number of things. First of
+all it can mean @dfn{bug-tracking}, that is being able
+to keep a database of reported bugs and the status of
+each one (is it fixed? in what release? has the bug
+submitter agreed that it is fixed?). For interfacing
address@hidden to an external bug-tracking system, see the
address@hidden and @file{verifymsg} files
+(@pxref{Administrative files}).
+
+Another aspect of change control is keeping track of
+the fact that changes to several files were in fact
+changed together as one logical change. If you check
+in several files in a single @code{cvs commit}
+operation, @sc{cvs} then forgets that those files were
+checked in together, and the fact that they have the
+same log message is the only thing tying them
+together. Keeping a @sc{gnu} style @file{ChangeLog}
+can help somewhat.
address@hidden FIXME: should have an xref to a section which talks
address@hidden more about keeping ChangeLog's with CVS, but that
address@hidden section hasn't been written yet.
+
+Another aspect of change control, in some systems, is
+the ability to keep track of the status of each
+change. Some changes have been written by a developer,
+others have been reviewed by a second developer, and so
+on. Generally, the way to do this with @sc{cvs} is to
+generate a diff (using @code{cvs diff} or @code{diff})
+and email it to someone who can then apply it using the
address@hidden utility. This is very flexible, but
+depends on mechanisms outside @sc{cvs} to make sure
+nothing falls through the cracks.
+
address@hidden @sc{cvs} is not an automated testing program
+
+It should be possible to enforce mandatory use of a
+testsuite using the @code{commitinfo} file. I haven't
+heard a lot about projects trying to do that or whether
+there are subtle gotchas, however.
+
address@hidden @sc{cvs} does not have a builtin process model
+
+Some systems provide ways to ensure that changes or
+releases go through various steps, with various
+approvals as needed. Generally, one can accomplish
+this with @sc{cvs} but it might be a little more work.
+In some cases you'll want to use the @file{commitinfo},
address@hidden, @file{rcsinfo}, or @file{verifymsg}
+files, to require that certain steps be performed
+before cvs will allow a checkin. Also consider whether
+features such as branches and tags can be used to
+perform tasks such as doing work in a development tree
+and then merging certain changes over to a stable tree
+only once they have been proven.
address@hidden table
+
address@hidden
---------------------------------------------------------------------
address@hidden A sample session
address@hidden A sample session
address@hidden Example of a work-session
address@hidden Getting started
address@hidden Work-session, example of
address@hidden tc, Trivial Compiler (example)
address@hidden Trivial Compiler (example)
+
address@hidden I think an example is a pretty good way to start. But
address@hidden somewhere in here, maybe after the sample session,
address@hidden we need something which is kind of
address@hidden a "roadmap" which is more directed at sketching out
address@hidden the functionality of CVS and pointing people to
address@hidden various other parts of the manual. As it stands now
address@hidden people who read in order get dumped right into all
address@hidden manner of hair regarding remote repositories,
address@hidden creating a repository, etc.
address@hidden
address@hidden The following was in the old Basic concepts node. I don't
address@hidden know how good a job it does at introducing modules,
address@hidden or whether they need to be introduced so soon, but
address@hidden something of this sort might go into some
address@hidden introductory material somewhere.
+
+As a way of introducing @sc{cvs}, we'll go through a
+typical work-session using @sc{cvs}. The first thing
+to understand is that @sc{cvs} stores all files in a
+centralized @dfn{repository} (@pxref{Repository}); this
+section assumes that a repository is set up.
address@hidden I'm not sure that the sentence concerning the
address@hidden repository quite tells the user what they need to
address@hidden know at this point. Might need to expand on "centralized"
address@hidden slightly (maybe not here, maybe further down in the example?)
+
+Suppose you are working on a simple compiler. The source
+consists of a handful of C files and a @file{Makefile}.
+The compiler is called @samp{tc} (Trivial Compiler),
+and the repository is set up so that there is a module
+called @samp{tc}.
+
address@hidden
+* Getting the source:: Creating a workspace
+* Committing your changes:: Making your work available to others
+* Cleaning up:: Cleaning up
+* Viewing differences:: Viewing differences
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Getting the source
address@hidden Getting the source
address@hidden Getting the source
address@hidden Checking out source
address@hidden Fetching source
address@hidden Source, getting from CVS
address@hidden Checkout, example
+
+The first thing you must do is to get your own working copy of the
+source for @samp{tc}. For this, you use the @code{checkout} command:
+
address@hidden
+$ cvs checkout tc
address@hidden example
+
address@hidden
+This will create a new directory called @file{tc} and populate it with
+the source files.
+
address@hidden
+$ cd tc
+$ ls
+CVS Makefile backend.c driver.c frontend.c parser.c
address@hidden example
+
+The @file{CVS} directory is used internally by
address@hidden Normally, you should not modify or remove
+any of the files in it.
+
+You start your favorite editor, hack away at @file{backend.c}, and a couple
+of hours later you have added an optimization pass to the compiler.
+A note to @sc{rcs} and @sc{sccs} users: There is no need to lock the files that
+you want to edit. @xref{Multiple developers}, for an explanation.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Committing your changes
address@hidden Committing your changes
address@hidden Committing changes to files
address@hidden Log message entry
+
+When you have checked that the compiler is still compilable you decide
+to make a new version of @file{backend.c}. This will
+store your new @file{backend.c} in the repository and
+make it available to anyone else who is using that same
+repository.
+
address@hidden
+$ cvs commit backend.c
address@hidden example
+
address@hidden
address@hidden starts an editor, to allow you to enter a log
+message. You type in ``Added an optimization pass.'',
+save the temporary file, and exit the editor.
+
address@hidden CVSEDITOR, environment variable
address@hidden EDITOR, environment variable
+The environment variable @code{$CVSEDITOR} determines
+which editor is started. If @code{$CVSEDITOR} is not
+set, then if the environment variable @code{$EDITOR} is
+set, it will be used. If both @code{$CVSEDITOR} and
address@hidden are not set then there is a default
+which will vary with your operating system, for example
address@hidden for unix or @code{notepad} for Windows
+NT/95.
+
address@hidden VISUAL, environment variable
+In addition, @sc{cvs} checks the @code{$VISUAL} environment
+variable. Opinions vary on whether this behavior is desirable and
+whether future releases of @sc{cvs} should check @code{$VISUAL} or
+ignore it. You will be OK either way if you make sure that
address@hidden is either unset or set to the same thing as
address@hidden
+
address@hidden This probably should go into some new node
address@hidden containing detailed info on the editor, rather than
address@hidden the intro. In fact, perhaps some of the stuff with
address@hidden CVSEDITOR and -m and so on should too.
+When @sc{cvs} starts the editor, it includes a list of
+files which are modified. For the @sc{cvs} client,
+this list is based on comparing the modification time
+of the file against the modification time that the file
+had when it was last gotten or updated. Therefore, if
+a file's modification time has changed but its contents
+have not, it will show up as modified. The simplest
+way to handle this is simply not to worry about it---if
+you proceed with the commit @sc{cvs} will detect that
+the contents are not modified and treat it as an
+unmodified file. The next @code{update} will clue
address@hidden in to the fact that the file is unmodified,
+and it will reset its stored timestamp so that the file
+will not show up in future editor sessions.
address@hidden FIXCVS: Might be nice if "commit" and other commands
address@hidden would reset that timestamp too, but currently commit
address@hidden doesn't.
address@hidden FIXME: Need to talk more about the process of
address@hidden prompting for the log message. Like show an example
address@hidden of what it pops up in the editor, for example. Also
address@hidden a discussion of how to get the "a)bort, c)ontinue,
address@hidden e)dit" prompt and what to do with it. Might also
address@hidden work in the suggestion that if you want a diff, you
address@hidden should make it before running commit (someone
address@hidden suggested that the diff pop up in the editor. I'm
address@hidden not sure that is better than telling people to run
address@hidden "cvs diff" first if that is what they want, but if
address@hidden we want to tell people that, the manual possibly
address@hidden should say it).
+
+If you want to avoid
+starting an editor you can specify the log message on
+the command line using the @samp{-m} flag instead, like
+this:
+
address@hidden
+$ cvs commit -m "Added an optimization pass" backend.c
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Cleaning up
address@hidden Cleaning up
address@hidden Cleaning up
address@hidden Working copy, removing
address@hidden Removing your working copy
address@hidden Releasing your working copy
+
+Before you turn to other tasks you decide to remove your working copy of
+tc. One acceptable way to do that is of course
+
address@hidden
+$ cd ..
+$ rm -r tc
address@hidden example
+
address@hidden
+but a better way is to use the @code{release} command (@pxref{release}):
+
address@hidden
+$ cd ..
+$ cvs release -d tc
+M driver.c
+? tc
+You have [1] altered files in this repository.
+Are you sure you want to release (and delete) directory `tc': n
+** `release' aborted by user choice.
address@hidden example
+
+The @code{release} command checks that all your modifications have been
+committed. If history logging is enabled it also makes a note in the
+history file. @xref{history file}.
+
+When you use the @samp{-d} flag with @code{release}, it
+also removes your working copy.
+
+In the example above, the @code{release} command wrote a couple of lines
+of output. @samp{? tc} means that the file @file{tc} is unknown to @sc{cvs}.
+That is nothing to worry about: @file{tc} is the executable compiler,
+and it should not be stored in the repository. @xref{cvsignore},
+for information about how to make that warning go away.
address@hidden output}, for a complete explanation of
+all possible output from @code{release}.
+
address@hidden driver.c} is more serious. It means that the
+file @file{driver.c} has been modified since it was
+checked out.
+
+The @code{release} command always finishes by telling
+you how many modified files you have in your working
+copy of the sources, and then asks you for confirmation
+before deleting any files or making any note in the
+history file.
+
+You decide to play it safe and answer @kbd{n @key{RET}}
+when @code{release} asks for confirmation.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Viewing differences
address@hidden Viewing differences
address@hidden Viewing differences
address@hidden Diff
+
+You do not remember modifying @file{driver.c}, so you want to see what
+has happened to that file.
+
address@hidden
+$ cd tc
+$ cvs diff driver.c
address@hidden example
+
+This command runs @code{diff} to compare the version of @file{driver.c}
+that you checked out with your working copy. When you see the output
+you remember that you added a command line option that enabled the
+optimization pass. You check it in, and release the module.
address@hidden FIXME: we haven't yet defined the term "check in".
+
address@hidden
+$ cvs commit -m "Added an optimization pass" driver.c
+Checking in driver.c;
+/usr/local/cvsroot/tc/driver.c,v <-- driver.c
+new revision: 1.2; previous revision: 1.1
+done
+$ cd ..
+$ cvs release -d tc
+? tc
+You have [0] altered files in this repository.
+Are you sure you want to release (and delete) directory `tc': y
address@hidden example
+
address@hidden
---------------------------------------------------------------------
address@hidden Repository
address@hidden The Repository
address@hidden Repository (intro)
address@hidden Repository, example
address@hidden Layout of repository
address@hidden Typical repository
address@hidden /usr/local/cvsroot, as example repository
address@hidden cvsroot
+
+The @sc{cvs} @dfn{repository} stores a complete copy of
+all the files and directories which are under version
+control.
+
+Normally, you never access any of the files in the
+repository directly. Instead, you use @sc{cvs}
+commands to get your own copy of the files into a
address@hidden directory}, and then
+work on that copy. When you've finished a set of
+changes, you check (or @dfn{commit}) them back into the
+repository. The repository then contains the changes
+which you have made, as well as recording exactly what
+you changed, when you changed it, and other such
+information. Note that the repository is not a
+subdirectory of the working directory, or vice versa;
+they should be in separate locations.
address@hidden Need some example, e.g. repository
address@hidden /usr/local/cvsroot; working directory
address@hidden /home/joe/sources. But this node is too long
address@hidden as it is; need a little reorganization...
+
address@hidden :local:, setting up
address@hidden can access a repository by a variety of
+means. It might be on the local computer, or it might
+be on a computer across the room or across the world.
+To distinguish various ways to access a repository, the
+repository name can start with an @dfn{access method}.
+For example, the access method @code{:local:} means to
+access a repository directory, so the repository
address@hidden:local:/usr/local/cvsroot} means that the
+repository is in @file{/usr/local/cvsroot} on the
+computer running @sc{cvs}. For information on other
+access methods, see @ref{Remote repositories}.
+
address@hidden Can se say this more concisely? Like by passing
address@hidden more of the buck to the Remote repositories node?
+If the access method is omitted, then if the repository
+starts with @samp{/}, then @code{:local:} is
+assumed. If it does not start with @samp{/} then either
address@hidden:ext:} or @code{:server:} is assumed. For
+example, if you have a local repository in
address@hidden/usr/local/cvsroot}, you can use
address@hidden/usr/local/cvsroot} instead of
address@hidden:local:/usr/local/cvsroot}. But if (under
+Windows NT, for example) your local repository is
address@hidden:\src\cvsroot}, then you must specify the access
+method, as in @code{:local:c:/src/cvsroot}.
+
address@hidden This might appear to go in Repository storage, but
address@hidden actually it is describing something which is quite
address@hidden user-visible, when you do a "cvs co CVSROOT". This
address@hidden isn't necessary the perfect place for that, though.
+The repository is split in two parts. @file{$CVSROOT/CVSROOT} contains
+administrative files for @sc{cvs}. The other directories contain the actual
+user-defined modules.
+
address@hidden
+* Specifying a repository:: Telling CVS where your repository is
+* Repository storage:: The structure of the repository
+* Working directory storage:: The structure of working directories
+* Intro administrative files:: Defining modules
+* Multiple repositories:: Multiple repositories
+* Creating a repository:: Creating a repository
+* Backing up:: Backing up a repository
+* Moving a repository:: Moving a repository
+* Remote repositories:: Accessing repositories on remote machines
+* Read-only access:: Granting read-only access to the repository
+* Server temporary directory:: The server creates temporary directories
address@hidden menu
+
address@hidden Specifying a repository
address@hidden Telling CVS where your repository is
+
+There are several ways to tell @sc{cvs}
+where to find the repository. You can name the
+repository on the command line explicitly, with the
address@hidden (for "directory") option:
+
address@hidden
+cvs -d /usr/local/cvsroot checkout yoyodyne/tc
address@hidden example
+
address@hidden .profile, setting CVSROOT in
address@hidden .cshrc, setting CVSROOT in
address@hidden .tcshrc, setting CVSROOT in
address@hidden .bashrc, setting CVSROOT in
address@hidden CVSROOT, environment variable
+ Or you can set the @code{$CVSROOT} environment
+variable to an absolute path to the root of the
+repository, @file{/usr/local/cvsroot} in this example.
+To set @code{$CVSROOT}, @code{csh} and @code{tcsh}
+users should have this line in their @file{.cshrc} or
address@hidden files:
+
address@hidden
+setenv CVSROOT /usr/local/cvsroot
address@hidden example
+
address@hidden
address@hidden and @code{bash} users should instead have these lines in their
address@hidden or @file{.bashrc}:
+
address@hidden
+CVSROOT=/usr/local/cvsroot
+export CVSROOT
address@hidden example
+
address@hidden Root file, in CVS directory
address@hidden CVS/Root file
+ A repository specified with @code{-d} will
+override the @code{$CVSROOT} environment variable.
+Once you've checked a working copy out from the
+repository, it will remember where its repository is
+(the information is recorded in the
address@hidden/Root} file in the working copy).
+
+The @code{-d} option and the @file{CVS/Root} file both
+override the @code{$CVSROOT} environment variable. If
address@hidden option differs from @file{CVS/Root}, the
+former is used. Of course, for proper operation they
+should be two ways of referring to the same repository.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Repository storage
address@hidden How data is stored in the repository
address@hidden Repository, how data is stored
+
+For most purposes it isn't important @emph{how}
address@hidden stores information in the repository. In
+fact, the format has changed in the past, and is likely
+to change in the future. Since in almost all cases one
+accesses the repository via @sc{cvs} commands, such
+changes need not be disruptive.
+
+However, in some cases it may be necessary to
+understand how @sc{cvs} stores data in the repository,
+for example you might need to track down @sc{cvs} locks
+(@pxref{Concurrency}) or you might need to deal with
+the file permissions appropriate for the repository.
+
address@hidden
+* Repository files:: What files are stored in the repository
+* File permissions:: File permissions
+* Windows permissions:: Issues specific to Windows
+* Attic:: Some files are stored in the Attic
+* CVS in repository:: Additional information in CVS directory
+* Locks:: CVS locks control concurrent accesses
+* CVSROOT storage:: A few things about CVSROOT are different
address@hidden menu
+
address@hidden Repository files
address@hidden Where files are stored within the repository
+
address@hidden @cindex Filenames, legal
address@hidden @cindex Legal filenames
address@hidden Somewhere we need to say something about legitimate
address@hidden characters in filenames in working directory and
address@hidden repository. Not "/" (not even on non-unix). And
address@hidden here is a specific set of issues:
address@hidden Files starting with a - are handled inconsistently. They can not
address@hidden be added to a repository with an add command, because it they
are
address@hidden interpreted as a switch. They can appear in a repository if
they are
address@hidden part of a tree that is imported. They can not be removed from
the tree
address@hidden once they are there.
address@hidden Note that "--" *is* supported (as a
address@hidden consequence of using GNU getopt). Should document
address@hidden this somewhere ("Common options"?). The other usual technique,
address@hidden "./-foo", isn't as effective, at least for "cvs add"
address@hidden which doesn't support pathnames containing "/".
+
+The overall structure of the repository is a directory
+tree corresponding to the directories in the working
+directory. For example, supposing the repository is in
+
address@hidden
+/usr/local/cvsroot
address@hidden example
+
address@hidden
+here is a possible directory tree (showing only the
+directories):
+
address@hidden
address@hidden/usr}
+ |
+ address@hidden
+ | |
+ | address@hidden
+ | | |
+ | | address@hidden
+ | (administrative files)
+ |
+ address@hidden
+ | |
+ | address@hidden
+ | | (source code to @sc{gnu} diff)
+ | |
+ | address@hidden
+ | | (source code to @sc{rcs})
+ | |
+ | address@hidden
+ | (source code to @sc{cvs})
+ |
+ address@hidden
+ |
+ address@hidden
+ | |
+ | address@hidden
+ | |
+ | address@hidden
+ |
+ +--(other Yoyodyne software)
address@hidden example
+
+With the directories are @dfn{history files} for each file
+under version control. The name of the history file is
+the name of the corresponding file with @samp{,v}
+appended to the end. Here is what the repository for
+the @file{yoyodyne/tc} directory might look like:
address@hidden FIXME: Should also mention CVS (CVSREP)
address@hidden FIXME? Should we introduce Attic with an xref to
address@hidden Attic? Not sure whether that is a good idea or not.
address@hidden
+ @code{$CVSROOT}
+ |
+ address@hidden
+ | |
+ | address@hidden
+ | | |
+ address@hidden,v}
+ address@hidden,v}
+ address@hidden,v}
+ address@hidden,v}
+ address@hidden,v}
+ address@hidden
+ | |
+ | address@hidden,v}
+ |
+ address@hidden
+ |
+ address@hidden,v}
+ address@hidden,v}
address@hidden example
+
address@hidden History files
address@hidden RCS history files
address@hidden The first sentence, about what history files
address@hidden contain, is kind of redundant with our intro to what the
address@hidden repository does in node Repository....
+The history files contain, among other things, enough
+information to recreate any revision of the file, a log
+of all commit messages and the user-name of the person
+who committed the revision. The history files are
+known as @dfn{RCS files}, because the first program to
+store files in that format was a version control system
+known as @sc{rcs}. For a full
+description of the file format, see the @code{man} page
address@hidden(5)}, distributed with @sc{rcs}, or the
+file @file{doc/RCSFILES} in the @sc{cvs} source
+distribution. This
+file format has become very common---many systems other
+than @sc{cvs} or @sc{rcs} can at least import history
+files in this format.
address@hidden FIXME: Think about including documentation for this
address@hidden rather than citing it? In the long run, getting
address@hidden this to be a standard (not sure if we can cope with
address@hidden a standards process as formal as IEEE/ANSI/ISO/etc,
address@hidden though...) is the way to go, so maybe citing is
address@hidden better.
+
+The @sc{rcs} files used in @sc{cvs} differ in a few
+ways from the standard format. The biggest difference
+is magic branches; for more information see @ref{Magic
+branch numbers}. Also in @sc{cvs} the valid tag names
+are a subset of what @sc{rcs} accepts; for @sc{cvs}'s
+rules see @ref{Tags}.
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden File permissions
address@hidden File permissions
address@hidden -- Move this to @node Creating a repository or similar
address@hidden Security, file permissions in repository
address@hidden File permissions, general
address@hidden Permissions, general
address@hidden FIXME: we need to somehow reflect "permissions in
address@hidden repository" versus "permissions in working
address@hidden directory" in the index entries.
address@hidden Group
address@hidden Read-only files, in repository
+All @samp{,v} files are created read-only, and you
+should not change the permission of those files. The
+directories inside the repository should be writable by
+the persons that have permission to modify the files in
+each directory. This normally means that you must
+create a UNIX group (see group(5)) consisting of the
+persons that are to edit the files in a project, and
+set up the repository so that it is that group that
+owns the directory.
+(On some systems, you also need to set the set-group-ID-on-execution bit
+on the repository directories (see chmod(1)) so that newly-created files
+and directories get the group-ID of the parent directory rather than
+that of the current process.)
+
address@hidden See also comment in commitinfo node regarding cases
address@hidden which are really awkward with unix groups.
+
+This means that you can only control access to files on
+a per-directory basis.
+
+Note that users must also have write access to check
+out files, because @sc{cvs} needs to create lock files
+(@pxref{Concurrency}). You can use LockDir in CVSROOT/config
+to put the lock files somewhere other than in the repository
+if you want to allow read-only access to some directories
+(@pxref{config}).
+
address@hidden CVS seems to use CVSUMASK in picking permissions for
address@hidden val-tags, but maybe we should say more about this.
address@hidden Like val-tags gets created by someone who doesn't
address@hidden have CVSUMASK set right?
+Also note that users must have write access to the
address@hidden/val-tags} file. @sc{cvs} uses it to keep
+track of what tags are valid tag names (it is sometimes
+updated when tags are used, as well as when they are
+created).
+
+Each @sc{rcs} file will be owned by the user who last
+checked it in. This has little significance; what
+really matters is who owns the directories.
+
address@hidden CVSUMASK, environment variable
address@hidden Umask, for repository files
address@hidden tries to set up reasonable file permissions
+for new directories that are added inside the tree, but
+you must fix the permissions manually when a new
+directory should have different permissions than its
+parent directory. If you set the @code{CVSUMASK}
+environment variable that will control the file
+permissions which @sc{cvs} uses in creating directories
+and/or files in the repository. @code{CVSUMASK} does
+not affect the file permissions in the working
+directory; such files have the permissions which are
+typical for newly created files, except that sometimes
address@hidden creates them read-only (see the sections on
+watches, @ref{Setting a watch}; -r, @ref{Global
+options}; or @code{CVSREAD}, @ref{Environment variables}).
address@hidden FIXME: Need more discussion of which
address@hidden group should own the file in the repository.
address@hidden Include a somewhat detailed example of the usual
address@hidden case where CVSUMASK is 007, the developers are all
address@hidden in a group, and that group owns stuff in the
address@hidden repository. Need to talk about group ownership of
address@hidden newly-created directories/files (on some unices,
address@hidden such as SunOS4, setting the setgid bit on the
address@hidden directories will make files inherit the directory's
address@hidden group. On other unices, your mileage may vary. I
address@hidden can't remember what POSIX says about this, if
address@hidden anything).
+
+Note that using the client/server @sc{cvs}
+(@pxref{Remote repositories}), there is no good way to
+set @code{CVSUMASK}; the setting on the client machine
+has no effect. If you are connecting with @code{rsh}, you
+can set @code{CVSUMASK} in @file{.bashrc} or @file{.cshrc}, as
+described in the documentation for your operating
+system. This behavior might change in future versions
+of @sc{cvs}; do not rely on the setting of
address@hidden on the client having no effect.
address@hidden FIXME: need to explain what a umask is or cite
address@hidden someplace which does.
address@hidden
address@hidden There is also a larger (largely separate) issue
address@hidden about the meaning of CVSUMASK in a non-unix context.
address@hidden For example, whether there is
address@hidden an equivalent which fits better into other
address@hidden protection schemes like POSIX.6, VMS, &c.
address@hidden
address@hidden FIXME: Need one place which discusses this
address@hidden read-only files thing. Why would one use -r or
address@hidden CVSREAD? Why would one use watches? How do they
address@hidden interact?
address@hidden
address@hidden FIXME: We need to state
address@hidden whether using CVSUMASK removes the need for manually
address@hidden fixing permissions (in fact, if we are going to mention
address@hidden manually fixing permission, we better document a lot
address@hidden better just what we mean by "fix").
+
+Using pserver, you will generally need stricter
+permissions on the @sc{cvsroot} directory and
+directories above it in the tree; see @ref{Password
+authentication security}.
+
address@hidden Setuid
address@hidden Setgid
address@hidden Security, setuid
address@hidden Installed images (VMS)
+Some operating systems have features which allow a
+particular program to run with the ability to perform
+operations which the caller of the program could not.
+For example, the set user ID (setuid) or set group ID
+(setgid) features of unix or the installed image
+feature of VMS. @sc{cvs} was not written to use such
+features and therefore attempting to install @sc{cvs} in
+this fashion will provide protection against only
+accidental lapses; anyone who is trying to circumvent
+the measure will be able to do so, and depending on how
+you have set it up may gain access to more than just
address@hidden You may wish to instead consider pserver. It
+shares some of the same attributes, in terms of
+possibly providing a false sense of security or opening
+security holes wider than the ones you are trying to
+fix, so read the documentation on pserver security
+carefully if you are considering this option
+(@ref{Password authentication security}).
+
address@hidden Windows permissions
address@hidden File Permission issues specific to Windows
address@hidden Windows, and permissions
address@hidden File permissions, Windows-specific
address@hidden Permissions, Windows-specific
+
+Some file permission issues are specific to Windows
+operating systems (Windows 95, Windows NT, and
+presumably future operating systems in this family.
+Some of the following might apply to OS/2 but I'm not
+sure).
+
+If you are using local @sc{cvs} and the repository is on a
+networked file system which is served by the Samba SMB
+server, some people have reported problems with
+permissions. Enabling WRITE=YES in the samba
+configuration is said to fix/workaround it.
+Disclaimer: I haven't investigated enough to know the
+implications of enabling that option, nor do I know
+whether there is something which @sc{cvs} could be doing
+differently in order to avoid the problem. If you find
+something out, please let us know as described in
address@hidden
+
address@hidden Attic
address@hidden The attic
address@hidden Attic
+
+You will notice that sometimes @sc{cvs} stores an
address@hidden file in the @code{Attic}. For example, if the
address@hidden is @file{/usr/local/cvsroot} and we are
+talking about the file @file{backend.c} in the
+directory @file{yoyodyne/tc}, then the file normally
+would be in
+
address@hidden
+/usr/local/cvsroot/yoyodyne/tc/backend.c,v
address@hidden example
+
address@hidden
+but if it goes in the attic, it would be in
+
address@hidden
+/usr/local/cvsroot/yoyodyne/tc/Attic/backend.c,v
address@hidden example
+
address@hidden
address@hidden Dead state
+instead. It should not matter from a user point of
+view whether a file is in the attic; @sc{cvs} keeps
+track of this and looks in the attic when it needs to.
+But in case you want to know, the rule is that the RCS
+file is stored in the attic if and only if the head
+revision on the trunk has state @code{dead}. A
address@hidden state means that file has been removed, or
+never added, for that revision. For example, if you
+add a file on a branch, it will have a trunk revision
+in @code{dead} state, and a branch revision in a
address@hidden state.
address@hidden Probably should have some more concrete examples
address@hidden here, or somewhere (not sure exactly how we should
address@hidden arrange the discussion of the dead state, versus
address@hidden discussion of the attic).
+
address@hidden CVS in repository
address@hidden The CVS directory in the repository
address@hidden CVS directory, in repository
+
+The @file{CVS} directory in each repository directory
+contains information such as file attributes (in a file
+called @file{CVS/fileattr}. In the
+future additional files may be added to this directory,
+so implementations should silently ignore additional
+files.
+
+This behavior is implemented only by @sc{cvs} 1.7 and
+later; for details see @ref{Watches Compatibility}.
+
+The format of the fileattr file is a series of entries
+of the following form (where @address@hidden and @address@hidden
+means the text between the braces can be repeated zero
+or more times):
+
address@hidden @var{filename} <tab> @var{attrname} = @var{attrval}
+ @{; @var{attrname} = @address@hidden <linefeed>
+
address@hidden is @samp{F} for a file, in which case the entry specifies the
+attributes for that file.
+
address@hidden is @samp{D},
+and @var{filename} empty, to specify default attributes
+to be used for newly added files.
+
+Other @var{ent-type} are reserved for future expansion. @sc{cvs} 1.9 and older
+will delete them any time it writes file attributes.
address@hidden 1.10 and later will preserve them.
+
+Note that the order of the lines is not significant;
+a program writing the fileattr file may
+rearrange them at its convenience.
+
+There is currently no way of quoting tabs or linefeeds in the
+filename, @samp{=} in @var{attrname},
address@hidden;} in @var{attrval}, etc. Note: some implementations also
+don't handle a NUL character in any of the fields, but
+implementations are encouraged to allow it.
+
+By convention, @var{attrname} starting with @samp{_} is for an attribute given
+special meaning by @sc{cvs}; other @var{attrname}s are for user-defined
attributes
+(or will be, once implementations start supporting user-defined attributes).
+
+Builtin attributes:
+
address@hidden @code
address@hidden _watched
+Present means the file is watched and should be checked out
+read-only.
+
address@hidden _watchers
+Users with watches for this file. Value is
address@hidden > @var{type} @{ , @var{watcher} > @var{type} @}
+where @var{watcher} is a username, and @var{type}
+is zero or more of edit,unedit,commit separated by
address@hidden (that is, nothing if none; there is no "none" or "all" keyword).
+
address@hidden _editors
+Users editing this file. Value is
address@hidden > @var{val} @{ , @var{editor} > @var{val} @}
+where @var{editor} is a username, and @var{val} is
address@hidden@address@hidden, where
address@hidden is when the @code{cvs edit} command (or
+equivalent) happened,
+and @var{hostname} and @var{pathname} are for the working directory.
address@hidden table
+
+Example:
+
address@hidden FIXME: sanity.sh should contain a similar test case
address@hidden so we can compare this example from something from
address@hidden Real Life(TM). See cvsclient.texi (under Notify) for more
address@hidden discussion of the date format of _editors.
address@hidden
+Ffile1 _watched=;_watchers=joe>edit,mary>commit
+Ffile2 _watched=;_editors=sue>8 Jan 1975+workstn1+/home/sue/cvs
+D _watched=
address@hidden example
+
address@hidden
+means that the file @file{file1} should be checked out
+read-only. Furthermore, joe is watching for edits and
+mary is watching for commits. The file @file{file2}
+should be checked out read-only; sue started editing it
+on 8 Jan 1975 in the directory @file{/home/sue/cvs} on
+the machine @code{workstn1}. Future files which are
+added should be checked out read-only. To represent
+this example here, we have shown a space after
address@hidden, @samp{Ffile1}, and @samp{Ffile2}, but in fact
+there must be a single tab character there and no spaces.
+
address@hidden Locks
address@hidden CVS locks in the repository
+
address@hidden #cvs.rfl, technical details
address@hidden #cvs.wfl, technical details
address@hidden #cvs.lock, technical details
address@hidden Locks, cvs, technical details
+For an introduction to @sc{cvs} locks focusing on
+user-visible behavior, see @ref{Concurrency}. The
+following section is aimed at people who are writing
+tools which want to access a @sc{cvs} repository without
+interfering with other tools accessing the same
+repository. If you find yourself confused by concepts
+described here, like @dfn{read lock}, @dfn{write lock},
+and @dfn{deadlock}, you might consult the literature on
+operating systems or databases.
+
address@hidden #cvs.tfl
+Any file in the repository with a name starting
+with @file{#cvs.rfl.} is a read lock. Any file in
+the repository with a name starting with
address@hidden is a write lock. Old versions of @sc{cvs}
+(before @sc{cvs} 1.5) also created files with names starting
+with @file{#cvs.tfl}, but they are not discussed here.
+The directory @file{#cvs.lock} serves as a master
+lock. That is, one must obtain this lock first before
+creating any of the other locks.
+
+To obtain a readlock, first create the @file{#cvs.lock}
+directory. This operation must be atomic (which should
+be true for creating a directory under most operating
+systems). If it fails because the directory already
+existed, wait for a while and try again. After
+obtaining the @file{#cvs.lock} lock, create a file
+whose name is @file{#cvs.rfl.} followed by information
+of your choice (for example, hostname and process
+identification number). Then remove the
address@hidden directory to release the master lock.
+Then proceed with reading the repository. When you are
+done, remove the @file{#cvs.rfl} file to release the
+read lock.
+
+To obtain a writelock, first create the
address@hidden directory, as with a readlock. Then
+check that there are no files whose names start with
address@hidden If there are, remove
address@hidden, wait for a while, and try again. If
+there are no readers, then create a file whose name is
address@hidden followed by information of your choice
+(for example, hostname and process identification
+number). Hang on to the @file{#cvs.lock} lock. Proceed
+with writing the repository. When you are done, first
+remove the @file{#cvs.wfl} file and then the
address@hidden directory. Note that unlike the
address@hidden file, the @file{#cvs.wfl} file is just
+informational; it has no effect on the locking operation
+beyond what is provided by holding on to the
address@hidden lock itself.
+
+Note that each lock (writelock or readlock) only locks
+a single directory in the repository, including
address@hidden and @file{CVS} but not including
+subdirectories which represent other directories under
+version control. To lock an entire tree, you need to
+lock each directory (note that if you fail to obtain
+any lock you need, you must release the whole tree
+before waiting and trying again, to avoid deadlocks).
+
+Note also that @sc{cvs} expects writelocks to control
+access to individual @file{foo,v} files. @sc{rcs} has
+a scheme where the @file{,foo,} file serves as a lock,
+but @sc{cvs} does not implement it and so taking out a
address@hidden writelock is recommended. See the comments at
+rcs_internal_lockfile in the @sc{cvs} source code for
+further discussion/rationale.
+
address@hidden CVSROOT storage
address@hidden How files are stored in the CVSROOT directory
address@hidden CVSROOT, storage of files
+
+The @file{$CVSROOT/CVSROOT} directory contains the
+various administrative files. In some ways this
+directory is just like any other directory in the
+repository; it contains @sc{rcs} files whose names end
+in @samp{,v}, and many of the @sc{cvs} commands operate
+on it the same way. However, there are a few
+differences.
+
+For each administrative file, in addition to the
address@hidden file, there is also a checked out copy of the
+file. For example, there is an @sc{rcs} file
address@hidden,v} and a file @file{loginfo} which
+contains the latest revision contained in
address@hidden,v}. When you check in an administrative
+file, @sc{cvs} should print
+
address@hidden
+cvs commit: Rebuilding administrative file database
address@hidden example
+
address@hidden
+and update the checked out copy in
address@hidden/CVSROOT}. If it does not, there is
+something wrong (@pxref{BUGS}). To add your own files
+to the files to be updated in this fashion, you can add
+them to the @file{checkoutlist} administrative file
+(@pxref{checkoutlist}).
+
address@hidden modules.db
address@hidden modules.pag
address@hidden modules.dir
+By default, the @file{modules} file behaves as
+described above. If the modules file is very large,
+storing it as a flat text file may make looking up
+modules slow (I'm not sure whether this is as much of a
+concern now as when @sc{cvs} first evolved this
+feature; I haven't seen benchmarks). Therefore, by
+making appropriate edits to the @sc{cvs} source code
+one can store the modules file in a database which
+implements the @code{ndbm} interface, such as Berkeley
+db or GDBM. If this option is in use, then the modules
+database will be stored in the files @file{modules.db},
address@hidden, and/or @file{modules.dir}.
address@hidden I think fileattr also will use the database stuff.
address@hidden Anything else?
+
+For information on the meaning of the various
+administrative files, see @ref{Administrative files}.
+
address@hidden Working directory storage
address@hidden How data is stored in the working directory
+
address@hidden FIXME: Somewhere we should discuss timestamps (test
address@hidden case "stamps" in sanity.sh). But not here. Maybe
address@hidden in some kind of "working directory" chapter which
address@hidden would encompass the "Builds" one? But I'm not sure
address@hidden whether that is a good organization (is it based on
address@hidden what the user wants to do?).
+
address@hidden CVS directory, in working directory
+While we are discussing @sc{cvs} internals which may
+become visible from time to time, we might as well talk
+about what @sc{cvs} puts in the @file{CVS} directories
+in the working directories. As with the repository,
address@hidden handles this information and one can usually
+access it via @sc{cvs} commands. But in some cases it
+may be useful to look at it, and other programs, such
+as the @code{jCVS} graphical user interface or the
address@hidden package for emacs, may need to look at it.
+Such programs should follow the recommendations in this
+section if they hope to be able to work with other
+programs which use those files, including future
+versions of the programs just mentioned and the
+command-line @sc{cvs} client.
+
+The @file{CVS} directory contains several files.
+Programs which are reading this directory should
+silently ignore files which are in the directory but
+which are not documented here, to allow for future
+expansion.
+
+The files are stored according to the text file
+convention for the system in question. This means that
+working directories are not portable between systems
+with differing conventions for storing text files.
+This is intentional, on the theory that the files being
+managed by @sc{cvs} probably will not be portable between
+such systems either.
+
address@hidden @file
address@hidden Root
+This file contains the current @sc{cvs} root, as
+described in @ref{Specifying a repository}.
+
address@hidden Repository file, in CVS directory
address@hidden CVS/Repository file
address@hidden Repository
+This file contains the directory within the repository
+which the current directory corresponds with. It can
+be either an absolute pathname or a relative pathname;
address@hidden has had the ability to read either format
+since at least version 1.3 or so. The relative
+pathname is relative to the root, and is the more
+sensible approach, but the absolute pathname is quite
+common and implementations should accept either. For
+example, after the command
+
address@hidden
+cvs -d :local:/usr/local/cvsroot checkout yoyodyne/tc
address@hidden example
+
address@hidden
address@hidden will contain
+
address@hidden
+:local:/usr/local/cvsroot
address@hidden example
+
address@hidden
+and @file{Repository} will contain either
+
address@hidden
+/usr/local/cvsroot/yoyodyne/tc
address@hidden example
+
address@hidden
+or
+
address@hidden
+yoyodyne/tc
address@hidden example
+
+If the particular working directory does not correspond
+to a directory in the repository, then @file{Repository}
+should contain @file{CVSROOT/Emptydir}.
address@hidden Emptydir, in CVSROOT directory
address@hidden CVSROOT/Emptydir directory
+
address@hidden Entries file, in CVS directory
address@hidden CVS/Entries file
address@hidden Entries
+This file lists the files and directories in the
+working directory.
+The first character of each line indicates what sort of
+line it is. If the character is unrecognized, programs
+reading the file should silently skip that line, to
+allow for future expansion.
+
+If the first character is @samp{/}, then the format is:
+
address@hidden
+/@var{name}/@var{revision}/@address@hidden/@var{options}/@var{tagdate}
address@hidden example
+
address@hidden
+where @samp{[} and @samp{]} are not part of the entry,
+but instead indicate that the @samp{+} and conflict
+marker are optional. @var{name} is the name of the
+file within the directory. @var{revision} is the
+revision that the file in the working derives from, or
address@hidden for an added file, or @samp{-} followed by a
+revision for a removed file. @var{timestamp} is the
+timestamp of the file at the time that @sc{cvs} created
+it; if the timestamp differs with the actual
+modification time of the file it means the file has
+been modified. It is stored in
+the format used by the ISO C asctime() function (for
+example, @samp{Sun Apr 7 01:29:26 1996}). One may
+write a string which is not in that format, for
+example, @samp{Result of merge}, to indicate that the
+file should always be considered to be modified. This
+is not a special case; to see whether a file is
+modified a program should take the timestamp of the file
+and simply do a string compare with @var{timestamp}.
+If there was a conflict, @var{conflict} can be set to
+the modification time of the file after the file has been
+written with conflict markers (@pxref{Conflicts example}).
+Thus if @var{conflict} is subsequently the same as the actual
+modification time of the file it means that the user
+has obviously not resolved the conflict. @var{options}
+contains sticky options (for example @samp{-kb} for a
+binary file). @var{tagdate} contains @samp{T} followed
+by a tag name, or @samp{D} for a date, followed by a
+sticky tag or date. Note that if @var{timestamp}
+contains a pair of timestamps separated by a space,
+rather than a single timestamp, you are dealing with a
+version of @sc{cvs} earlier than @sc{cvs} 1.5 (not
+documented here).
+
+The timezone on the timestamp in CVS/Entries (local or
+universal) should be the same as the operating system
+stores for the timestamp of the file itself. For
+example, on Unix the file's timestamp is in universal
+time (UT), so the timestamp in CVS/Entries should be
+too. On @sc{vms}, the file's timestamp is in local
+time, so @sc{cvs} on @sc{vms} should use local time.
+This rule is so that files do not appear to be modified
+merely because the timezone changed (for example, to or
+from summer time).
address@hidden See comments and calls to gmtime() and friends in
address@hidden src/vers_ts.c (function time_stamp).
+
+If the first character of a line in @file{Entries} is
address@hidden, then it indicates a subdirectory. @samp{D}
+on a line all by itself indicates that the program
+which wrote the @file{Entries} file does record
+subdirectories (therefore, if there is such a line and
+no other lines beginning with @samp{D}, one knows there
+are no subdirectories). Otherwise, the line looks
+like:
+
address@hidden
+D/@var{name}/@var{filler1}/@var{filler2}/@var{filler3}/@var{filler4}
address@hidden example
+
address@hidden
+where @var{name} is the name of the subdirectory, and
+all the @var{filler} fields should be silently ignored,
+for future expansion. Programs which modify
address@hidden files should preserve these fields.
+
+The lines in the @file{Entries} file can be in any order.
+
address@hidden Entries.Log file, in CVS directory
address@hidden CVS/Entries.Log file
address@hidden Entries.Log
+This file does not record any information beyond that
+in @file{Entries}, but it does provide a way to update
+the information without having to rewrite the entire
address@hidden file, including the ability to preserve
+the information even if the program writing
address@hidden and @file{Entries.Log} abruptly aborts.
+Programs which are reading the @file{Entries} file
+should also check for @file{Entries.Log}. If the latter
+exists, they should read @file{Entries} and then apply
+the changes mentioned in @file{Entries.Log}. After
+applying the changes, the recommended practice is to
+rewrite @file{Entries} and then delete @file{Entries.Log}.
+The format of a line in @file{Entries.Log} is a single
+character command followed by a space followed by a
+line in the format specified for a line in
address@hidden The single character command is
address@hidden to indicate that the entry is being added,
address@hidden to indicate that the entry is being removed,
+or any other character to indicate that the entire line
+in @file{Entries.Log} should be silently ignored (for
+future expansion). If the second character of the line
+in @file{Entries.Log} is not a space, then it was
+written by an older version of @sc{cvs} (not documented
+here).
+
+Programs which are writing rather than reading can
+safely ignore @file{Entries.Log} if they so choose.
+
address@hidden Entries.Backup file, in CVS directory
address@hidden CVS/Entries.Backup file
address@hidden Entries.Backup
+This is a temporary file. Recommended usage is to
+write a new entries file to @file{Entries.Backup}, and
+then to rename it (atomically, where possible) to @file{Entries}.
+
address@hidden Entries.Static file, in CVS directory
address@hidden CVS/Entries.Static file
address@hidden Entries.Static
+The only relevant thing about this file is whether it
+exists or not. If it exists, then it means that only
+part of a directory was gotten and @sc{cvs} will
+not create additional files in that directory. To
+clear it, use the @code{update} command with the
address@hidden option, which will get the additional files
+and remove @file{Entries.Static}.
address@hidden FIXME: This needs to be better documented, in places
address@hidden other than Working Directory Storage.
address@hidden FIXCVS: The fact that this setting exists needs to
address@hidden be more visible to the user. For example "cvs
address@hidden status foo", in the case where the file would be
address@hidden gotten except for Entries.Static, might say
address@hidden something to distinguish this from other cases.
address@hidden One thing that periodically gets suggested is to
address@hidden have "cvs update" print something when it skips
address@hidden files due to Entries.Static, but IMHO that kind of
address@hidden noise pretty much makes the Entries.Static feature
address@hidden useless.
+
address@hidden Tag file, in CVS directory
address@hidden CVS/Tag file
address@hidden Sticky tags/dates, per-directory
address@hidden Per-directory sticky tags/dates
address@hidden Tag
+This file contains per-directory sticky tags or dates.
+The first character is @samp{T} for a branch tag,
address@hidden for a non-branch tag, or @samp{D} for a date,
+or another character to mean the file should be
+silently ignored, for future expansion. This character
+is followed by the tag or date. Note that
+per-directory sticky tags or dates are used for things
+like applying to files which are newly added; they
+might not be the same as the sticky tags or dates on
+individual files. For general information on sticky
+tags and dates, see @ref{Sticky tags}.
address@hidden FIXME: This needs to be much better documented,
address@hidden preferably not in the context of "working directory
address@hidden storage".
address@hidden FIXME: The Sticky tags node needs to discuss, or xref to
address@hidden someplace which discusses, per-directory sticky
address@hidden tags and the distinction with per-file sticky tags.
+
address@hidden Notify file, in CVS directory
address@hidden CVS/Notify file
address@hidden Notify
+This file stores notifications (for example, for
address@hidden or @code{unedit}) which have not yet been
+sent to the server. Its format is not yet documented
+here.
+
address@hidden Notify.tmp file, in CVS directory
address@hidden CVS/Notify.tmp file
address@hidden Notify.tmp
+This file is to @file{Notify} as @file{Entries.Backup}
+is to @file{Entries}. That is, to write @file{Notify},
+first write the new contents to @file{Notify.tmp} and
+then (atomically where possible), rename it to
address@hidden
+
address@hidden Base directory, in CVS directory
address@hidden CVS/Base directory
address@hidden Base
+If watches are in use, then an @code{edit} command
+stores the original copy of the file in the @file{Base}
+directory. This allows the @code{unedit} command to
+operate even if it is unable to communicate with the
+server.
+
address@hidden Baserev file, in CVS directory
address@hidden CVS/Baserev file
address@hidden Baserev
+The file lists the revision for each of the files in
+the @file{Base} directory. The format is:
+
address@hidden
address@hidden/@var{rev}/@var{expansion}
address@hidden example
+
address@hidden
+where @var{expansion} should be ignored, to allow for
+future expansion.
+
address@hidden Baserev.tmp file, in CVS directory
address@hidden CVS/Baserev.tmp file
address@hidden Baserev.tmp
+This file is to @file{Baserev} as @file{Entries.Backup}
+is to @file{Entries}. That is, to write @file{Baserev},
+first write the new contents to @file{Baserev.tmp} and
+then (atomically where possible), rename it to
address@hidden
+
address@hidden Template file, in CVS directory
address@hidden CVS/Template file
address@hidden Template
+This file contains the template specified by the
address@hidden file (@pxref{rcsinfo}). It is only used
+by the client; the non-client/server @sc{cvs} consults
address@hidden directly.
address@hidden table
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Intro administrative files
address@hidden The administrative files
address@hidden Administrative files (intro)
address@hidden Modules file
address@hidden CVSROOT, module name
address@hidden Defining modules (intro)
+
address@hidden FIXME: this node should be reorganized into "general
address@hidden information about admin files" and put the "editing
address@hidden admin files" stuff up front rather than jumping into
address@hidden the details of modules right away. Then the
address@hidden Administrative files node can go away, the information
address@hidden on each admin file distributed to a place appropriate
address@hidden to its function, and this node can contain a table
address@hidden listing each file and a @ref to its detailed description.
+
+The directory @file{$CVSROOT/CVSROOT} contains some @dfn{administrative
+files}. @xref{Administrative files}, for a complete description.
+You can use @sc{cvs} without any of these files, but
+some commands work better when at least the
address@hidden file is properly set up.
+
+The most important of these files is the @file{modules}
+file. It defines all modules in the repository. This
+is a sample @file{modules} file.
+
address@hidden FIXME: The CVSROOT line is a goofy example now that
address@hidden mkmodules doesn't exist.
address@hidden
+CVSROOT CVSROOT
+modules CVSROOT modules
+cvs gnu/cvs
+rcs gnu/rcs
+diff gnu/diff
+tc yoyodyne/tc
address@hidden example
+
+The @file{modules} file is line oriented. In its
+simplest form each line contains the name of the
+module, whitespace, and the directory where the module
+resides. The directory is a path relative to
address@hidden The last four lines in the example
+above are examples of such lines.
+
address@hidden FIXME: might want to introduce the concept of options in modules
file
address@hidden (the old example which was here, -i mkmodules, is obsolete).
+
+The line that defines the module called @samp{modules}
+uses features that are not explained here.
address@hidden, for a full explanation of all the
+available features.
+
address@hidden FIXME: subsection without node is bogus
address@hidden Editing administrative files
address@hidden Editing administrative files
address@hidden Administrative files, editing them
+
+You edit the administrative files in the same way that you would edit
+any other module. Use @samp{cvs checkout CVSROOT} to get a working
+copy, edit it, and commit your changes in the normal way.
+
+It is possible to commit an erroneous administrative
+file. You can often fix the error and check in a new
+revision, but sometimes a particularly bad error in the
+administrative file makes it impossible to commit new
+revisions.
address@hidden @xref{Bad administrative files} for a hint
address@hidden about how to solve such situations.
address@hidden -- administrative file checking--
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Multiple repositories
address@hidden Multiple repositories
address@hidden Multiple repositories
address@hidden Repositories, multiple
address@hidden Many repositories
address@hidden Parallel repositories
address@hidden Disjoint repositories
address@hidden CVSROOT, multiple repositories
+
+In some situations it is a good idea to have more than
+one repository, for instance if you have two
+development groups that work on separate projects
+without sharing any code. All you have to do to have
+several repositories is to specify the appropriate
+repository, using the @code{CVSROOT} environment
+variable, the @samp{-d} option to @sc{cvs}, or (once
+you have checked out a working directory) by simply
+allowing @sc{cvs} to use the repository that was used
+to check out the working directory
+(@pxref{Specifying a repository}).
+
+The big advantage of having multiple repositories is
+that they can reside on different servers. With @sc{cvs}
+version 1.10, a single command cannot recurse into
+directories from different repositories. With development
+versions of @sc{cvs}, you can check out code from multiple
+servers into your working directory. @sc{cvs} will
+recurse and handle all the details of making
+connections to as many server machines as necessary to
+perform the requested command. Here is an example of
+how to set up a working directory:
+
address@hidden
+cvs -d server1:/cvs co dir1
+cd dir1
+cvs -d server2:/root co sdir
+cvs update
address@hidden example
+
+The @code{cvs co} commands set up the working
+directory, and then the @code{cvs update} command will
+contact server2, to update the dir1/sdir subdirectory,
+and server1, to update everything else.
+
address@hidden FIXME: Does the FAQ have more about this? I have a
address@hidden dim recollection, but I'm too lazy to check right now.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Creating a repository
address@hidden Creating a repository
+
address@hidden Repository, setting up
address@hidden Creating a repository
address@hidden Setting up a repository
+
+To set up a @sc{cvs} repository, first choose the
+machine and disk on which you want to store the
+revision history of the source files. CPU and memory
+requirements are modest, so most machines should be
+adequate. For details see @ref{Server requirements}.
address@hidden Possible that we should be providing a quick rule of
address@hidden thumb, like the 32M memory for the server. That
address@hidden might increase the number of people who are happy
address@hidden with the answer, without following the xref.
+
+To estimate disk space
+requirements, if you are importing RCS files from
+another system, the size of those files is the
+approximate initial size of your repository, or if you
+are starting without any version history, a rule of
+thumb is to allow for the server approximately three
+times the size of the code to be under @sc{cvs} for the
+repository (you will eventually outgrow this, but not
+for a while). On the machines on which the developers
+will be working, you'll want disk space for
+approximately one working directory for each developer
+(either the entire tree or a portion of it, depending
+on what each developer uses).
+
+The repository should be accessible
+(directly or via a networked file system) from all
+machines which want to use @sc{cvs} in server or local
+mode; the client machines need not have any access to
+it other than via the @sc{cvs} protocol. It is not
+possible to use @sc{cvs} to read from a repository
+which one only has read access to; @sc{cvs} needs to be
+able to create lock files (@pxref{Concurrency}).
+
address@hidden init (subcommand)
+To create a repository, run the @code{cvs init}
+command. It will set up an empty repository in the
address@hidden root specified in the usual way
+(@pxref{Repository}). For example,
+
address@hidden
+cvs -d /usr/local/cvsroot init
address@hidden example
+
address@hidden init} is careful to never overwrite any
+existing files in the repository, so no harm is done if
+you run @code{cvs init} on an already set-up
+repository.
+
address@hidden init} will enable history logging; if you
+don't want that, remove the history file after running
address@hidden init}. @xref{history file}.
+
address@hidden Backing up
address@hidden Backing up a repository
address@hidden Repository, backing up
address@hidden Backing up, repository
+
+There is nothing particularly magical about the files
+in the repository; for the most part it is possible to
+back them up just like any other files. However, there
+are a few issues to consider.
+
address@hidden Locks, cvs, and backups
address@hidden #cvs.rfl, and backups
+The first is that to be paranoid, one should either not
+use @sc{cvs} during the backup, or have the backup
+program lock @sc{cvs} while doing the backup. To not
+use @sc{cvs}, you might forbid logins to machines which
+can access the repository, turn off your @sc{cvs}
+server, or similar mechanisms. The details would
+depend on your operating system and how you have
address@hidden set up. To lock @sc{cvs}, you would create
address@hidden locks in each repository directory.
+See @ref{Concurrency}, for more on @sc{cvs} locks.
+Having said all this, if you just back up without any
+of these precautions, the results are unlikely to be
+particularly dire. Restoring from backup, the
+repository might be in an inconsistent state, but this
+would not be particularly hard to fix manually.
+
+When you restore a repository from backup, assuming
+that changes in the repository were made after the time
+of the backup, working directories which were not
+affected by the failure may refer to revisions which no
+longer exist in the repository. Trying to run @sc{cvs}
+in such directories will typically produce an error
+message. One way to get those changes back into the
+repository is as follows:
+
address@hidden @bullet
address@hidden
+Get a new working directory.
+
address@hidden
+Copy the files from the working directory from before
+the failure over to the new working directory (do not
+copy the contents of the @file{CVS} directories, of
+course).
+
address@hidden
+Working in the new working directory, use commands such
+as @code{cvs update} and @code{cvs diff} to figure out
+what has changed, and then when you are ready, commit
+the changes into the repository.
address@hidden itemize
+
address@hidden Moving a repository
address@hidden Moving a repository
address@hidden Repository, moving
address@hidden Moving a repository
address@hidden Copying a repository
+
+Just as backing up the files in the repository is
+pretty much like backing up any other files, if you
+need to move a repository from one place to another it
+is also pretty much like just moving any other
+collection of files.
+
+The main thing to consider is that working directories
+point to the repository. The simplest way to deal with
+a moved repository is to just get a fresh working
+directory after the move. Of course, you'll want to
+make sure that the old working directory had been
+checked in before the move, or you figured out some
+other way to make sure that you don't lose any
+changes. If you really do want to reuse the existing
+working directory, it should be possible with manual
+surgery on the @file{CVS/Repository} files. You can
+see @ref{Working directory storage}, for information on
+the @file{CVS/Repository} and @file{CVS/Root} files, but
+unless you are sure you want to bother, it probably
+isn't worth it.
address@hidden FIXME: Surgery on CVS/Repository should be avoided
address@hidden by making RELATIVE_REPOS the default.
address@hidden FIXME-maybe: might want some documented way to
address@hidden change the CVS/Root files in some particular tree.
address@hidden But then again, I don't know, maybe just having
address@hidden people do this in perl/shell/&c isn't so bad...
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Remote repositories
address@hidden Remote repositories
address@hidden Repositories, remote
address@hidden Remote repositories
address@hidden Client/Server Operation
address@hidden Server, CVS
address@hidden Remote repositories, port specification
address@hidden Repositories, remote, port specification
address@hidden Client/Server Operation, port specification
address@hidden pserver (client/server connection method), port specification
address@hidden kserver (client/server connection method), port specification
address@hidden gserver (client/server connection method), port specification
address@hidden port, specifying for remote repositories
+
+ Your working copy of the sources can be on a
+different machine than the repository. Using @sc{cvs}
+in this manner is known as @dfn{client/server}
+operation. You run @sc{cvs} on a machine which can
+mount your working directory, known as the
address@hidden, and tell it to communicate to a machine
+which can mount the repository, known as the
address@hidden Generally, using a remote
+repository is just like using a local one, except that
+the format of the repository name is:
+
address@hidden
+[:@var{method}:address@hidden:@var{password}]@@address@hidden:address@hidden/path/to/repository
address@hidden example
+
+Specifying a password in the repository name is not recommended during
+checkout, since this will cause @sc{cvs} to store a cleartext copy of the
+password in each created directory. @code{cvs login} first instead
+(@pxref{Password authentication client}).
+
+The details of exactly what needs to be set up depend
+on how you are connecting to the server.
+
+If @var{method} is not specified, and the repository
+name contains @samp{:}, then the default is @code{ext}
+or @code{server}, depending on your platform; both are
+described in @ref{Connecting via rsh}.
address@hidden Should we try to explain which platforms are which?
address@hidden Platforms like unix and VMS, which only allow
address@hidden privileged programs to bind to sockets <1024 lose on
address@hidden :server:
address@hidden Platforms like Mac and VMS, whose rsh program is
address@hidden unusable or nonexistent, lose on :ext:
address@hidden Platforms like OS/2 and NT probably could plausibly
address@hidden default either way (modulo -b troubles).
+
address@hidden FIXME: We need to have a better way of explaining
address@hidden what method to use. This presentation totally
address@hidden obscures the fact that :ext: and CVS_RSH is the way to
address@hidden use SSH, for example. Plus it incorrectly implies
address@hidden that you need an @code{rsh} binary on the client to use
address@hidden :server:.
address@hidden Also note that rsh not pserver is the right choice if you want
address@hidden users to be able to create their own repositories
address@hidden (because of the --allow-root related issues).
address@hidden
+* Server requirements:: Memory and other resources for servers
+* Connecting via rsh:: Using the @code{rsh} program to connect
+* Password authenticated:: Direct connections using passwords
+* GSSAPI authenticated:: Direct connections using GSSAPI
+* Kerberos authenticated:: Direct connections with kerberos
+* Connecting via fork:: Using a forked @code{cvs server} to connect
address@hidden menu
+
address@hidden Server requirements
address@hidden Server requirements
+
+The quick answer to what sort of machine is suitable as
+a server is that requirements are modest---a server
+with 32M of memory or even less can handle a fairly
+large source tree with a fair amount of activity.
address@hidden Say something about CPU speed too? I'm even less sure
address@hidden what to say on that subject...
+
+The real answer, of course, is more complicated.
+Estimating the known areas of large memory consumption
+should be sufficient to estimate memory requirements.
+There are two such areas documented here; other memory
+consumption should be small by comparison (if you find
+that is not the case, let us know, as described in
address@hidden, so we can update this documentation).
+
+The first area of big memory consumption is large
+checkouts, when using the @sc{cvs} server. The server
+consists of two processes for each client that it is
+serving. Memory consumption on the child process
+should remain fairly small. Memory consumption on the
+parent process, particularly if the network connection
+to the client is slow, can be expected to grow to
+slightly more than the size of the sources in a single
+directory, or two megabytes, whichever is larger.
address@hidden "two megabytes" of course is SERVER_HI_WATER. But
address@hidden we don't mention that here because we are
address@hidden documenting the default configuration of CVS. If it
address@hidden is a "standard" thing to change that value, it
address@hidden should be some kind of run-time configuration.
address@hidden
address@hidden See cvsclient.texi for more on the design decision
address@hidden to not have locks in place while waiting for the
address@hidden client, which is what results in memory consumption
address@hidden as high as this.
+
+Multiplying the size of each @sc{cvs} server by the
+number of servers which you expect to have active at
+one time should give an idea of memory requirements for
+the server. For the most part, the memory consumed by
+the parent process probably can be swap space rather
+than physical memory.
address@hidden Has anyone verified that notion about swap space?
address@hidden I say it based pretty much on guessing that the
address@hidden ->text of the struct buffer_data only gets accessed
address@hidden in a first in, first out fashion, but I haven't
address@hidden looked very closely.
+
address@hidden What about disk usage in /tmp on the server? I think that
address@hidden it can be substantial, but I haven't looked at this
address@hidden again and tried to figure it out ("cvs import" is
address@hidden probably the worst case...).
+
+The second area of large memory consumption is
address@hidden, when checking in large files. This is
+required even for binary files. The rule of thumb is
+to allow about ten times the size of the largest file
+you will want to check in, although five times may be
+adequate. For example, if you want to check in a file
+which is 10 megabytes, you should have 100 megabytes of
+memory on the machine doing the checkin (the server
+machine for client/server, or the machine running
address@hidden for non-client/server). This can be swap
+space rather than physical memory. Because the memory
+is only required briefly, there is no particular need
+to allow memory for more than one such checkin at a
+time.
address@hidden The 5-10 times rule of thumb is from Paul Eggert for
address@hidden GNU diff. I don't think it is in the GNU diff
address@hidden manual or anyplace like that.
address@hidden
address@hidden Probably we could be saying more about
address@hidden non-client/server CVS.
address@hidden I would guess for non-client/server CVS in an NFS
address@hidden environment the biggest issues are the network and
address@hidden the NFS server.
+
+Resource consumption for the client is even more
+modest---any machine with enough capacity to run the
+operating system in question should have little
+trouble.
address@hidden Is that true? I think the client still wants to
address@hidden (bogusly) store entire files in memory at times.
+
+For information on disk space requirements, see
address@hidden a repository}.
+
address@hidden Connecting via rsh
address@hidden Connecting with rsh
+
address@hidden rsh
address@hidden uses the @samp{rsh} protocol to perform these
+operations, so the remote user host needs to have a
address@hidden file which grants access to the local
+user. Note that the program that @sc{cvs} uses for this
+purpose may be specified using the @file{--with-rsh}
+flag to configure.
+
+For example, suppose you are the user @samp{mozart} on
+the local machine @samp{toe.example.com}, and the
+server machine is @samp{faun.example.org}. On
+faun, put the following line into the file
address@hidden in @samp{bach}'s home directory:
+
address@hidden
+toe.example.com mozart
address@hidden example
+
address@hidden
+Then test that @samp{rsh} is working with
+
address@hidden
+rsh -l bach faun.example.org 'echo $PATH'
address@hidden example
+
address@hidden CVS_SERVER, environment variable
+Next you have to make sure that @code{rsh} will be able
+to find the server. Make sure that the path which
address@hidden printed in the above example includes the
+directory containing a program named @code{cvs} which
+is the server. You need to set the path in
address@hidden, @file{.cshrc}, etc., not @file{.login}
+or @file{.profile}. Alternately, you can set the
+environment variable @code{CVS_SERVER} on the client
+machine to the filename of the server you want to use,
+for example @file{/usr/local/bin/cvs-1.6}.
address@hidden FIXME: there should be a way to specify the
address@hidden program in CVSROOT, not CVS_SERVER, so that one can use
address@hidden different ones for different roots. e.g. ":server;cvs=cvs-1.6:"
address@hidden instead of ":server:".
+
+There is no need to edit @file{inetd.conf} or start a
address@hidden server daemon.
+
address@hidden :server:, setting up
address@hidden :ext:, setting up
address@hidden Kerberos, using kerberized rsh
address@hidden SSH (rsh replacement)
address@hidden rsh replacements (Kerberized, SSH, &c)
+There are two access methods that you use in @code{CVSROOT}
+for rsh. @code{:server:} specifies an internal rsh
+client, which is supported only by some @sc{cvs} ports.
address@hidden:ext:} specifies an external rsh program. By
+default this is @code{rsh} (unless otherwise specified
+by the @file{--with-rsh} flag to configure) but you may set the
address@hidden environment variable to invoke another
+program which can access the remote server (for
+example, @code{remsh} on HP-UX 9 because @code{rsh} is
+something different). It must be a program which can
+transmit data to and from the server without modifying
+it; for example the Windows NT @code{rsh} is not
+suitable since it by default translates between CRLF
+and LF. The OS/2 @sc{cvs} port has a hack to pass @samp{-b}
+to @code{rsh} to get around this, but since this could
+potentially cause problems for programs other than the
+standard @code{rsh}, it may change in the future. If
+you set @code{CVS_RSH} to @code{SSH} or some other rsh
+replacement, the instructions in the rest of this
+section concerning @file{.rhosts} and so on are likely
+to be inapplicable; consult the documentation for your rsh
+replacement.
address@hidden FIXME: there should be a way to specify the
address@hidden program in CVSROOT, not CVS_RSH, so that one can use
address@hidden different ones for different roots. e.g. ":ext;rsh=remsh:"
address@hidden instead of ":ext:".
address@hidden See also the comment in src/client.c for rationale
address@hidden concerning "rsh" being the default and never
address@hidden "remsh".
+
+Continuing our example, supposing you want to access
+the module @file{foo} in the repository
address@hidden/usr/local/cvsroot/}, on machine
address@hidden, you are ready to go:
+
address@hidden
+cvs -d :ext:bach@@faun.example.org:/usr/local/cvsroot checkout foo
address@hidden example
+
address@hidden
+(The @file{bach@@} can be omitted if the username is
+the same on both the local and remote hosts.)
+
address@hidden Should we mention "rsh host echo hi" and "rsh host
address@hidden cat" (the latter followed by typing text and ^D)
address@hidden as troubleshooting techniques? Probably yes
address@hidden (people tend to have trouble setting this up),
address@hidden but this kind of thing can be hard to spell out.
+
address@hidden Password authenticated
address@hidden Direct connection with password authentication
+
+The @sc{cvs} client can also connect to the server
+using a password protocol. This is particularly useful
+if using @code{rsh} is not feasible (for example,
+the server is behind a firewall), and Kerberos also is
+not available.
+
+ To use this method, it is necessary to make
+some adjustments on both the server and client sides.
+
address@hidden
+* Password authentication server:: Setting up the server
+* Password authentication client:: Using the client
+* Password authentication security:: What this method does and does not do
address@hidden menu
+
address@hidden Password authentication server
address@hidden Setting up the server for password authentication
+
+First of all, you probably want to tighten the
+permissions on the @file{$CVSROOT} and
address@hidden/CVSROOT} directories. See @ref{Password
+authentication security}, for more details.
+
address@hidden pserver (subcommand)
address@hidden Remote repositories, port specification
address@hidden Repositories, remote, port specification
address@hidden Client/Server Operation, port specification
address@hidden pserver (client/server connection method), port specification
address@hidden kserver (client/server connection method), port specification
address@hidden gserver (client/server connection method), port specification
address@hidden port, specifying for remote repositories
address@hidden Password server, setting up
address@hidden Authenticating server, setting up
address@hidden inetd, configuring for pserver
address@hidden xinetd, configuring for pserver
address@hidden FIXME: this isn't quite right regarding port
address@hidden numbers; CVS looks up "cvspserver" in
address@hidden /etc/services (on unix, but what about non-unix?).
+On the server side, the file @file{/etc/inetd.conf}
+needs to be edited so @code{inetd} knows to run the
+command @code{cvs pserver} when it receives a
+connection on the right port. By default, the port
+number is 2401; it would be different if your client
+were compiled with @code{CVS_AUTH_PORT} defined to
+something else, though. This can also be specified in the CVSROOT variable
+(@pxref{Remote repositories}) or overridden with the CVS_CLIENT_PORT
+environment variable (@pxref{Environment variables}).
+
+ If your @code{inetd} allows raw port numbers in
address@hidden/etc/inetd.conf}, then the following (all on a
+single line in @file{inetd.conf}) should be sufficient:
+
address@hidden
+2401 stream tcp nowait root /usr/local/bin/cvs
+cvs -f --allow-root=/usr/cvsroot pserver
address@hidden example
+
address@hidden
+(You could also use the
address@hidden option to specify a temporary directory.)
+
+The @samp{--allow-root} option specifies the allowable
address@hidden directory. Clients which attempt to use a
+different @sc{cvsroot} directory will not be allowed to
+connect. If there is more than one @sc{cvsroot}
+directory which you want to allow, repeat the option.
+(Unfortunately, many versions of @code{inetd} have very small
+limits on the number of arguments and/or the total length
+of the command. The usual solution to this problem is
+to have @code{inetd} run a shell script which then invokes
address@hidden with the necessary arguments.)
+
+ If your @code{inetd} wants a symbolic service
+name instead of a raw port number, then put this in
address@hidden/etc/services}:
+
address@hidden
+cvspserver 2401/tcp
address@hidden example
+
address@hidden
+and put @code{cvspserver} instead of @code{2401} in @file{inetd.conf}.
+
+If your system uses @code{xinetd} instead of @code{inetd},
+the procedure is slightly different.
+Create a file called @file{/etc/xinetd.d/cvspserver} containing the following:
+
address@hidden
+service cvspserver
address@hidden
+ port = 2401
+ socket_type = stream
+ protocol = tcp
+ wait = no
+ user = root
+ passenv = PATH
+ server = /usr/local/bin/cvs
+ server_args = -f --allow-root=/usr/cvsroot pserver
address@hidden
address@hidden example
+
address@hidden
+(If @code{cvspserver} is defined in @file{/etc/services}, you can omit
+the @code{port} line.)
+
+ Once the above is taken care of, restart your
address@hidden, or do whatever is necessary to force it
+to reread its initialization files.
+
+If you are having trouble setting this up, see
address@hidden
+
address@hidden CVS passwd file
address@hidden passwd (admin file)
+Because the client stores and transmits passwords in
+cleartext (almost---see @ref{Password authentication
+security}, for details), a separate @sc{cvs} password
+file is generally used, so people don't compromise
+their regular passwords when they access the
+repository. This file is
address@hidden/CVSROOT/passwd} (@pxref{Intro
+administrative files}). It uses a colon-separated
+format, similar to @file{/etc/passwd} on Unix systems,
+except that it has fewer fields: @sc{cvs} username,
+optional password, and an optional system username for
address@hidden to run as if authentication succeeds. Here is
+an example @file{passwd} file with five entries:
+
address@hidden
+anonymous:
+bach:ULtgRLXo7NRxs
+spwang:1sOp854gDF3DY
+melissa:tGX1fS8sun6rY:pubcvs
+qproj:XR4EZcEs0szik:pubcvs
address@hidden example
+
address@hidden
+(The passwords are encrypted according to the standard
+Unix @code{crypt()} function, so it is possible to
+paste in passwords directly from regular Unix
address@hidden/etc/passwd} files.)
+
+The first line in the example will grant access to any
address@hidden client attempting to authenticate as user
address@hidden, no matter what password they use,
+including an empty password. (This is typical for
+sites granting anonymous read-only access; for
+information on how to do the "read-only" part, see
address@hidden access}.)
+
+The second and third lines will grant access to
address@hidden and @code{spwang} if they supply their
+respective plaintext passwords.
+
address@hidden User aliases
+The fourth line will grant access to @code{melissa}, if
+she supplies the correct password, but her @sc{cvs}
+operations will actually run on the server side under
+the system user @code{pubcvs}. Thus, there need not be
+any system user named @code{melissa}, but there
address@hidden be one named @code{pubcvs}.
+
+The fifth line shows that system user identities can be
+shared: any client who successfully authenticates as
address@hidden will actually run as @code{pubcvs}, just
+as @code{melissa} does. That way you could create a
+single, shared system user for each project in your
+repository, and give each developer their own line in
+the @file{$CVSROOT/CVSROOT/passwd} file. The @sc{cvs}
+username on each line would be different, but the
+system username would be the same. The reason to have
+different @sc{cvs} usernames is that @sc{cvs} will log their
+actions under those names: when @code{melissa} commits
+a change to a project, the checkin is recorded in the
+project's history under the name @code{melissa}, not
address@hidden And the reason to have them share a
+system username is so that you can arrange permissions
+in the relevant area of the repository such that only
+that account has write-permission there.
+
+If the system-user field is present, all
+password-authenticated @sc{cvs} commands run as that
+user; if no system user is specified, @sc{cvs} simply
+takes the @sc{cvs} username as the system username and
+runs commands as that user. In either case, if there
+is no such user on the system, then the @sc{cvs}
+operation will fail (regardless of whether the client
+supplied a valid password).
+
+The password and system-user fields can both be omitted
+(and if the system-user field is omitted, then also
+omit the colon that would have separated it from the
+encrypted password). For example, this would be a
+valid @file{$CVSROOT/CVSROOT/passwd} file:
+
address@hidden
+anonymous::pubcvs
+fish:rKa5jzULzmhOo:kfogel
+sussman:1sOp854gDF3DY
address@hidden example
+
address@hidden
+When the password field is omitted or empty, then the
+client's authentication attempt will succeed with any
+password, including the empty string. However, the
+colon after the @sc{cvs} username is always necessary,
+even if the password is empty.
+
address@hidden can also fall back to use system authentication.
+When authenticating a password, the server first checks
+for the user in the @file{$CVSROOT/CVSROOT/passwd}
+file. If it finds the user, it will use that entry for
+authentication as described above. But if it does not
+find the user, or if the @sc{cvs} @file{passwd} file
+does not exist, then the server can try to authenticate
+the username and password using the operating system's
+user-lookup routines (this "fallback" behavior can be
+disabled by setting @code{SystemAuth=no} in the
address@hidden @file{config} file, @pxref{config}).
+
+The default fallback behaviour is to look in
address@hidden/etc/passwd} for this system password unless your
+system has PAM (Pluggable Authentication Modules)
+and your @sc{cvs} server executable was configured to
+use it at compile time (using @code{./configure --enable-pam} - see the
+INSTALL file for more). In this case, PAM will be consulted instead.
+This means that @sc{cvs} can be configured to use any password
+authentication source PAM can be configured to use (possibilities
+include a simple UNIX password, NIS, LDAP, and others) in its
+global configuration file (usually @file{/etc/pam.conf}
+or possibly @file{/etc/pam.d/cvs}). See your PAM documentation
+for more details on PAM configuration.
+
+Note that PAM is an experimental feature in @sc{cvs} and feedback is
+encouraged. Please send a mail to one of the @sc{cvs} mailing lists
+(@code{info-cvs@@gnu.org} or @code{bug-cvs@@gnu.org}) if you use the
address@hidden PAM support.
+
address@hidden: Using PAM gives the system administrator much more
+flexibility about how @sc{cvs} users are authenticated but
+no more security than other methods. See below for more.}
+
+CVS needs an "auth" and "account" module in the
+PAM configuration file. A typical PAM configuration
+would therefore have the following lines
+in @file{/etc/pam.conf} to emulate the standard @sc{cvs}
+system @file{/etc/passwd} authentication:
+
address@hidden
+cvs auth required pam_unix.so
+cvs account required pam_unix.so
address@hidden example
+
+The the equivalent @file{/etc/pam.d/cvs} would contain
+
address@hidden
+auth required pam_unix.so
+account required pam_unix.so
address@hidden example
+
+Some systems require a full path to the module so that
address@hidden (Linux) would become something like
address@hidden/usr/lib/security/$ISA/pam_unix.so.1} (Sun Solaris).
+See the @file{contrib/pam} subdirectory of the @sc{cvs}
+source distribution for further example configurations.
+
+The PAM service name given above as "cvs" is just
+the service name in the default configuration amd can be
+set using
address@hidden/configure --with-hardcoded-pam-service-name=<pam-service-name>}
+before compiling. @sc{cvs} can also be configured to use whatever
+name it is invoked as as its PAM service name using
address@hidden/configure --without-hardcoded-pam-service-name}, but this
+feature should not be used if you may not have control of the name
address@hidden will be invoked as.
+
+Be aware, also, that falling back to system
+authentication might be a security risk: @sc{cvs}
+operations would then be authenticated with that user's
+regular login password, and the password flies across
+the network in plaintext. See @ref{Password
+authentication security} for more on this.
+This may be more of a problem with PAM authentication
+because it is likely that the source of the system
+password is some central authentication service like
+LDAP which is also used to authenticate other services.
+
+On the other hand, PAM makes it very easy to change your password
+regularly. If they are given the option of a one-password system for
+all of their activities, users are often more willing to change their
+password on a regular basis.
+
+In the non-PAM configuration where the password is stored in the
address@hidden/passwd} file, it is difficult to change passwords on a
+regular basis since only administrative users (or in some cases
+processes that act as an administrative user) are typicaly given
+access to modify this file. Either there needs to be some
+hand-crafted web page or set-uid program to update the file, or the
+update needs to be done by submitting a request to an administrator to
+perform the duty by hand. In the first case, having to remember to
+update a separate password on a periodic basis can be difficult. In
+the second case, the manual nature of the change will typically mean
+that the password will not be changed unless it is absolutely
+necessary.
+
+Note that PAM administrators should probably avoid configuring
+one-time-passwords (OTP) for @sc{cvs} authentication/authorization. If
+OTPs are desired, the administrator may wish to encourage the use of
+one of the other Client/Server access methods. See the section on
address@hidden repositories} for a list of other methods.
+
+Right now, the only way to put a password in the
address@hidden @file{passwd} file is to paste it there from
+somewhere else. Someday, there may be a @code{cvs
+passwd} command.
+
+Unlike many of the files in @file{$CVSROOT/CVSROOT}, it
+is normal to edit the @file{passwd} file in-place,
+rather than via @sc{cvs}. This is because of the
+possible security risks of having the @file{passwd}
+file checked out to people's working copies. If you do
+want to include the @file{passwd} file in checkouts of
address@hidden/CVSROOT}, see @ref{checkoutlist}.
+
address@hidden We might also suggest using the @code{htpasswd} command
address@hidden from freely available web servers as well, but that
address@hidden would open up a can of worms in that the users next
address@hidden questions are likely to be "where do I get it?" and
address@hidden "how do I use it?"
address@hidden Also note that htpasswd, at least the version I had,
address@hidden likes to clobber the third field.
+
address@hidden Password authentication client
address@hidden Using the client with password authentication
address@hidden Login (subcommand)
address@hidden Password client, using
address@hidden Authenticated client, using
address@hidden :pserver:, setting up
+To run a @sc{cvs} command on a remote repository via
+the password-authenticating server, one specifies the
address@hidden protocol, optional username, repository host, an
+optional port number, and path to the repository. For example:
+
address@hidden
+cvs -d :pserver:faun.example.org:/usr/local/cvsroot checkout someproj
address@hidden example
+
address@hidden
+or
+
address@hidden
+CVSROOT=:pserver:bach@@faun.example.org:2401/usr/local/cvsroot
+cvs checkout someproj
address@hidden example
+
+However, unless you're connecting to a public-access
+repository (i.e., one where that username doesn't
+require a password), you'll need to supply a password or @dfn{log in} first.
+Logging in verifies your password with the repository and stores it in a file.
+It's done with the @code{login} command, which will
+prompt you interactively for the password if you didn't supply one as part of
address@hidden:
+
address@hidden
+cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot login
+CVS password:
address@hidden example
+
address@hidden
+or
+
address@hidden
+cvs -d :pserver:bach:p4ss30rd@@faun.example.org:/usr/local/cvsroot login
address@hidden example
+
+After you enter the password, @sc{cvs} verifies it with
+the server. If the verification succeeds, then that
+combination of username, host, repository, and password
+is permanently recorded, so future transactions with
+that repository won't require you to run @code{cvs
+login}. (If verification fails, @sc{cvs} will exit
+complaining that the password was incorrect, and
+nothing will be recorded.)
+
+The records are stored, by default, in the file
address@hidden/.cvspass}. That file's format is
+human-readable, and to a degree human-editable, but
+note that the passwords are not stored in
+cleartext---they are trivially encoded to protect them
+from "innocent" compromise (i.e., inadvertent viewing
+by a system administrator or other non-malicious
+person).
+
address@hidden CVS_PASSFILE, environment variable
+You can change the default location of this file by
+setting the @code{CVS_PASSFILE} environment variable.
+If you use this variable, make sure you set it
address@hidden @code{cvs login} is run. If you were to
+set it after running @code{cvs login}, then later
address@hidden commands would be unable to look up the
+password for transmission to the server.
+
+Once you have logged in, all @sc{cvs} commands using
+that remote repository and username will authenticate
+with the stored password. So, for example
+
address@hidden
+cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot checkout foo
address@hidden example
+
address@hidden
+should just work (unless the password changes on the
+server side, in which case you'll have to re-run
address@hidden login}).
+
+Note that if the @samp{:pserver:} were not present in
+the repository specification, @sc{cvs} would assume it
+should use @code{rsh} to connect with the server
+instead (@pxref{Connecting via rsh}).
+
+Of course, once you have a working copy checked out and
+are running @sc{cvs} commands from within it, there is
+no longer any need to specify the repository
+explicitly, because @sc{cvs} can deduce the repository
+from the working copy's @file{CVS} subdirectory.
+
address@hidden FIXME: seems to me this needs somewhat more
address@hidden explanation.
address@hidden Logout (subcommand)
+The password for a given remote repository can be
+removed from the @code{CVS_PASSFILE} by using the
address@hidden logout} command.
+
address@hidden Password authentication security
address@hidden Security considerations with password authentication
+
address@hidden Security, of pserver
+The passwords are stored on the client side in a
+trivial encoding of the cleartext, and transmitted in
+the same encoding. The encoding is done only to
+prevent inadvertent password compromises (i.e., a
+system administrator accidentally looking at the file),
+and will not prevent even a naive attacker from gaining
+the password.
+
address@hidden FIXME: The bit about "access to the repository
address@hidden implies general access to the system is *not* specific
address@hidden to pserver; it applies to kerberos and SSH and
address@hidden everything else too. Should reorganize the
address@hidden documentation to make this clear.
+The separate @sc{cvs} password file (@pxref{Password
+authentication server}) allows people
+to use a different password for repository access than
+for login access. On the other hand, once a user has
+non-read-only
+access to the repository, she can execute programs on
+the server system through a variety of means. Thus, repository
+access implies fairly broad system access as well. It
+might be possible to modify @sc{cvs} to prevent that,
+but no one has done so as of this writing.
address@hidden OpenBSD uses chroot() and copies the repository to
address@hidden provide anonymous read-only access (for details see
address@hidden http://www.openbsd.org/anoncvs.shar). While this
address@hidden closes the most obvious holes, I'm not sure it
address@hidden closes enough holes to recommend it (plus it is
address@hidden *very* easy to accidentally screw up a setup of this
address@hidden type).
+
+Note that because the @file{$CVSROOT/CVSROOT} directory
+contains @file{passwd} and other files which are used
+to check security, you must control the permissions on
+this directory as tightly as the permissions on
address@hidden/etc}. The same applies to the @file{$CVSROOT}
+directory itself and any directory
+above it in the tree. Anyone who has write access to
+such a directory will have the ability to become any
+user on the system. Note that these permissions are
+typically tighter than you would use if you are not
+using pserver.
address@hidden TODO: Would be really nice to document/implement a
address@hidden scheme where the CVS server can run as some non-root
address@hidden user, e.g. "cvs". CVSROOT/passwd would contain a
address@hidden bunch of entries of the form foo:xxx:cvs (or the "cvs"
address@hidden would be implicit). This would greatly reduce
address@hidden security risks such as those hinted at in the
address@hidden previous paragraph. I think minor changes to CVS
address@hidden might be required but mostly this would just need
address@hidden someone who wants to play with it, document it, &c.
+
+In summary, anyone who gets the password gets
+repository access (which may imply some measure of general system
+access as well). The password is available to anyone
+who can sniff network packets or read a protected
+(i.e., user read-only) file. If you want real
+security, get Kerberos.
+
address@hidden GSSAPI authenticated
address@hidden Direct connection with GSSAPI
+
address@hidden GSSAPI
address@hidden Security, GSSAPI
address@hidden :gserver:, setting up
address@hidden Kerberos, using :gserver:
+GSSAPI is a generic interface to network security
+systems such as Kerberos 5.
+If you have a working GSSAPI library, you can have
address@hidden connect via a direct @sc{tcp} connection,
+authenticating with GSSAPI.
+
+To do this, @sc{cvs} needs to be compiled with GSSAPI
+support; when configuring @sc{cvs} it tries to detect
+whether GSSAPI libraries using kerberos version 5 are
+present. You can also use the @file{--with-gssapi}
+flag to configure.
+
+The connection is authenticated using GSSAPI, but the
+message stream is @emph{not} authenticated by default.
+You must use the @code{-a} global option to request
+stream authentication.
+
+The data transmitted is @emph{not} encrypted by
+default. Encryption support must be compiled into both
+the client and the server; use the
address@hidden configure option to turn it on.
+You must then use the @code{-x} global option to
+request encryption.
+
+GSSAPI connections are handled on the server side by
+the same server which handles the password
+authentication server; see @ref{Password authentication
+server}. If you are using a GSSAPI mechanism such as
+Kerberos which provides for strong authentication, you
+will probably want to disable the ability to
+authenticate via cleartext passwords. To do so, create
+an empty @file{CVSROOT/passwd} password file, and set
address@hidden in the config file
+(@pxref{config}).
+
+The GSSAPI server uses a principal name of
+cvs/@var{hostname}, where @var{hostname} is the
+canonical name of the server host. You will have to
+set this up as required by your GSSAPI mechanism.
+
+To connect using GSSAPI, use @samp{:gserver:}. For
+example,
+
address@hidden
+cvs -d :gserver:faun.example.org:/usr/local/cvsroot checkout foo
address@hidden example
+
address@hidden Kerberos authenticated
address@hidden Direct connection with kerberos
+
address@hidden Kerberos, using :kserver:
address@hidden Security, kerberos
address@hidden :kserver:, setting up
+The easiest way to use kerberos is to use the kerberos
address@hidden, as described in @ref{Connecting via rsh}.
+The main disadvantage of using rsh is that all the data
+needs to pass through additional programs, so it may be
+slower. So if you have kerberos installed you can
+connect via a direct @sc{tcp} connection,
+authenticating with kerberos.
+
+This section concerns the kerberos network security
+system, version 4. Kerberos version 5 is supported via
+the GSSAPI generic network security interface, as
+described in the previous section.
+
+To do this, @sc{cvs} needs to be compiled with kerberos
+support; when configuring @sc{cvs} it tries to detect
+whether kerberos is present or you can use the
address@hidden flag to configure.
+
+The data transmitted is @emph{not} encrypted by
+default. Encryption support must be compiled into both
+the client and server; use the
address@hidden configure option to turn it
+on. You must then use the @code{-x} global option to
+request encryption.
+
address@hidden CVS_CLIENT_PORT
+You need to edit @file{inetd.conf} on the server
+machine to run @code{cvs kserver}. The client uses
+port 1999 by default; if you want to use another port
+specify it in the @code{CVSROOT} (@pxref{Remote repositories})
+or the @code{CVS_CLIENT_PORT} environment variable
+(@pxref{Environment variables}) on the client.
+
address@hidden kinit
+When you want to use @sc{cvs}, get a ticket in the
+usual way (generally @code{kinit}); it must be a ticket
+which allows you to log into the server machine. Then
+you are ready to go:
+
address@hidden
+cvs -d :kserver:faun.example.org:/usr/local/cvsroot checkout foo
address@hidden example
+
+Previous versions of @sc{cvs} would fall back to a
+connection via rsh; this version will not do so.
+
address@hidden Connecting via fork
address@hidden Connecting with fork
+
address@hidden fork, access method
address@hidden :fork:, setting up
+This access method allows you to connect to a
+repository on your local disk via the remote protocol.
+In other words it does pretty much the same thing as
address@hidden:local:}, but various quirks, bugs and the like are
+those of the remote @sc{cvs} rather than the local
address@hidden
+
+For day-to-day operations you might prefer either
address@hidden:local:} or @code{:fork:}, depending on your
+preferences. Of course @code{:fork:} comes in
+particularly handy in testing or
+debugging @code{cvs} and the remote protocol.
+Specifically, we avoid all of the network-related
+setup/configuration, timeouts, and authentication
+inherent in the other remote access methods but still
+create a connection which uses the remote protocol.
+
+To connect using the @code{fork} method, use
address@hidden:fork:} and the pathname to your local
+repository. For example:
+
address@hidden
+cvs -d :fork:/usr/local/cvsroot checkout foo
address@hidden example
+
address@hidden CVS_SERVER, and :fork:
+As with @code{:ext:}, the server is called @samp{cvs}
+by default, or the value of the @code{CVS_SERVER}
+environment variable.
+
address@hidden
---------------------------------------------------------------------
address@hidden Read-only access
address@hidden Read-only repository access
address@hidden Read-only repository access
address@hidden readers (admin file)
address@hidden writers (admin file)
+
+ It is possible to grant read-only repository
+access to people using the password-authenticated
+server (@pxref{Password authenticated}). (The
+other access methods do not have explicit support for
+read-only users because those methods all assume login
+access to the repository machine anyway, and therefore
+the user can do whatever local file permissions allow
+her to do.)
+
+ A user who has read-only access can do only
+those @sc{cvs} operations which do not modify the
+repository, except for certain ``administrative'' files
+(such as lock files and the history file). It may be
+desirable to use this feature in conjunction with
+user-aliasing (@pxref{Password authentication server}).
+
+Unlike with previous versions of @sc{cvs}, read-only
+users should be able merely to read the repository, and
+not to execute programs on the server or otherwise gain
+unexpected levels of access. Or to be more accurate,
+the @emph{known} holes have been plugged. Because this
+feature is new and has not received a comprehensive
+security audit, you should use whatever level of
+caution seems warranted given your attitude concerning
+security.
+
+ There are two ways to specify read-only access
+for a user: by inclusion, and by exclusion.
+
+ "Inclusion" means listing that user
+specifically in the @file{$CVSROOT/CVSROOT/readers}
+file, which is simply a newline-separated list of
+users. Here is a sample @file{readers} file:
+
address@hidden
+melissa
+splotnik
+jrandom
address@hidden example
+
address@hidden
+ (Don't forget the newline after the last user.)
+
+ "Exclusion" means explicitly listing everyone
+who has @emph{write} access---if the file
+
address@hidden
+$CVSROOT/CVSROOT/writers
address@hidden example
+
address@hidden
+exists, then only
+those users listed in it have write access, and
+everyone else has read-only access (of course, even the
+read-only users still need to be listed in the
address@hidden @file{passwd} file). The
address@hidden file has the same format as the
address@hidden file.
+
+ Note: if your @sc{cvs} @file{passwd}
+file maps cvs users onto system users (@pxref{Password
+authentication server}), make sure you deny or grant
+read-only access using the @emph{cvs} usernames, not
+the system usernames. That is, the @file{readers} and
address@hidden files contain cvs usernames, which may
+or may not be the same as system usernames.
+
+ Here is a complete description of the server's
+behavior in deciding whether to grant read-only or
+read-write access:
+
+ If @file{readers} exists, and this user is
+listed in it, then she gets read-only access. Or if
address@hidden exists, and this user is NOT listed in
+it, then she also gets read-only access (this is true
+even if @file{readers} exists but she is not listed
+there). Otherwise, she gets full read-write access.
+
+ Of course there is a conflict if the user is
+listed in both files. This is resolved in the more
+conservative way, it being better to protect the
+repository too much than too little: such a user gets
+read-only access.
+
address@hidden Server temporary directory
address@hidden Temporary directories for the server
address@hidden Temporary directories, and server
address@hidden Server, temporary directories
+
+While running, the @sc{cvs} server creates temporary
+directories. They are named
+
address@hidden
address@hidden
address@hidden example
+
address@hidden
+where @var{pid} is the process identification number of
+the server.
+They are located in the directory specified by
+the @samp{-T} global option (@pxref{Global options}),
+the @code{TMPDIR} environment variable (@pxref{Environment variables}),
+or, failing that, @file{/tmp}.
+
+In most cases the server will remove the temporary
+directory when it is done, whether it finishes normally
+or abnormally. However, there are a few cases in which
+the server does not or cannot remove the temporary
+directory, for example:
+
address@hidden @bullet
address@hidden
+If the server aborts due to an internal server error,
+it may preserve the directory to aid in debugging
+
address@hidden
+If the server is killed in a way that it has no way of
+cleaning up (most notably, @samp{kill -KILL} on unix).
+
address@hidden
+If the system shuts down without an orderly shutdown,
+which tells the server to clean up.
address@hidden itemize
+
+In cases such as this, you will need to manually remove
+the @address@hidden directories. As long as
+there is no server running with process identification
+number @var{pid}, it is safe to do so.
+
address@hidden
---------------------------------------------------------------------
address@hidden Starting a new project
address@hidden Starting a project with CVS
address@hidden Starting a project with CVS
address@hidden Creating a project
+
address@hidden --moduledb--
+Because renaming files and moving them between
+directories is somewhat inconvenient, the first thing
+you do when you start a new project should be to think
+through your file organization. It is not impossible
+to rename or move files, but it does increase the
+potential for confusion and @sc{cvs} does have some
+quirks particularly in the area of renaming
+directories. @xref{Moving files}.
+
+What to do next depends on the situation at hand.
+
address@hidden
+* Setting up the files:: Getting the files into the repository
+* Defining the module:: How to make a module of the files
address@hidden menu
address@hidden -- File permissions!
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Setting up the files
address@hidden Setting up the files
+
+The first step is to create the files inside the repository. This can
+be done in a couple of different ways.
+
address@hidden -- The contributed scripts
address@hidden
+* From files:: This method is useful with old projects
+ where files already exists.
+* From other version control systems:: Old projects where you want to
+ preserve history from another system.
+* From scratch:: Creating a directory tree from scratch.
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden From files
address@hidden Creating a directory tree from a number of files
address@hidden Importing files
+
+When you begin using @sc{cvs}, you will probably already have several
+projects that can be
+put under @sc{cvs} control. In these cases the easiest way is to use the
address@hidden command. An example is probably the easiest way to
+explain how to use it. If the files you want to install in
address@hidden reside in @address@hidden, and you want them to appear in the
+repository as @file{$CVSROOT/yoyodyne/@var{rdir}}, you can do this:
+
address@hidden
+$ cd @var{wdir}
+$ cvs import -m "Imported sources" yoyodyne/@var{rdir} yoyo start
address@hidden example
+
+Unless you supply a log message with the @samp{-m}
+flag, @sc{cvs} starts an editor and prompts for a
+message. The string @samp{yoyo} is a @dfn{vendor tag},
+and @samp{start} is a @dfn{release tag}. They may fill
+no purpose in this context, but since @sc{cvs} requires
+them they must be present. @xref{Tracking sources}, for
+more information about them.
+
+You can now verify that it worked, and remove your
+original source directory.
address@hidden FIXME: Need to say more about "verify that it
address@hidden worked". What should the user look for in the output
address@hidden from "diff -r"?
+
address@hidden
+$ cd ..
+$ cvs checkout yoyodyne/@var{rdir} # @r{Explanation below}
+$ diff -r @var{wdir} yoyodyne/@var{rdir}
+$ rm -r @var{wdir}
address@hidden example
+
address@hidden
+Erasing the original sources is a good idea, to make sure that you do
+not accidentally edit them in @var{wdir}, bypassing @sc{cvs}.
+Of course, it would be wise to make sure that you have
+a backup of the sources before you remove them.
+
+The @code{checkout} command can either take a module
+name as argument (as it has done in all previous
+examples) or a path name relative to @code{$CVSROOT},
+as it did in the example above.
+
+It is a good idea to check that the permissions
address@hidden sets on the directories inside @code{$CVSROOT}
+are reasonable, and that they belong to the proper
+groups. @xref{File permissions}.
+
+If some of the files you want to import are binary, you
+may want to use the wrappers features to specify which
+files are binary and which are not. @xref{Wrappers}.
+
address@hidden The node name is too long, but I am having trouble
address@hidden thinking of something more concise.
address@hidden From other version control systems
address@hidden Creating Files From Other Version Control Systems
address@hidden Importing files, from other version control systems
+
+If you have a project which you are maintaining with
+another version control system, such as @sc{rcs}, you
+may wish to put the files from that project into
address@hidden, and preserve the revision history of the
+files.
+
address@hidden @asis
address@hidden RCS, importing files from
address@hidden From RCS
+If you have been using @sc{rcs}, find the @sc{rcs}
+files---usually a file named @file{foo.c} will have its
address@hidden file in @file{RCS/foo.c,v} (but it could be
+other places; consult the @sc{rcs} documentation for
+details). Then create the appropriate directories in
address@hidden if they do not already exist. Then copy the
+files into the appropriate directories in the @sc{cvs}
+repository (the name in the repository must be the name
+of the source file with @samp{,v} added; the files go
+directly in the appropriate directory of the repository,
+not in an @file{RCS} subdirectory). This is one of the
+few times when it is a good idea to access the @sc{cvs}
+repository directly, rather than using @sc{cvs}
+commands. Then you are ready to check out a new
+working directory.
address@hidden Someday there probably should be a "cvs import -t
address@hidden rcs" or some such. It could even create magic
address@hidden branches. It could also do something about the case
address@hidden where the RCS file had a (non-magic) "0" branch.
+
+The @sc{rcs} file should not be locked when you move it
+into @sc{cvs}; if it is, @sc{cvs} will have trouble
+letting you operate on it.
address@hidden What is the easiest way to unlock your files if you
address@hidden have them locked? Especially if you have a lot of them?
address@hidden This is a CVS bug/misfeature; importing RCS files
address@hidden should ignore whether they are locked and leave them in
address@hidden an unlocked state. Yet another reason for a separate
address@hidden "import RCS file" command.
+
address@hidden How many is "many"? Or do they just import RCS files?
address@hidden From another version control system
+Many version control systems have the ability to export
address@hidden files in the standard format. If yours does,
+export the @sc{rcs} files and then follow the above
+instructions.
+
+Failing that, probably your best bet is to write a
+script that will check out the files one revision at a
+time using the command line interface to the other
+system, and then check the revisions into @sc{cvs}.
+The @file{sccs2rcs} script mentioned below may be a
+useful example to follow.
+
address@hidden SCCS, importing files from
address@hidden From SCCS
+There is a script in the @file{contrib} directory of
+the @sc{cvs} source distribution called @file{sccs2rcs}
+which converts @sc{sccs} files to @sc{rcs} files.
+Note: you must run it on a machine which has both
address@hidden and @sc{rcs} installed, and like everything
+else in contrib it is unsupported (your mileage may
+vary).
+
address@hidden PVCS, importing files from
address@hidden From PVCS
+There is a script in the @file{contrib} directory of
+the @sc{cvs} source distribution called @file{pvcs_to_rcs}
+which converts @sc{pvcs} archives to @sc{rcs} files.
+You must run it on a machine which has both
address@hidden and @sc{rcs} installed, and like everything
+else in contrib it is unsupported (your mileage may
+vary). See the comments in the script for details.
address@hidden table
address@hidden CMZ and/or PATCHY were systems that were used in the
address@hidden high energy physics community (especially for
address@hidden CERNLIB). CERN has replaced them with CVS, but the
address@hidden CAR format seems to live on as a way to submit
address@hidden changes. There is a program car2cvs which converts
address@hidden but I'm not sure where one gets a copy.
address@hidden Not sure it is worth mentioning here, since it would
address@hidden appear to affect only one particular community.
address@hidden Best page for more information is:
address@hidden http://wwwcn1.cern.ch/asd/cvs/index.html
address@hidden See also:
address@hidden http://ecponion.cern.ch/ecpsa/cernlib.html
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden From scratch
address@hidden Creating a directory tree from scratch
+
address@hidden Also/instead should be documenting
address@hidden $ cvs co -l .
address@hidden $ mkdir tc
address@hidden $ cvs add tc
address@hidden $ cd tc
address@hidden $ mkdir man
address@hidden $ cvs add man
address@hidden etc.
address@hidden Using import to create the directories only is
address@hidden probably a somewhat confusing concept.
+For a new project, the easiest thing to do is probably
+to create an empty directory structure, like this:
+
address@hidden
+$ mkdir tc
+$ mkdir tc/man
+$ mkdir tc/testing
address@hidden example
+
+After that, you use the @code{import} command to create
+the corresponding (empty) directory structure inside
+the repository:
+
address@hidden
+$ cd tc
+$ cvs import -m "Created directory structure" yoyodyne/@var{dir} yoyo start
address@hidden example
+
+Then, use @code{add} to add files (and new directories)
+as they appear.
+
+Check that the permissions @sc{cvs} sets on the
+directories inside @code{$CVSROOT} are reasonable.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Defining the module
address@hidden Defining the module
address@hidden Defining a module
address@hidden Editing the modules file
address@hidden Module, defining
address@hidden Modules file, changing
+
+The next step is to define the module in the
address@hidden file. This is not strictly necessary,
+but modules can be convenient in grouping together
+related files and directories.
+
+In simple cases these steps are sufficient to define a module.
+
address@hidden
address@hidden
+Get a working copy of the modules file.
+
address@hidden
+$ cvs checkout CVSROOT/modules
+$ cd CVSROOT
address@hidden example
+
address@hidden
+Edit the file and insert a line that defines the module. @xref{Intro
+administrative files}, for an introduction. @xref{modules}, for a full
+description of the modules file. You can use the
+following line to define the module @samp{tc}:
+
address@hidden
+tc yoyodyne/tc
address@hidden example
+
address@hidden
+Commit your changes to the modules file.
+
address@hidden
+$ cvs commit -m "Added the tc module." modules
address@hidden example
+
address@hidden
+Release the modules module.
+
address@hidden
+$ cd ..
+$ cvs release -d CVSROOT
address@hidden example
address@hidden enumerate
+
address@hidden
---------------------------------------------------------------------
address@hidden Revisions
address@hidden Revisions
+
+For many uses of @sc{cvs}, one doesn't need to worry
+too much about revision numbers; @sc{cvs} assigns
+numbers such as @code{1.1}, @code{1.2}, and so on, and
+that is all one needs to know. However, some people
+prefer to have more knowledge and control concerning
+how @sc{cvs} assigns revision numbers.
+
+If one wants to keep track of a set of revisions
+involving more than one file, such as which revisions
+went into a particular release, one uses a @dfn{tag},
+which is a symbolic revision which can be assigned to a
+numeric revision in each file.
+
address@hidden
+* Revision numbers:: The meaning of a revision number
+* Versions revisions releases:: Terminology used in this manual
+* Assigning revisions:: Assigning revisions
+* Tags:: Tags--Symbolic revisions
+* Tagging the working directory:: The cvs tag command
+* Tagging by date/tag:: The cvs rtag command
+* Modifying tags:: Adding, renaming, and deleting tags
+* Tagging add/remove:: Tags with adding and removing files
+* Sticky tags:: Certain tags are persistent
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Revision numbers
address@hidden Revision numbers
address@hidden Revision numbers
address@hidden Revision tree
address@hidden Linear development
address@hidden Number, revision-
address@hidden Decimal revision number
address@hidden Branch number
address@hidden Number, branch
+
+Each version of a file has a unique @dfn{revision
+number}. Revision numbers look like @samp{1.1},
address@hidden, @samp{1.3.2.2} or even @samp{1.3.2.2.4.5}.
+A revision number always has an even number of
+period-separated decimal integers. By default revision
+1.1 is the first revision of a file. Each successive
+revision is given a new number by increasing the
+rightmost number by one. The following figure displays
+a few revisions, with newer revisions to the right.
+
address@hidden
+ +-----+ +-----+ +-----+ +-----+ +-----+
+ ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
+ +-----+ +-----+ +-----+ +-----+ +-----+
address@hidden example
+
+It is also possible to end up with numbers containing
+more than one period, for example @samp{1.3.2.2}. Such
+revisions represent revisions on branches
+(@pxref{Branching and merging}); such revision numbers
+are explained in detail in @ref{Branches and
+revisions}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Versions revisions releases
address@hidden Versions, revisions and releases
address@hidden Revisions, versions and releases
address@hidden Versions, revisions and releases
address@hidden Releases, revisions and versions
+
+A file can have several versions, as described above.
+Likewise, a software product can have several versions.
+A software product is often given a version number such
+as @samp{4.1.1}.
+
+Versions in the first sense are called @dfn{revisions}
+in this document, and versions in the second sense are
+called @dfn{releases}. To avoid confusion, the word
address@hidden is almost never used in this document.
+
address@hidden Assigning revisions
address@hidden Assigning revisions
+
address@hidden We avoid the "major revision" terminology. It seems
address@hidden like jargon. Hopefully "first number" is clear enough.
address@hidden
address@hidden Well, in the context of software release numbers,
address@hidden "major" and "minor" release or version numbers are
address@hidden documented in at least the GNU Coding Standards, but I'm
address@hidden still not sure I find that a valid reason to apply the
address@hidden terminology to RCS revision numbers. "First", "Second",
address@hidden "subsequent", and so on is almost surely clearer,
address@hidden especially to a novice reader. -DRP
+By default, @sc{cvs} will assign numeric revisions by
+leaving the first number the same and incrementing the
+second number. For example, @code{1.1}, @code{1.2},
address@hidden, etc.
+
+When adding a new file, the second number will always
+be one and the first number will equal the highest
+first number of any file in that directory. For
+example, the current directory contains files whose
+highest numbered revisions are @code{1.7}, @code{3.1},
+and @code{4.12}, then an added file will be given the
+numeric revision @code{4.1}.
+
address@hidden This is sort of redundant with something we said a
address@hidden while ago. Somewhere we need a better way of
address@hidden introducing how the first number can be anything
address@hidden except "1", perhaps. Also I don't think this
address@hidden presentation is clear on why we are discussing releases
address@hidden and first numbers of numeric revisions in the same
address@hidden breath.
+Normally there is no reason to care
+about the revision numbers---it is easier to treat them
+as internal numbers that @sc{cvs} maintains, and tags
+provide a better way to distinguish between things like
+release 1 versus release 2 of your product
+(@pxref{Tags}). However, if you want to set the
+numeric revisions, the @samp{-r} option to @code{cvs
+commit} can do that. The @samp{-r} option implies the
address@hidden option, in the sense that it causes the
+files to be committed even if they are not modified.
+
+For example, to bring all your files up to
+revision 3.0 (including those that haven't changed),
+you might invoke:
+
address@hidden
+$ cvs commit -r 3.0
address@hidden example
+
+Note that the number you specify with @samp{-r} must be
+larger than any existing revision number. That is, if
+revision 3.0 exists, you cannot @samp{cvs commit
+-r 1.3}. If you want to maintain several releases in
+parallel, you need to use a branch (@pxref{Branching and merging}).
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Tags
address@hidden Tags--Symbolic revisions
address@hidden Tags
+
+The revision numbers live a life of their own. They
+need not have anything at all to do with the release
+numbers of your software product. Depending
+on how you use @sc{cvs} the revision numbers might change several times
+between two releases. As an example, some of the
+source files that make up @sc{rcs} 5.6 have the following
+revision numbers:
address@hidden RCS revision numbers
+
address@hidden
+ci.c 5.21
+co.c 5.9
+ident.c 5.3
+rcs.c 5.12
+rcsbase.h 5.11
+rcsdiff.c 5.10
+rcsedit.c 5.11
+rcsfcmp.c 5.9
+rcsgen.c 5.10
+rcslex.c 5.11
+rcsmap.c 5.2
+rcsutil.c 5.10
address@hidden example
+
address@hidden tag (subcommand), introduction
address@hidden Tags, symbolic name
address@hidden Symbolic name (tag)
address@hidden Name, symbolic (tag)
address@hidden HEAD, as reserved tag name
address@hidden BASE, as reserved tag name
+You can use the @code{tag} command to give a symbolic name to a
+certain revision of a file. You can use the @samp{-v} flag to the
address@hidden command to see all tags that a file has, and
+which revision numbers they represent. Tag names must
+start with an uppercase or lowercase letter and can
+contain uppercase and lowercase letters, digits,
address@hidden, and @samp{_}. The two tag names @code{BASE}
+and @code{HEAD} are reserved for use by @sc{cvs}. It
+is expected that future names which are special to
address@hidden will be specially named, for example by
+starting with @samp{.}, rather than being named analogously to
address@hidden and @code{HEAD}, to avoid conflicts with
+actual tag names.
address@hidden Including a character such as % or = has also been
address@hidden suggested as the naming convention for future
address@hidden special tag names. Starting with . is nice because
address@hidden that is not a legal tag name as far as RCS is concerned.
address@hidden FIXME: CVS actually accepts quite a few characters
address@hidden in tag names, not just the ones documented above
address@hidden (see RCS_check_tag). RCS
address@hidden defines legitimate tag names by listing illegal
address@hidden characters rather than legal ones. CVS is said to lose its
address@hidden mind if you try to use "/" (try making such a tag sticky
address@hidden and using "cvs status" client/server--see remote
address@hidden protocol format for entries line for probable cause).
address@hidden TODO: The testsuite
address@hidden should test for whatever are documented above as
address@hidden officially-OK tag names, and CVS should at least reject
address@hidden characters that won't work, like "/".
+
+You'll want to choose some convention for naming tags,
+based on information such as the name of the program
+and the version number of the release. For example,
+one might take the name of the program, immediately
+followed by the version number with @samp{.} changed to
address@hidden, so that @sc{cvs} 1.9 would be tagged with the name
address@hidden If you choose a consistent convention,
+then you won't constantly be guessing whether a tag is
address@hidden or @code{cvs1_9} or what. You might
+even want to consider enforcing your convention in the
+taginfo file (@pxref{user-defined logging}).
address@hidden Might be nice to say more about using taginfo this
address@hidden way, like giving an example, or pointing out any particular
address@hidden issues which arise.
+
address@hidden Adding a tag
address@hidden Tags, example
+The following example shows how you can add a tag to a
+file. The commands must be issued inside your working
+directory. That is, you should issue the
+command in the directory where @file{backend.c}
+resides.
+
address@hidden
+$ cvs tag rel-0-4 backend.c
+T backend.c
+$ cvs status -v backend.c
+===================================================================
+File: backend.c Status: Up-to-date
+
+ Version: 1.4 Tue Dec 1 14:39:01 1992
+ RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v
+ Sticky Tag: (none)
+ Sticky Date: (none)
+ Sticky Options: (none)
+
+ Existing Tags:
+ rel-0-4 (revision: 1.4)
+
address@hidden example
+
+For a complete summary of the syntax of @code{cvs tag},
+including the various options, see @ref{Invoking CVS}.
+
+There is seldom reason to tag a file in isolation. A more common use is
+to tag all the files that constitute a module with the same tag at
+strategic points in the development life-cycle, such as when a release
+is made.
+
address@hidden
+$ cvs tag rel-1-0 .
+cvs tag: Tagging .
+T Makefile
+T backend.c
+T driver.c
+T frontend.c
+T parser.c
address@hidden example
+
address@hidden
+(When you give @sc{cvs} a directory as argument, it generally applies the
+operation to all the files in that directory, and (recursively), to any
+subdirectories that it may contain. @xref{Recursive behavior}.)
+
address@hidden Retrieving an old revision using tags
address@hidden Tags, retrieving old revisions
+The @code{checkout} command has a flag, @samp{-r}, that lets you check out
+a certain revision of a module. This flag makes it easy to
+retrieve the sources that make up release 1.0 of the module @samp{tc} at
+any time in the future:
+
address@hidden
+$ cvs checkout -r rel-1-0 tc
address@hidden example
+
address@hidden
+This is useful, for instance, if someone claims that there is a bug in
+that release, but you cannot find the bug in the current working copy.
+
+You can also check out a module as it was at any given date.
address@hidden options}. When specifying @samp{-r} to
+any of these commands, you will need beware of sticky
+tags; see @ref{Sticky tags}.
+
+When you tag more than one file with the same tag you
+can think about the tag as "a curve drawn through a
+matrix of filename vs. revision number." Say we have 5
+files with the following revisions:
+
address@hidden
address@hidden
+ file1 file2 file3 file4 file5
+
+ 1.1 1.1 1.1 1.1 /--1.1* <-*- TAG
+ 1.2*- 1.2 1.2 -1.2*-
+ 1.3 \- 1.3*- 1.3 / 1.3
+ 1.4 \ 1.4 / 1.4
+ \-1.5*- 1.5
+ 1.6
address@hidden group
address@hidden example
+
+At some time in the past, the @code{*} versions were tagged.
+You can think of the tag as a handle attached to the curve
+drawn through the tagged revisions. When you pull on
+the handle, you get all the tagged revisions. Another
+way to look at it is that you "sight" through a set of
+revisions that is "flat" along the tagged revisions,
+like this:
+
address@hidden
address@hidden
+ file1 file2 file3 file4 file5
+
+ 1.1
+ 1.2
+ 1.1 1.3 _
+ 1.1 1.2 1.4 1.1 /
+ 1.2*----1.3*----1.5*----1.2*----1.1 (--- <--- Look here
+ 1.3 1.6 1.3 \_
+ 1.4 1.4
+ 1.5
address@hidden group
address@hidden example
+
address@hidden Tagging the working directory
address@hidden Specifying what to tag from the working directory
+
address@hidden tag (subcommand)
+The example in the previous section demonstrates one of
+the most common ways to choose which revisions to tag.
+Namely, running the @code{cvs tag} command without
+arguments causes @sc{cvs} to select the revisions which
+are checked out in the current working directory. For
+example, if the copy of @file{backend.c} in working
+directory was checked out from revision 1.4, then
address@hidden will tag revision 1.4. Note that the tag is
+applied immediately to revision 1.4 in the repository;
+tagging is not like modifying a file, or other
+operations in which one first modifies the working
+directory and then runs @code{cvs commit} to transfer
+that modification to the repository.
+
+One potentially surprising aspect of the fact that
address@hidden tag} operates on the repository is that you
+are tagging the checked-in revisions, which may differ
+from locally modified files in your working directory.
+If you want to avoid doing this by mistake, specify the
address@hidden option to @code{cvs tag}. If there are any
+locally modified files, @sc{cvs} will abort with an
+error before it tags any files:
+
address@hidden
+$ cvs tag -c rel-0-4
+cvs tag: backend.c is locally modified
+cvs [tag aborted]: correct the above errors first!
address@hidden example
+
address@hidden Tagging by date/tag
address@hidden Specifying what to tag by date or revision
address@hidden rtag (subcommand)
+
+The @code{cvs rtag} command tags the repository as of a
+certain date or time (or can be used to tag the latest
+revision). @code{rtag} works directly on the
+repository contents (it requires no prior checkout and
+does not look for a working directory).
+
+The following options specify which date or revision to
+tag. See @ref{Common options}, for a complete
+description of them.
+
address@hidden @code
address@hidden -D @var{date}
+Tag the most recent revision no later than @var{date}.
+
address@hidden -f
+Only useful with the @samp{-D @var{date}} or @samp{-r @var{tag}}
+flags. If no matching revision is found, use the most
+recent revision (instead of ignoring the file).
+
address@hidden -r @var{tag}
+Only tag those files that contain existing tag @var{tag}.
address@hidden table
+
+The @code{cvs tag} command also allows one to specify
+files by revision or date, using the same @samp{-r},
address@hidden, and @samp{-f} options. However, this
+feature is probably not what you want. The reason is
+that @code{cvs tag} chooses which files to tag based on
+the files that exist in the working directory, rather
+than the files which existed as of the given tag/date.
+Therefore, you are generally better off using @code{cvs
+rtag}. The exceptions might be cases like:
+
address@hidden
+cvs tag -r 1.4 stable backend.c
address@hidden example
+
address@hidden Modifying tags
address@hidden Deleting, moving, and renaming tags
+
address@hidden Also see:
address@hidden "How do I move or rename a magic branch tag?"
address@hidden in the FAQ (I think the issues it talks about still
address@hidden apply, but this could use some sanity.sh work).
+
+Normally one does not modify tags. They exist in order
+to record the history of the repository and so deleting
+them or changing their meaning would, generally, not be
+what you want.
+
+However, there might be cases in which one uses a tag
+temporarily or accidentally puts one in the wrong
+place. Therefore, one might delete, move, or rename a
+tag.
+
address@hidden
address@hidden: the commands in this section are
+dangerous; they permanently discard historical
+information and it can be difficult or impossible to
+recover from errors. If you are a @sc{cvs}
+administrator, you may consider restricting these
+commands with taginfo (@pxref{user-defined logging}).}
+
address@hidden Deleting tags
address@hidden Deleting branch tags
address@hidden Removing tags
address@hidden Removing branch tags
address@hidden Tags, deleting
address@hidden Branch tags, deleting
+To delete a tag, specify the @samp{-d} option to either
address@hidden tag} or @code{cvs rtag}. For example:
+
address@hidden
+cvs rtag -d rel-0-4 tc
address@hidden example
+
address@hidden
+deletes the non-branch tag @code{rel-0-4} from the module @code{tc}.
+In the event that branch tags are encountered within the repository
+with the given name, a warning message will be issued and the branch
+tag will not be deleted. If you are absolutely certain you know what
+you are doing, the @code{-B} option may be specified to allow deletion
+of branch tags. In that case, any non-branch tags encountered will
+trigger warnings and will not be deleted.
+
address@hidden
address@hidden: Moving branch tags is very dangerous! If you think
+you need the @code{-B} option, think again and ask your @sc{cvs}
+administrator about it (if that isn't you). There is almost certainly
+another way to accomplish what you want to accomplish.}
+
address@hidden Moving tags
address@hidden Moving branch tags
address@hidden Tags, moving
address@hidden Branch tags, moving
+When we say @dfn{move} a tag, we mean to make the same
+name point to different revisions. For example, the
address@hidden tag may currently point to revision 1.4
+of @file{backend.c} and perhaps we want to make it
+point to revision 1.6. To move a non-branch tag, specify the
address@hidden option to either @code{cvs tag} or @code{cvs
+rtag}. For example, the task just mentioned might be
+accomplished as:
+
address@hidden
+cvs tag -r 1.6 -F stable backend.c
address@hidden example
+
address@hidden
+If any branch tags are encountered in the repository
+with the given name, a warning is issued and the branch
+tag is not disturbed. If you are absolutely certain you
+wish to move the branch tag, the @code{-B} option may be specified.
+In that case, non-branch tags encountered with the given
+name are ignored with a warning message.
+
address@hidden
address@hidden: Moving branch tags is very dangerous! If you think you
+need the @code{-B} option, think again and ask your @sc{cvs}
+administrator about it (if that isn't you). There is almost certainly
+another way to accomplish what you want to accomplish.}
+
address@hidden Renaming tags
address@hidden Tags, renaming
+When we say @dfn{rename} a tag, we mean to make a
+different name point to the same revisions as the old
+tag. For example, one may have misspelled the tag name
+and want to correct it (hopefully before others are
+relying on the old spelling). To rename a tag, first
+create a new tag using the @samp{-r} option to
address@hidden rtag}, and then delete the old name. (Caution:
+this method will not work with branch tags.)
+This leaves the new tag on exactly the
+same files as the old tag. For example:
+
address@hidden
+cvs rtag -r old-name-0-4 rel-0-4 tc
+cvs rtag -d old-name-0-4 tc
address@hidden example
+
address@hidden Tagging add/remove
address@hidden Tagging and adding and removing files
+
+The subject of exactly how tagging interacts with
+adding and removing files is somewhat obscure; for the
+most part @sc{cvs} will keep track of whether files
+exist or not without too much fussing. By default,
+tags are applied to only files which have a revision
+corresponding to what is being tagged. Files which did
+not exist yet, or which were already removed, simply
+omit the tag, and @sc{cvs} knows to treat the absence
+of a tag as meaning that the file didn't exist as of
+that tag.
+
+However, this can lose a small amount of information.
+For example, suppose a file was added and then removed.
+Then, if the tag is missing for that file, there is no
+way to know whether the tag refers to the time before
+the file was added, or the time after it was removed.
+If you specify the @samp{-r} option to @code{cvs rtag},
+then @sc{cvs} tags the files which have been removed,
+and thereby avoids this problem. For example, one
+might specify @code{-r HEAD} to tag the head.
+
+On the subject of adding and removing files, the
address@hidden rtag} command has a @samp{-a} option which
+means to clear the tag from removed files that would
+not otherwise be tagged. For example, one might
+specify this option in conjunction with @samp{-F} when
+moving a tag. If one moved a tag without @samp{-a},
+then the tag in the removed files might still refer to
+the old revision, rather than reflecting the fact that
+the file had been removed. I don't think this is
+necessary if @samp{-r} is specified, as noted above.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Sticky tags
address@hidden Sticky tags
address@hidden Sticky tags
address@hidden Tags, sticky
+
address@hidden A somewhat related issue is per-directory sticky
address@hidden tags (see comment at CVS/Tag in node Working
address@hidden directory storage); we probably want to say
address@hidden something like "you can set a sticky tag for only
address@hidden some files, but you don't want to" or some such.
+
+Sometimes a working copy's revision has extra data
+associated with it, for example it might be on a branch
+(@pxref{Branching and merging}), or restricted to
+versions prior to a certain date by @samp{checkout -D}
+or @samp{update -D}. Because this data persists --
+that is, it applies to subsequent commands in the
+working copy -- we refer to it as @dfn{sticky}.
+
+Most of the time, stickiness is an obscure aspect of
address@hidden that you don't need to think about. However,
+even if you don't want to use the feature, you may need
+to know @emph{something} about sticky tags (for
+example, how to avoid them!).
+
+You can use the @code{status} command to see if any
+sticky tags or dates are set:
+
address@hidden
+$ cvs status driver.c
+===================================================================
+File: driver.c Status: Up-to-date
+
+ Version: 1.7.2.1 Sat Dec 5 19:35:03 1992
+ RCS Version: 1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v
+ Sticky Tag: rel-1-0-patches (branch: 1.7.2)
+ Sticky Date: (none)
+ Sticky Options: (none)
+
address@hidden example
+
address@hidden Resetting sticky tags
address@hidden Sticky tags, resetting
address@hidden Deleting sticky tags
+The sticky tags will remain on your working files until
+you delete them with @samp{cvs update -A}. The
address@hidden option merges local changes into the version of the
+file from the head of the trunk, removing any sticky tags,
+dates, or options. See @ref{update} for more on the operation
+of @code{cvs update}.
+
address@hidden Sticky date
+The most common use of sticky tags is to identify which
+branch one is working on, as described in
address@hidden branches}. However, non-branch
+sticky tags have uses as well. For example,
+suppose that you want to avoid updating your working
+directory, to isolate yourself from possibly
+destabilizing changes other people are making. You
+can, of course, just refrain from running @code{cvs
+update}. But if you want to avoid updating only a
+portion of a larger tree, then sticky tags can help.
+If you check out a certain revision (such as 1.4) it
+will become sticky. Subsequent @code{cvs update}
+commands will
+not retrieve the latest revision until you reset the
+tag with @code{cvs update -A}. Likewise, use of the
address@hidden option to @code{update} or @code{checkout}
+sets a @dfn{sticky date}, which, similarly, causes that
+date to be used for future retrievals.
+
+People often want to retrieve an old version of
+a file without setting a sticky tag. This can
+be done with the @samp{-p} option to @code{checkout} or
address@hidden, which sends the contents of the file to
+standard output. For example:
address@hidden
+$ cvs update -p -r 1.1 file1 >file1
+===================================================================
+Checking out file1
+RCS: /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v
+VERS: 1.1
+***************
+$
address@hidden example
+
+However, this isn't the easiest way, if you are asking
+how to undo a previous checkin (in this example, put
address@hidden back to the way it was as of revision
+1.1). In that case you are better off using the
address@hidden option to @code{update}; for further
+discussion see @ref{Merging two revisions}.
+
address@hidden
---------------------------------------------------------------------
address@hidden Branching and merging
address@hidden Branching and merging
address@hidden Branching
address@hidden Merging
address@hidden Copying changes
address@hidden Main trunk and branches
address@hidden Revision tree, making branches
address@hidden Branches, copying changes between
address@hidden Changes, copying between branches
address@hidden Modifications, copying between branches
+
address@hidden allows you to isolate changes onto a separate
+line of development, known as a @dfn{branch}. When you
+change files on a branch, those changes do not appear
+on the main trunk or other branches.
+
+Later you can move changes from one branch to another
+branch (or the main trunk) by @dfn{merging}. Merging
+involves first running @code{cvs update -j}, to merge
+the changes into the working directory.
+You can then commit that revision, and thus effectively
+copy the changes onto another branch.
+
address@hidden
+* Branches motivation:: What branches are good for
+* Creating a branch:: Creating a branch
+* Accessing branches:: Checking out and updating branches
+* Branches and revisions:: Branches are reflected in revision numbers
+* Magic branch numbers:: Magic branch numbers
+* Merging a branch:: Merging an entire branch
+* Merging more than once:: Merging from a branch several times
+* Merging two revisions:: Merging differences between two revisions
+* Merging adds and removals:: What if files are added or removed?
+* Merging and keywords:: Avoiding conflicts due to keyword substitution
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Branches motivation
address@hidden What branches are good for
address@hidden Branches motivation
address@hidden What branches are good for
address@hidden Motivation for branches
+
address@hidden FIXME: this node mentions one way to use branches,
address@hidden but it is by no means the only way. For example,
address@hidden the technique of committing a new feature on a branch,
address@hidden until it is ready for the main trunk. The whole
address@hidden thing is generally speaking more akin to the
address@hidden "Revision management" node although it isn't clear to
address@hidden me whether policy matters should be centralized or
address@hidden distributed throughout the relevant sections.
+Suppose that release 1.0 of tc has been made. You are continuing to
+develop tc, planning to create release 1.1 in a couple of months. After a
+while your customers start to complain about a fatal bug. You check
+out release 1.0 (@pxref{Tags}) and find the bug
+(which turns out to have a trivial fix). However, the current revision
+of the sources are in a state of flux and are not expected to be stable
+for at least another month. There is no way to make a
+bugfix release based on the newest sources.
+
+The thing to do in a situation like this is to create a @dfn{branch} on
+the revision trees for all the files that make up
+release 1.0 of tc. You can then make
+modifications to the branch without disturbing the main trunk. When the
+modifications are finished you can elect to either incorporate them on
+the main trunk, or leave them on the branch.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Creating a branch
address@hidden Creating a branch
address@hidden Creating a branch
address@hidden Branch, creating a
address@hidden tag (subcommand), creating a branch using
address@hidden rtag (subcommand), creating a branch using
+
+You can create a branch with @code{tag -b}; for
+example, assuming you're in a working copy:
+
address@hidden
+$ cvs tag -b rel-1-0-patches
address@hidden example
+
address@hidden FIXME: we should be more explicit about the value of
address@hidden having a tag on the branchpoint. For example
address@hidden "cvs tag rel-1-0-patches-branchpoint" before
address@hidden the "cvs tag -b". This points out that
address@hidden rel-1-0-patches is a pretty awkward name for
address@hidden this example (more so than for the rtag example
address@hidden below).
+
+This splits off a branch based on the current revisions
+in the working copy, assigning that branch the name
address@hidden
+
+It is important to understand that branches get created
+in the repository, not in the working copy. Creating a
+branch based on current revisions, as the above example
+does, will @emph{not} automatically switch the working
+copy to be on the new branch. For information on how
+to do that, see @ref{Accessing branches}.
+
+You can also create a branch without reference to any
+working copy, by using @code{rtag}:
+
address@hidden
+$ cvs rtag -b -r rel-1-0 rel-1-0-patches tc
address@hidden example
+
address@hidden rel-1-0} says that this branch should be
+rooted at the revision that
+corresponds to the tag @samp{rel-1-0}. It need not
+be the most recent revision -- it's often useful to
+split a branch off an old revision (for example, when
+fixing a bug in a past release otherwise known to be
+stable).
+
+As with @samp{tag}, the @samp{-b} flag tells
address@hidden to create a branch (rather than just a
+symbolic revision name). Note that the numeric
+revision number that matches @samp{rel-1-0} will
+probably be different from file to file.
+
+So, the full effect of the command is to create a new
+branch -- named @samp{rel-1-0-patches} -- in module
address@hidden, rooted in the revision tree at the point tagged
+by @samp{rel-1-0}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Accessing branches
address@hidden Accessing branches
address@hidden Check out a branch
address@hidden Retrieve a branch
address@hidden Access a branch
address@hidden Identifying a branch
address@hidden Branch, check out
address@hidden Branch, retrieving
address@hidden Branch, accessing
address@hidden Branch, identifying
+
+You can retrieve a branch in one of two ways: by
+checking it out fresh from the repository, or by
+switching an existing working copy over to the branch.
+
+To check out a branch from the repository, invoke
address@hidden with the @samp{-r} flag, followed by
+the tag name of the branch (@pxref{Creating a branch}):
+
address@hidden
+$ cvs checkout -r rel-1-0-patches tc
address@hidden example
+
+Or, if you already have a working copy, you can switch
+it to a given branch with @samp{update -r}:
+
address@hidden
+$ cvs update -r rel-1-0-patches tc
address@hidden example
+
address@hidden
+or equivalently:
+
address@hidden
+$ cd tc
+$ cvs update -r rel-1-0-patches
address@hidden example
+
+It does not matter if the working copy was originally
+on the main trunk or on some other branch -- the above
+command will switch it to the named branch. And
+similarly to a regular @samp{update} command,
address@hidden -r} merges any changes you have made,
+notifying you of conflicts where they occur.
+
+Once you have a working copy tied to a particular
+branch, it remains there until you tell it otherwise.
+This means that changes checked in from the working
+copy will add new revisions on that branch, while
+leaving the main trunk and other branches unaffected.
+
address@hidden Branches, sticky
+To find out what branch a working copy is on, you can
+use the @samp{status} command. In its output, look for
+the field named @samp{Sticky tag} (@pxref{Sticky tags})
+-- that's @sc{cvs}'s way of telling you the branch, if
+any, of the current working files:
+
address@hidden
+$ cvs status -v driver.c backend.c
+===================================================================
+File: driver.c Status: Up-to-date
+
+ Version: 1.7 Sat Dec 5 18:25:54 1992
+ RCS Version: 1.7 /u/cvsroot/yoyodyne/tc/driver.c,v
+ Sticky Tag: rel-1-0-patches (branch: 1.7.2)
+ Sticky Date: (none)
+ Sticky Options: (none)
+
+ Existing Tags:
+ rel-1-0-patches (branch: 1.7.2)
+ rel-1-0 (revision: 1.7)
+
+===================================================================
+File: backend.c Status: Up-to-date
+
+ Version: 1.4 Tue Dec 1 14:39:01 1992
+ RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v
+ Sticky Tag: rel-1-0-patches (branch: 1.4.2)
+ Sticky Date: (none)
+ Sticky Options: (none)
+
+ Existing Tags:
+ rel-1-0-patches (branch: 1.4.2)
+ rel-1-0 (revision: 1.4)
+ rel-0-4 (revision: 1.4)
+
address@hidden example
+
+Don't be confused by the fact that the branch numbers
+for each file are different (@samp{1.7.2} and
address@hidden respectively). The branch tag is the
+same, @samp{rel-1-0-patches}, and the files are
+indeed on the same branch. The numbers simply reflect
+the point in each file's revision history at which the
+branch was made. In the above example, one can deduce
+that @samp{driver.c} had been through more changes than
address@hidden before this branch was created.
+
+See @ref{Branches and revisions} for details about how
+branch numbers are constructed.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Branches and revisions
address@hidden Branches and revisions
address@hidden Branch number
address@hidden Number, branch
address@hidden Revision numbers (branches)
+
+Ordinarily, a file's revision history is a linear
+series of increments (@pxref{Revision numbers}):
+
address@hidden
+ +-----+ +-----+ +-----+ +-----+ +-----+
+ ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
+ +-----+ +-----+ +-----+ +-----+ +-----+
address@hidden example
+
+However, @sc{cvs} is not limited to linear development. The
address@hidden tree} can be split into @dfn{branches},
+where each branch is a self-maintained line of
+development. Changes made on one branch can easily be
+moved back to the main trunk.
+
+Each branch has a @dfn{branch number}, consisting of an
+odd number of period-separated decimal integers. The
+branch number is created by appending an integer to the
+revision number where the corresponding branch forked
+off. Having branch numbers allows more than one branch
+to be forked off from a certain revision.
+
address@hidden 3500
+All revisions on a branch have revision numbers formed
+by appending an ordinal number to the branch number.
+The following figure illustrates branching with an
+example.
+
address@hidden
address@hidden This example used to have a 1.2.2.4 revision, which
address@hidden might help clarify that development can continue on
address@hidden 1.2.2. Might be worth reinstating if it can be done
address@hidden without overfull hboxes.
address@hidden
+ +-------------+
+ Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 !
+ / +-------------+
+ /
+ /
+ +---------+ +---------+ +---------+
+Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
+ / +---------+ +---------+ +---------+
+ /
+ /
++-----+ +-----+ +-----+ +-----+ +-----+
+! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
++-----+ +-----+ +-----+ +-----+ +-----+
+ !
+ !
+ ! +---------+ +---------+ +---------+
+Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 !
+ +---------+ +---------+ +---------+
+
address@hidden group
address@hidden example
+
address@hidden -- However, at least for me the figure is not enough. I
suggest more
address@hidden -- text to accompany it. "A picture is worth a thousand
words", so you
address@hidden -- have to make sure the reader notices the couple of hundred
words
address@hidden -- *you* had in mind more than the others!
+
address@hidden -- Why an even number of segments? This section implies that
this is
address@hidden -- how the main trunk is distinguished from branch roots, but
you never
address@hidden -- explicitly say that this is the purpose of the [by itself
rather
address@hidden -- surprising] restriction to an even number of segments.
+
+The exact details of how the branch number is
+constructed is not something you normally need to be
+concerned about, but here is how it works: When
address@hidden creates a branch number it picks the first
+unused even integer, starting with 2. So when you want
+to create a branch from revision 6.4 it will be
+numbered 6.4.2. All branch numbers ending in a zero
+(such as 6.4.0) are used internally by @sc{cvs}
+(@pxref{Magic branch numbers}). The branch 1.1.1 has a
+special meaning. @xref{Tracking sources}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Magic branch numbers
address@hidden Magic branch numbers
+
address@hidden Want xref to here from "log"?
+
+This section describes a @sc{cvs} feature called
address@hidden branches}. For most purposes, you need not
+worry about magic branches; @sc{cvs} handles them for
+you. However, they are visible to you in certain
+circumstances, so it may be useful to have some idea of
+how it works.
+
+Externally, branch numbers consist of an odd number of
+dot-separated decimal integers. @xref{Revision
+numbers}. That is not the whole truth, however. For
+efficiency reasons @sc{cvs} sometimes inserts an extra 0
+in the second rightmost position (1.2.4 becomes
+1.2.0.4, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so
+on).
+
address@hidden does a pretty good job at hiding these so
+called magic branches, but in a few places the hiding
+is incomplete:
+
address@hidden @bullet
address@hidden
+The magic branch number appears in the output from
address@hidden log}.
address@hidden What output should appear instead?
+
address@hidden
+You cannot specify a symbolic branch name to @code{cvs
+admin}.
+
address@hidden itemize
+
address@hidden Can CVS do this automatically the first time
address@hidden you check something in to that branch? Should
address@hidden it?
+You can use the @code{admin} command to reassign a
+symbolic name to a branch the way @sc{rcs} expects it
+to be. If @code{R4patches} is assigned to the branch
+1.4.2 (magic branch number 1.4.0.2) in file
address@hidden you can do this:
+
address@hidden
+$ cvs admin -NR4patches:1.4.2 numbers.c
address@hidden example
+
+It only works if at least one revision is already
+committed on the branch. Be very careful so that you
+do not assign the tag to the wrong number. (There is
+no way to see how the tag was assigned yesterday).
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Merging a branch
address@hidden Merging an entire branch
address@hidden Merging a branch
address@hidden -j (merging branches)
+
+You can merge changes made on a branch into your working copy by giving
+the @samp{-j @var{branchname}} flag to the @code{update} subcommand. With one
address@hidden @var{branchname}} option it merges the changes made between the
+greatest common ancestor (GCA) of the branch and the destination revision (in
+the simple case below the GCA is the point where the branch forked) and the
+newest revision on that branch into your working copy.
+
address@hidden Join
+The @samp{-j} stands for ``join''.
+
address@hidden Branch merge example
address@hidden Example, branch merge
address@hidden Merge, branch example
+Consider this revision tree:
+
address@hidden
++-----+ +-----+ +-----+ +-----+
+! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 ! <- The main trunk
++-----+ +-----+ +-----+ +-----+
+ !
+ !
+ ! +---------+ +---------+
+Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
+ +---------+ +---------+
address@hidden example
+
address@hidden
+The branch 1.2.2 has been given the tag (symbolic name) @samp{R1fix}. The
+following example assumes that the module @samp{mod} contains only one
+file, @file{m.c}.
+
address@hidden
+$ cvs checkout mod # @r{Retrieve the latest revision, 1.4}
+
+$ cvs update -j R1fix m.c # @r{Merge all changes made on the branch,}
+ # @r{i.e. the changes between revision 1.2}
+ # @r{and 1.2.2.2, into your working copy}
+ # @r{of the file.}
+
+$ cvs commit -m "Included R1fix" # @r{Create revision 1.5.}
address@hidden example
+
+A conflict can result from a merge operation. If that
+happens, you should resolve it before committing the
+new revision. @xref{Conflicts example}.
+
+If your source files contain keywords (@pxref{Keyword substitution}),
+you might be getting more conflicts than strictly necessary. See
address@hidden and keywords}, for information on how to avoid this.
+
+The @code{checkout} command also supports the @samp{-j @var{branchname}} flag.
The
+same effect as above could be achieved with this:
+
address@hidden
+$ cvs checkout -j R1fix mod
+$ cvs commit -m "Included R1fix"
address@hidden example
+
+It should be noted that @code{update -j @var{tagname}} will also work but may
+not produce the desired result. @xref{Merging adds and removals}, for more.
+
address@hidden Merging more than once
address@hidden Merging from a branch several times
+
+Continuing our example, the revision tree now looks
+like this:
+
address@hidden
++-----+ +-----+ +-----+ +-----+ +-----+
+! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
++-----+ +-----+ +-----+ +-----+ +-----+
+ ! *
+ ! *
+ ! +---------+ +---------+
+Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
+ +---------+ +---------+
address@hidden example
+
address@hidden
+where the starred line represents the merge from the
address@hidden branch to the main trunk, as just
+discussed.
+
+Now suppose that development continues on the
address@hidden branch:
+
address@hidden
++-----+ +-----+ +-----+ +-----+ +-----+
+! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
++-----+ +-----+ +-----+ +-----+ +-----+
+ ! *
+ ! *
+ ! +---------+ +---------+ +---------+
+Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
+ +---------+ +---------+ +---------+
address@hidden example
+
address@hidden
+and then you want to merge those new changes onto the
+main trunk. If you just use the @code{cvs update -j
+R1fix m.c} command again, @sc{cvs} will attempt to
+merge again the changes which you have already merged,
+which can have undesirable side effects.
+
+So instead you need to specify that you only want to
+merge the changes on the branch which have not yet been
+merged into the trunk. To do that you specify two
address@hidden options, and @sc{cvs} merges the changes from
+the first revision to the second revision. For
+example, in this case the simplest way would be
+
address@hidden
+cvs update -j 1.2.2.2 -j R1fix m.c # @r{Merge changes from 1.2.2.2 to the}
+ # @r{head of the R1fix branch}
address@hidden example
+
+The problem with this is that you need to specify the
+1.2.2.2 revision manually. A slightly better approach
+might be to use the date the last merge was done:
+
address@hidden
+cvs update -j R1fix:yesterday -j R1fix m.c
address@hidden example
+
+Better yet, tag the R1fix branch after every merge into
+the trunk, and then use that tag for subsequent merges:
+
address@hidden
+cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Merging two revisions
address@hidden Merging differences between any two revisions
address@hidden Merging two revisions
address@hidden Revisions, merging differences between
address@hidden Differences, merging
+
+With two @samp{-j @var{revision}} flags, the @code{update}
+(and @code{checkout}) command can merge the differences
+between any two revisions into your working file.
+
address@hidden Undoing a change
address@hidden Removing a change
address@hidden
+$ cvs update -j 1.5 -j 1.3 backend.c
address@hidden example
+
address@hidden
+will undo all changes made between revision
+1.3 and 1.5. Note the order of the revisions!
+
+If you try to use this option when operating on
+multiple files, remember that the numeric revisions will
+probably be very different between the various files.
+You almost always use symbolic
+tags rather than revision numbers when operating on
+multiple files.
+
address@hidden Restoring old version of removed file
address@hidden Resurrecting old version of dead file
+Specifying two @samp{-j} options can also undo file
+removals or additions. For example, suppose you have
+a file
+named @file{file1} which existed as revision 1.1, and
+you then removed it (thus adding a dead revision 1.2).
+Now suppose you want to add it again, with the same
+contents it had previously. Here is how to do it:
+
address@hidden
+$ cvs update -j 1.2 -j 1.1 file1
+U file1
+$ cvs commit -m test
+Checking in file1;
+/tmp/cvs-sanity/cvsroot/first-dir/file1,v <-- file1
+new revision: 1.3; previous revision: 1.2
+done
+$
address@hidden example
+
address@hidden Merging adds and removals
address@hidden Merging can add or remove files
+
+If the changes which you are merging involve removing
+or adding some files, @code{update -j} will reflect
+such additions or removals.
+
address@hidden FIXME: This example needs a lot more explanation.
address@hidden We also need other examples for some of the other
address@hidden cases (not all--there are too many--as long as we present a
address@hidden coherent general principle).
+For example:
address@hidden
+cvs update -A
+touch a b c
+cvs add a b c ; cvs ci -m "added" a b c
+cvs tag -b branchtag
+cvs update -r branchtag
+touch d ; cvs add d
+rm a ; cvs rm a
+cvs ci -m "added d, removed a"
+cvs update -A
+cvs update -jbranchtag
address@hidden example
+
+After these commands are executed and a @samp{cvs commit} is done,
+file @file{a} will be removed and file @file{d} added in the main branch.
address@hidden (which was determined by trying it)
+
+Note that using a single static tag (@samp{-j @var{tagname}})
+rather than a dynamic tag (@samp{-j @var{branchname}}) to merge
+changes from a branch will usually not remove files which were removed on the
+branch since @sc{cvs} does not automatically add static tags to dead revisions.
+The exception to this rule occurs when
+a static tag has been attached to a dead revision manually. Use the branch tag
+to merge all changes from the branch or use two static tags as merge endpoints
+to be sure that all intended changes are propagated in the merge.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Merging and keywords
address@hidden Merging and keywords
address@hidden Merging, and keyword substitution
address@hidden Keyword substitution, and merging
address@hidden -j (merging branches), and keyword substitution
address@hidden -kk, to avoid conflicts during a merge
+
+If you merge files containing keywords (@pxref{Keyword
+substitution}), you will normally get numerous
+conflicts during the merge, because the keywords are
+expanded differently in the revisions which you are
+merging.
+
+Therefore, you will often want to specify the
address@hidden (@pxref{Substitution modes}) switch to the
+merge command line. By substituting just the name of
+the keyword, not the expanded value of that keyword,
+this option ensures that the revisions which you are
+merging will be the same as each other, and avoid
+spurious conflicts.
+
+For example, suppose you have a file like this:
+
address@hidden
+ +---------+
+ _! 1.1.2.1 ! <- br1
+ / +---------+
+ /
+ /
++-----+ +-----+
+! 1.1 !----! 1.2 !
++-----+ +-----+
address@hidden example
+
address@hidden
+and your working directory is currently on the trunk
+(revision 1.2). Then you might get the following
+results from a merge:
+
address@hidden
+$ cat file1
+key address@hidden: 1.2 $
+. . .
+$ cvs update -j br1
+U file1
+RCS file: /cvsroot/first-dir/file1,v
+retrieving revision 1.1
+retrieving revision 1.1.2.1
+Merging differences between 1.1 and 1.1.2.1 into file1
+rcsmerge: warning: conflicts during merge
+$ cat file1
address@hidden<<<<<<< file1
+key address@hidden: 1.2 $
address@hidden
+key address@hidden: 1.1.2.1 $
address@hidden>>>>>>> 1.1.2.1
+. . .
address@hidden example
+
+What happened was that the merge tried to merge the
+differences between 1.1 and 1.1.2.1 into your working
+directory. So, since the keyword changed from
address@hidden: 1.1} to @code{Revision: 1.1.2.1},
address@hidden tried to merge that change into your working
+directory, which conflicted with the fact that your
+working directory had contained @code{Revision: 1.2}.
+
+Here is what happens if you had used @samp{-kk}:
+
address@hidden
+$ cat file1
+key address@hidden: 1.2 $
+. . .
+$ cvs update -kk -j br1
+U file1
+RCS file: /cvsroot/first-dir/file1,v
+retrieving revision 1.1
+retrieving revision 1.1.2.1
+Merging differences between 1.1 and 1.1.2.1 into file1
+$ cat file1
+key address@hidden
+. . .
address@hidden example
+
+What is going on here is that revision 1.1 and 1.1.2.1
+both expand as plain @code{Revision}, and therefore
+merging the changes between them into the working
+directory need not change anything. Therefore, there
+is no conflict.
+
address@hidden: In versions of @sc{cvs} prior to 1.12.2, there was a
+major problem with using @samp{-kk} on merges. Namely, @samp{-kk}
+overrode any default keyword expansion mode set in the archive file in
+the repository. This could, unfortunately for some users, cause data
+corruption in binary files (with a default keyword expansion mode set
+to @samp{-kb}). Therefore, when a repository contained binary files,
+conflicts had to be dealt with manually rather than using @samp{-kk} in
+a merge command.}
+
+In @sc{cvs} version 1.12.2 and later, the keyword expansion mode
+provided on the command line to any @sc{cvs} command no longer
+overrides the @samp{-kb} keyword expansion mode setting for binary
+files, though it will still override other default keyword expansion
+modes. You can now safely merge using @samp{-kk} to avoid spurious conflicts
+on lines containing RCS keywords, even when your repository contains
+binary files.
+
address@hidden
---------------------------------------------------------------------
address@hidden Recursive behavior
address@hidden Recursive behavior
address@hidden Recursive (directory descending)
address@hidden Directory, descending
address@hidden Descending directories
address@hidden Subdirectories
+
+Almost all of the subcommands of @sc{cvs} work
+recursively when you specify a directory as an
+argument. For instance, consider this directory
+structure:
+
address@hidden
+ @code{$HOME}
+ |
+ address@hidden
+ | |
+ address@hidden
+ | (internal @sc{cvs} files)
+ address@hidden
+ address@hidden
+ address@hidden
+ address@hidden
+ address@hidden
+ address@hidden
+ | |
+ | address@hidden
+ | | (internal @sc{cvs} files)
+ | address@hidden
+ |
+ address@hidden
+ |
+ address@hidden
+ | (internal @sc{cvs} files)
+ address@hidden
+ address@hidden
address@hidden example
+
address@hidden
+If @file{tc} is the current working directory, the
+following is true:
+
address@hidden @bullet
address@hidden
address@hidden update testing} is equivalent to
+
address@hidden
+cvs update testing/testpgm.t testing/test2.t
address@hidden example
+
address@hidden
address@hidden update testing man} updates all files in the
+subdirectories
+
address@hidden
address@hidden update .} or just @samp{cvs update} updates
+all files in the @code{tc} directory
address@hidden itemize
+
+If no arguments are given to @code{update} it will
+update all files in the current working directory and
+all its subdirectories. In other words, @file{.} is a
+default argument to @code{update}. This is also true
+for most of the @sc{cvs} subcommands, not only the
address@hidden command.
+
+The recursive behavior of the @sc{cvs} subcommands can be
+turned off with the @samp{-l} option.
+Conversely, the @samp{-R} option can be used to force recursion if
address@hidden is specified in @file{~/.cvsrc} (@pxref{~/.cvsrc}).
+
address@hidden
+$ cvs update -l # @r{Don't update files in subdirectories}
address@hidden example
+
address@hidden
---------------------------------------------------------------------
address@hidden Adding and removing
address@hidden Adding, removing, and renaming files and directories
+
+In the course of a project, one will often add new
+files. Likewise with removing or renaming, or with
+directories. The general concept to keep in mind in
+all these cases is that instead of making an
+irreversible change you want @sc{cvs} to record the
+fact that a change has taken place, just as with
+modifying an existing file. The exact mechanisms to do
+this in @sc{cvs} vary depending on the situation.
+
address@hidden
+* Adding files:: Adding files
+* Removing files:: Removing files
+* Removing directories:: Removing directories
+* Moving files:: Moving and renaming files
+* Moving directories:: Moving and renaming directories
address@hidden menu
+
address@hidden Adding files
address@hidden Adding files to a directory
address@hidden Adding files
+
+To add a new file to a directory, follow these steps.
+
address@hidden @bullet
address@hidden
+You must have a working copy of the directory.
address@hidden the source}.
+
address@hidden
+Create the new file inside your working copy of the directory.
+
address@hidden
+Use @samp{cvs add @var{filename}} to tell @sc{cvs} that you
+want to version control the file. If the file contains
+binary data, specify @samp{-kb} (@pxref{Binary files}).
+
address@hidden
+Use @samp{cvs commit @var{filename}} to actually check
+in the file into the repository. Other developers
+cannot see the file until you perform this step.
address@hidden itemize
+
+You can also use the @code{add} command to add a new
+directory.
address@hidden FIXCVS and/or FIXME: Adding a directory doesn't
address@hidden require the commit step. This probably can be
address@hidden considered a CVS bug, but it is possible we should
address@hidden warn people since this behavior probably won't be
address@hidden changing right away.
+
+Unlike most other commands, the @code{add} command is
+not recursive. You cannot even type @samp{cvs add
+foo/bar}! Instead, you have to
address@hidden FIXCVS: This is, of course, not a feature. It is
address@hidden just that no one has gotten around to fixing "cvs add
address@hidden foo/bar".
+
address@hidden
+$ cd foo
+$ cvs add bar
address@hidden example
+
address@hidden add (subcommand)
address@hidden Command {cvs add} address@hidden kflag] address@hidden message]
files @dots{}
+
+Schedule @var{files} to be added to the repository.
+The files or directories specified with @code{add} must
+already exist in the current directory. To add a whole
+new directory hierarchy to the source repository (for
+example, files received from a third-party vendor), use
+the @code{import} command instead. @xref{import}.
+
+The added files are not placed in the source repository
+until you use @code{commit} to make the change
+permanent. Doing an @code{add} on a file that was
+removed with the @code{remove} command will undo the
+effect of the @code{remove}, unless a @code{commit}
+command intervened. @xref{Removing files}, for an
+example.
+
+The @samp{-k} option specifies the default way that
+this file will be checked out; for more information see
address@hidden modes}.
+
address@hidden As noted in BUGS, -m is broken client/server (Nov
address@hidden 96). Also see testsuite log2-* tests.
+The @samp{-m} option specifies a description for the
+file. This description appears in the history log (if
+it is enabled, @pxref{history file}). It will also be
+saved in the version history inside the repository when
+the file is committed. The @code{log} command displays
+this description. The description can be changed using
address@hidden -t}. @xref{admin}. If you omit the
address@hidden @var{description}} flag, an empty string will
+be used. You will not be prompted for a description.
address@hidden deffn
+
+For example, the following commands add the file
address@hidden to the repository:
+
address@hidden This example used to specify
address@hidden -m "Optimizer and code generation passes."
address@hidden to the cvs add command, but that doesn't work
address@hidden client/server (see log2 in sanity.sh). Should fix CVS,
address@hidden but also seems strange to document things which
address@hidden don't work...
address@hidden
+$ cvs add backend.c
+$ cvs commit -m "Early version. Not yet compilable." backend.c
address@hidden example
+
+When you add a file it is added only on the branch
+which you are working on (@pxref{Branching and merging}). You can
+later merge the additions to another branch if you want
+(@pxref{Merging adds and removals}).
address@hidden Should we mention that earlier versions of CVS
address@hidden lacked this feature (1.3) or implemented it in a buggy
address@hidden way (well, 1.8 had many bugs in cvs update -j)?
address@hidden Should we mention the bug/limitation regarding a
address@hidden file being a regular file on one branch and a directory
address@hidden on another?
address@hidden FIXME: This needs an example, or several, here or
address@hidden elsewhere, for it to make much sense.
address@hidden Somewhere we need to discuss the aspects of death
address@hidden support which don't involve branching, I guess.
address@hidden Like the ability to re-create a release from a tag.
+
address@hidden
---------------------------------------------------------------------
address@hidden Removing files
address@hidden Removing files
address@hidden Removing files
address@hidden Deleting files
+
address@hidden FIXME: this node wants to be split into several
address@hidden smaller nodes. Could make these children of
address@hidden "Adding and removing", probably (death support could
address@hidden be its own section, for example, as could the
address@hidden various bits about undoing mistakes in adding and
address@hidden removing).
+Directories change. New files are added, and old files
+disappear. Still, you want to be able to retrieve an
+exact copy of old releases.
+
+Here is what you can do to remove a file,
+but remain able to retrieve old revisions:
+
address@hidden @bullet
address@hidden FIXME: should probably be saying something about
address@hidden having a working directory in the first place.
address@hidden
+Make sure that you have not made any uncommitted
+modifications to the file. @xref{Viewing differences},
+for one way to do that. You can also use the
address@hidden or @code{update} command. If you remove
+the file without committing your changes, you will of
+course not be able to retrieve the file as it was
+immediately before you deleted it.
+
address@hidden
+Remove the file from your working copy of the directory.
+You can for instance use @code{rm}.
+
address@hidden
+Use @samp{cvs remove @var{filename}} to tell @sc{cvs} that
+you really want to delete the file.
+
address@hidden
+Use @samp{cvs commit @var{filename}} to actually
+perform the removal of the file from the repository.
address@hidden itemize
+
address@hidden FIXME: Somehow this should be linked in with a more
address@hidden general discussion of death support. I don't know
address@hidden whether we want to use the term "death support" or
address@hidden not (we can perhaps get by without it), but we do
address@hidden need to discuss the "dead" state in "cvs log" and
address@hidden related subjects. The current discussion is
address@hidden scattered around, and not xref'd to each other.
address@hidden FIXME: I think this paragraph wants to be moved
address@hidden later down, at least after the first example.
+When you commit the removal of the file, @sc{cvs}
+records the fact that the file no longer exists. It is
+possible for a file to exist on only some branches and
+not on others, or to re-add another file with the same
+name later. @sc{cvs} will correctly create or not create
+the file, based on the @samp{-r} and @samp{-D} options
+specified to @code{checkout} or @code{update}.
+
address@hidden FIXME: This style seems to clash with how we
address@hidden document things in general.
address@hidden Remove (subcommand)
address@hidden Command {cvs remove} [options] files @dots{}
+
+Schedule file(s) to be removed from the repository
+(files which have not already been removed from the
+working directory are not processed). This command
+does not actually remove the file from the repository
+until you commit the removal. For a full list of
+options, see @ref{Invoking CVS}.
address@hidden deffn
+
+Here is an example of removing several files:
+
address@hidden
+$ cd test
+$ rm *.c
+$ cvs remove
+cvs remove: Removing .
+cvs remove: scheduling a.c for removal
+cvs remove: scheduling b.c for removal
+cvs remove: use 'cvs commit' to remove these files permanently
+$ cvs ci -m "Removed unneeded files"
+cvs commit: Examining .
+cvs commit: Committing .
address@hidden example
+
+As a convenience you can remove the file and @code{cvs
+remove} it in one step, by specifying the @samp{-f}
+option. For example, the above example could also be
+done like this:
+
address@hidden
+$ cd test
+$ cvs remove -f *.c
+cvs remove: scheduling a.c for removal
+cvs remove: scheduling b.c for removal
+cvs remove: use 'cvs commit' to remove these files permanently
+$ cvs ci -m "Removed unneeded files"
+cvs commit: Examining .
+cvs commit: Committing .
address@hidden example
+
+If you execute @code{remove} for a file, and then
+change your mind before you commit, you can undo the
address@hidden with an @code{add} command.
+
address@hidden FIXME: what if you change your mind after you commit
address@hidden it? (answer is also "cvs add" but we don't say that...).
address@hidden We need some index entries for thinks like "undoing
address@hidden removal" too.
+
address@hidden
+$ ls
+CVS ja.h oj.c
+$ rm oj.c
+$ cvs remove oj.c
+cvs remove: scheduling oj.c for removal
+cvs remove: use 'cvs commit' to remove this file permanently
+$ cvs add oj.c
+U oj.c
+cvs add: oj.c, version 1.1.1.1, resurrected
address@hidden example
+
+If you realize your mistake before you run the
address@hidden command you can use @code{update} to
+resurrect the file:
+
address@hidden
+$ rm oj.c
+$ cvs update oj.c
+cvs update: warning: oj.c was lost
+U oj.c
address@hidden example
+
+When you remove a file it is removed only on the branch
+which you are working on (@pxref{Branching and merging}). You can
+later merge the removals to another branch if you want
+(@pxref{Merging adds and removals}).
+
address@hidden Removing directories
address@hidden Removing directories
address@hidden Removing directories
address@hidden Directories, removing
+
+In concept removing directories is somewhat similar to
+removing files---you want the directory to not exist in
+your current working directories, but you also want to
+be able to retrieve old releases in which the directory
+existed.
+
+The way that you remove a directory is to remove all
+the files in it. You don't remove the directory
+itself; there is no way to do that.
+Instead you specify the @samp{-P} option to
address@hidden update} or @code{cvs checkout},
+which will cause @sc{cvs} to remove empty
+directories from working directories.
+(Note that @code{cvs export} always removes empty directories.)
+Probably the
+best way to do this is to always specify @samp{-P}; if
+you want an empty directory then put a dummy file (for
+example @file{.keepme}) in it to prevent @samp{-P} from
+removing it.
+
address@hidden I'd try to give a rationale for this, but I'm not
address@hidden sure there is a particularly convincing one. What
address@hidden we would _like_ is for CVS to do a better job of version
address@hidden controlling whether directories exist, to eliminate the
address@hidden need for -P and so that a file can be a directory in
address@hidden one revision and a regular file in another.
+Note that @samp{-P} is implied by the @samp{-r} or @samp{-D}
+options of @code{checkout}. This way
address@hidden will be able to correctly create the directory
+or not depending on whether the particular version you
+are checking out contains any files in that directory.
+
address@hidden
---------------------------------------------------------------------
address@hidden Moving files
address@hidden Moving and renaming files
address@hidden Moving files
address@hidden Renaming files
address@hidden Files, moving
+
+Moving files to a different directory or renaming them
+is not difficult, but some of the ways in which this
+works may be non-obvious. (Moving or renaming a
+directory is even harder. @xref{Moving directories}.).
+
+The examples below assume that the file @var{old} is renamed to
address@hidden
+
address@hidden
+* Outside:: The normal way to Rename
+* Inside:: A tricky, alternative way
+* Rename by copying:: Another tricky, alternative way
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Outside
address@hidden The Normal way to Rename
+
address@hidden More rename issues. Not sure whether these are
address@hidden worth documenting; I'm putting them here because
address@hidden it seems to be as good a place as any to try to
address@hidden set down the issues.
address@hidden * "cvs annotate" will annotate either the new
address@hidden file or the old file; it cannot annotate _each
address@hidden line_ based on whether it was last changed in the
address@hidden new or old file. Unlike "cvs log", where the
address@hidden consequences of having to select either the new
address@hidden or old name seem fairly benign, this may be a
address@hidden real advantage to having CVS know about renames
address@hidden other than as a deletion and an addition.
+
+The normal way to move a file is to copy @var{old} to
address@hidden, and then issue the normal @sc{cvs} commands
+to remove @var{old} from the repository, and add
address@hidden to it.
address@hidden The following sentence is not true: one must cd into
address@hidden the directory to run "cvs add".
address@hidden (Both @var{old} and @var{new} could
address@hidden contain relative paths, for example @file{foo/bar.c}).
+
address@hidden
+$ mv @var{old} @var{new}
+$ cvs remove @var{old}
+$ cvs add @var{new}
+$ cvs commit -m "Renamed @var{old} to @var{new}" @var{old} @var{new}
address@hidden example
+
+This is the simplest way to move a file, it is not
+error-prone, and it preserves the history of what was
+done. Note that to access the history of the file you
+must specify the old or the new name, depending on what
+portion of the history you are accessing. For example,
address@hidden log @var{old}} will give the log up until the
+time of the rename.
+
+When @var{new} is committed its revision numbers will
+start again, usually at 1.1, so if that bothers you,
+use the @samp{-r rev} option to commit. For more
+information see @ref{Assigning revisions}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Inside
address@hidden Moving the history file
+
+This method is more dangerous, since it involves moving
+files inside the repository. Read this entire section
+before trying it out!
+
address@hidden
+$ cd $CVSROOT/@var{dir}
+$ mv @var{old},v @var{new},v
address@hidden example
+
address@hidden
+Advantages:
+
address@hidden @bullet
address@hidden
+The log of changes is maintained intact.
+
address@hidden
+The revision numbers are not affected.
address@hidden itemize
+
address@hidden
+Disadvantages:
+
address@hidden @bullet
address@hidden
+Old releases cannot easily be fetched from the
+repository. (The file will show up as @var{new} even
+in revisions from the time before it was renamed).
+
address@hidden
+There is no log information of when the file was renamed.
+
address@hidden
+Nasty things might happen if someone accesses the history file
+while you are moving it. Make sure no one else runs any of the @sc{cvs}
+commands while you move it.
address@hidden itemize
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Rename by copying
address@hidden Copying the history file
+
+This way also involves direct modifications to the
+repository. It is safe, but not without drawbacks.
+
address@hidden
+# @r{Copy the @sc{rcs} file inside the repository}
+$ cd $CVSROOT/@var{dir}
+$ cp @var{old},v @var{new},v
+# @r{Remove the old file}
+$ cd ~/@var{dir}
+$ rm @var{old}
+$ cvs remove @var{old}
+$ cvs commit @var{old}
+# @r{Remove all tags from @var{new}}
+$ cvs update @var{new}
+$ cvs log @var{new} # @r{Remember the non-branch tag names}
+$ cvs tag -d @var{tag1} @var{new}
+$ cvs tag -d @var{tag2} @var{new}
address@hidden
address@hidden example
+
+By removing the tags you will be able to check out old
+revisions.
+
address@hidden
+Advantages:
+
address@hidden @bullet
address@hidden
address@hidden FIXME: Is this true about -D now that we have death
address@hidden support? See 5B.3 in the FAQ.
+Checking out old revisions works correctly, as long as
+you use @address@hidden and not @address@hidden
+to retrieve the revisions.
+
address@hidden
+The log of changes is maintained intact.
+
address@hidden
+The revision numbers are not affected.
address@hidden itemize
+
address@hidden
+Disadvantages:
+
address@hidden @bullet
address@hidden
+You cannot easily see the history of the file across the rename.
+
address@hidden itemize
+
address@hidden
---------------------------------------------------------------------
address@hidden Moving directories
address@hidden Moving and renaming directories
address@hidden Moving directories
address@hidden Renaming directories
address@hidden Directories, moving
+
+The normal way to rename or move a directory is to
+rename or move each file within it as described in
address@hidden Then check out with the @samp{-P}
+option, as described in @ref{Removing directories}.
+
+If you really want to hack the repository to rename or
+delete a directory in the repository, you can do it
+like this:
+
address@hidden
address@hidden
+Inform everyone who has a checked out copy of the directory that the
+directory will be renamed. They should commit all
+their changes, and remove their working copies,
+before you take the steps below.
+
address@hidden
+Rename the directory inside the repository.
+
address@hidden
+$ cd $CVSROOT/@var{parent-dir}
+$ mv @var{old-dir} @var{new-dir}
address@hidden example
+
address@hidden
+Fix the @sc{cvs} administrative files, if necessary (for
+instance if you renamed an entire module).
+
address@hidden
+Tell everyone that they can check out again and continue
+working.
+
address@hidden enumerate
+
+If someone had a working copy the @sc{cvs} commands will
+cease to work for him, until he removes the directory
+that disappeared inside the repository.
+
+It is almost always better to move the files in the
+directory instead of moving the directory. If you move the
+directory you are unlikely to be able to retrieve old
+releases correctly, since they probably depend on the
+name of the directories.
+
address@hidden
---------------------------------------------------------------------
address@hidden History browsing
address@hidden History browsing
address@hidden History browsing
address@hidden Traceability
address@hidden Isolation
+
+
address@hidden kind of lame, in a lot of ways the above text inside
address@hidden the @ignore motivates this chapter better
+Once you have used @sc{cvs} to store a version control
+history---what files have changed when, how, and by
+whom, there are a variety of mechanisms for looking
+through the history.
+
address@hidden FIXME: should also be talking about how you look at
address@hidden old revisions (e.g. "cvs update -p -r 1.2 foo.c").
address@hidden
+* log messages:: Log messages
+* history database:: The history database
+* user-defined logging:: User-defined logging
+* annotate:: What revision modified each line of a file?
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden log messages
address@hidden Log messages
+
address@hidden FIXME: @xref to place where we talk about how to
address@hidden specify message to commit.
+Whenever you commit a file you specify a log message.
+
address@hidden FIXME: bring the information here, and get rid of or
address@hidden greatly shrink the "log" node.
+To look through the log messages which have been
+specified for every revision which has been committed,
+use the @code{cvs log} command (@pxref{log}).
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden history database
address@hidden The history database
+
address@hidden FIXME: bring the information from the history file
address@hidden and history nodes here. Rewrite it to be motivated
address@hidden better (start out by clearly explaining what gets
address@hidden logged in history, for example).
+You can use the history file (@pxref{history file}) to
+log various @sc{cvs} actions. To retrieve the
+information from the history file, use the @code{cvs
+history} command (@pxref{history}).
+
+Note: you can control what is logged to this file by using the
address@hidden keyword in the @file{CVSROOT/config} file
+(@pxref{config}).
+
address@hidden
address@hidden The history database has many problems:
address@hidden * It is very unclear what field means what. This
address@hidden could be improved greatly by better documentation,
address@hidden but there are still non-orthogonalities (for
address@hidden example, tag does not record the "repository"
address@hidden field but most records do).
address@hidden * Confusion about files, directories, and modules.
address@hidden Some commands record one, some record others.
address@hidden * File removal is not logged. There is an 'R'
address@hidden record type documented, but CVS never uses it.
address@hidden * Tags are only logged for the "cvs rtag" command,
address@hidden not "cvs tag". The fix for this is not completely
address@hidden clear (see above about modules vs. files).
address@hidden * Are there other cases of operations that are not
address@hidden logged? One would hope for all changes to the
address@hidden repository to be logged somehow (particularly
address@hidden operations like tagging, "cvs admin -k", and other
address@hidden operations which do not record a history that one
address@hidden can get with "cvs log"). Operations on the working
address@hidden directory, like export, get, and release, are a
address@hidden second category also covered by the current "cvs
address@hidden history".
address@hidden * The history file does not record the options given
address@hidden to a command. The most serious manifestation of
address@hidden this is perhaps that it doesn't record whether a command
address@hidden was recursive. It is not clear to me whether one
address@hidden wants to log at a level very close to the command
address@hidden line, as a sort of way of logging each command
address@hidden (more or less), or whether one wants
address@hidden to log more at the level of what was changed (or
address@hidden something in between), but either way the current
address@hidden information has pretty big gaps.
address@hidden * Further details about a tag--like whether it is a
address@hidden branch tag or, if a non-branch tag, which branch it
address@hidden is on. One can find out this information about the
address@hidden tag as it exists _now_, but if the tag has been
address@hidden moved, one doesn't know what it was like at the time
address@hidden the history record was written.
address@hidden * Whether operating on a particular tag, date, or
address@hidden options was implicit (sticky) or explicit.
address@hidden
address@hidden Another item, only somewhat related to the above, is a
address@hidden way to control what is logged in the history file.
address@hidden This is probably the only good way to handle
address@hidden different people having different ideas about
address@hidden information/space tradeoffs.
address@hidden
address@hidden It isn't really clear that it makes sense to try to
address@hidden patch up the history file format as it exists now to
address@hidden include all that stuff. It might be better to
address@hidden design a whole new CVSROOT/nhistory file and "cvs
address@hidden nhistory" command, or some such, or in some other
address@hidden way trying to come up with a clean break from the
address@hidden past, which can address the above concerns. Another
address@hidden open question is how/whether this relates to
address@hidden taginfo/loginfo/etc.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden user-defined logging
address@hidden User-defined logging
+
address@hidden FIXME: should probably also mention the fact the -l
address@hidden global option can disable most of the mechanisms
address@hidden discussed here (why? What is the -l global option for?).
address@hidden
address@hidden FIXME: probably should centralize this information
address@hidden here, at least to some extent. Maybe by moving the
address@hidden loginfo, etc., nodes here and replacing
address@hidden the "user-defined logging" node with one node for
address@hidden each method.
+You can customize @sc{cvs} to log various kinds of
+actions, in whatever manner you choose. These
+mechanisms operate by executing a script at various
+times. The script might append a message to a file
+listing the information and the programmer who created
+it, or send mail to a group of developers, or, perhaps,
+post a message to a particular newsgroup. To log
+commits, use the @file{loginfo} file (@pxref{loginfo}).
address@hidden FIXME: What is difference between doing it in the
address@hidden modules file and using loginfo/taginfo? Why should
address@hidden user use one or the other?
+To log commits, checkouts, exports, and tags,
+respectively, you can also use the @samp{-i},
address@hidden, @samp{-e}, and @samp{-t} options in the
+modules file. For a more flexible way of giving
+notifications to various users, which requires less in
+the way of keeping centralized scripts up to date, use
+the @code{cvs watch add} command (@pxref{Getting
+Notified}); this command is useful even if you are not
+using @code{cvs watch on}.
+
address@hidden taginfo
address@hidden Exit status, of taginfo
+The @file{taginfo} file defines programs to execute
+when someone executes a @code{tag} or @code{rtag}
+command. The @file{taginfo} file has the standard form
+for administrative files (@pxref{Administrative
+files}), where each line is a regular expression
+followed by a command to execute. The arguments passed
+to the command are, in order, the @var{tagname},
address@hidden (@code{add} for @code{tag},
address@hidden for @code{tag -F}, and @code{del} for
address@hidden -d}), @var{repository}, and any remaining are
+pairs of @var{filename} @var{revision}. A non-zero
+exit of the filter program will cause the tag to be
+aborted.
+
+Here is an example of using taginfo to log tag and rtag
+commands. In the taginfo file put:
+
address@hidden
+ALL /usr/local/cvsroot/CVSROOT/loggit
address@hidden example
+
address@hidden
+Where @file{/usr/local/cvsroot/CVSROOT/loggit} contains the
+following script:
+
address@hidden
+#!/bin/sh
+echo "$@@" >>/home/kingdon/cvsroot/CVSROOT/taglog
address@hidden example
+
address@hidden annotate
address@hidden Annotate command
address@hidden annotate (subcommand)
+
address@hidden Command {cvs annotate} address@hidden address@hidden
rev}|@code{-D date}] files @dots{}
+
+For each file in @var{files}, print the head revision
+of the trunk, together with information on the last
+modification for each line. For example:
+
address@hidden
+$ cvs annotate ssfile
+Annotations for ssfile
+***************
+1.1 (mary 27-Mar-96): ssfile line 1
+1.2 (joe 28-Mar-96): ssfile line 2
address@hidden example
+
+The file @file{ssfile} currently contains two lines.
+The @code{ssfile line 1} line was checked in by
address@hidden on March 27. Then, on March 28, @code{joe}
+added a line @code{ssfile line 2}, without modifying
+the @code{ssfile line 1} line. This report doesn't
+tell you anything about lines which have been deleted
+or replaced; you need to use @code{cvs diff} for that
+(@pxref{diff}).
+
address@hidden deffn
+
+The options to @code{cvs annotate} are listed in
address@hidden CVS}, and can be used to select the files
+and revisions to annotate. The options are described
+in more detail there and in @ref{Common options}.
+
address@hidden FIXME: maybe an example using the options? Just
address@hidden what it means to select a revision might be worth a
address@hidden few words of explanation ("you want to see who
address@hidden changed this line *before* 1.4"...).
+
address@hidden
---------------------------------------------------------------------
address@hidden Binary files
address@hidden Handling binary files
address@hidden Binary files
+
+The most common use for @sc{cvs} is to store text
+files. With text files, @sc{cvs} can merge revisions,
+display the differences between revisions in a
+human-visible fashion, and other such operations.
+However, if you are willing to give up a few of these
+abilities, @sc{cvs} can store binary files. For
+example, one might store a web site in @sc{cvs}
+including both text files and binary images.
+
address@hidden
+* Binary why:: More details on issues with binary files
+* Binary howto:: How to store them
address@hidden menu
+
address@hidden Binary why
address@hidden The issues with binary files
+
+While the need to manage binary files may seem obvious
+if the files that you customarily work with are binary,
+putting them into version control does present some
+additional issues.
+
+One basic function of version control is to show the
+differences between two revisions. For example, if
+someone else checked in a new version of a file, you
+may wish to look at what they changed and determine
+whether their changes are good. For text files,
address@hidden provides this functionality via the @code{cvs
+diff} command. For binary files, it may be possible to
+extract the two revisions and then compare them with a
+tool external to @sc{cvs} (for example, word processing
+software often has such a feature). If there is no
+such tool, one must track changes via other mechanisms,
+such as urging people to write good log messages, and
+hoping that the changes they actually made were the
+changes that they intended to make.
+
+Another ability of a version control system is the
+ability to merge two revisions. For @sc{cvs} this
+happens in two contexts. The first is when users make
+changes in separate working directories
+(@pxref{Multiple developers}). The second is when one
+merges explicitly with the @samp{update -j} command
+(@pxref{Branching and merging}).
+
+In the case of text
+files, @sc{cvs} can merge changes made independently,
+and signal a conflict if the changes conflict. With
+binary files, the best that @sc{cvs} can do is present
+the two different copies of the file, and leave it to
+the user to resolve the conflict. The user may choose
+one copy or the other, or may run an external merge
+tool which knows about that particular file format, if
+one exists.
+Note that having the user merge relies primarily on the
+user to not accidentally omit some changes, and thus is
+potentially error prone.
+
+If this process is thought to be undesirable, the best
+choice may be to avoid merging. To avoid the merges
+that result from separate working directories, see the
+discussion of reserved checkouts (file locking) in
address@hidden developers}. To avoid the merges
+resulting from branches, restrict use of branches.
+
address@hidden Binary howto
address@hidden How to store binary files
+
+There are two issues with using @sc{cvs} to store
+binary files. The first is that @sc{cvs} by default
+converts line endings between the canonical form in
+which they are stored in the repository (linefeed
+only), and the form appropriate to the operating system
+in use on the client (for example, carriage return
+followed by line feed for Windows NT).
+
+The second is that a binary file might happen to
+contain data which looks like a keyword (@pxref{Keyword
+substitution}), so keyword expansion must be turned
+off.
+
address@hidden FIXME: the third is that one can't do merges with
address@hidden binary files. xref to Multiple Developers and the
address@hidden reserved checkout issues.
+
+The @samp{-kb} option available with some @sc{cvs}
+commands insures that neither line ending conversion
+nor keyword expansion will be done.
+
+Here is an example of how you can create a new file
+using the @samp{-kb} flag:
+
address@hidden
+$ echo 'address@hidden' > kotest
+$ cvs add -kb -m"A test file" kotest
+$ cvs ci -m"First checkin; contains a keyword" kotest
address@hidden example
+
+If a file accidentally gets added without @samp{-kb},
+one can use the @code{cvs admin} command to recover.
+For example:
+
address@hidden
+$ echo 'address@hidden' > kotest
+$ cvs add -m"A test file" kotest
+$ cvs ci -m"First checkin; contains a keyword" kotest
+$ cvs admin -kb kotest
+$ cvs update -A kotest
+# @r{For non-unix systems:}
+# @r{Copy in a good copy of the file from outside CVS}
+$ cvs commit -m "make it binary" kotest
address@hidden example
+
address@hidden Trying to describe this for both unix and non-unix
address@hidden in the same description is very confusing. Might
address@hidden want to split the two, or just ditch the unix "shortcut"
address@hidden (unixheads don't do much with binary files, anyway).
address@hidden This used to say "(Try the above example, and do a
address@hidden @code{cat kotest} after every command)". But that
address@hidden only really makes sense for the unix case.
+When you check in the file @file{kotest} the file is
+not preserved as a binary file, because you did not
+check it in as a binary file. The @code{cvs
+admin -kb} command sets the default keyword
+substitution method for this file, but it does not
+alter the working copy of the file that you have. If you need to
+cope with line endings (that is, you are using
address@hidden on a non-unix system), then you need to
+check in a new copy of the file, as shown by the
address@hidden commit} command above.
+On unix, the @code{cvs update -A} command suffices.
address@hidden FIXME: should also describe what the *other users*
address@hidden need to do, if they have checked out copies which
address@hidden have been corrupted by lack of -kb. I think maybe
address@hidden "cvs update -kb" or "cvs
address@hidden update -A" would suffice, although the user who
address@hidden reported this suggested removing the file, manually
address@hidden removing it from CVS/Entries, and then "cvs update"
+(Note that you can use @code{cvs log} to determine the default keyword
+substitution method for a file and @code{cvs status} to determine
+the keyword substitution method for a working copy.)
+
+However, in using @code{cvs admin -k} to change the
+keyword expansion, be aware that the keyword expansion
+mode is not version controlled. This means that, for
+example, that if you have a text file in old releases,
+and a binary file with the same name in new releases,
address@hidden provides no way to check out the file in text
+or binary mode depending on what version you are
+checking out. There is no good workaround for this
+problem.
+
+You can also set a default for whether @code{cvs add}
+and @code{cvs import} treat a file as binary based on
+its name; for example you could say that files who
+names end in @samp{.exe} are binary. @xref{Wrappers}.
+There is currently no way to have @sc{cvs} detect
+whether a file is binary based on its contents. The
+main difficulty with designing such a feature is that
+it is not clear how to distinguish between binary and
+non-binary files, and the rules to apply would vary
+considerably with the operating system.
address@hidden For example, it would be good on MS-DOS-family OSes
address@hidden for anything containing ^Z to be binary. Having
address@hidden characters with the 8th bit set imply binary is almost
address@hidden surely a bad idea in the context of ISO-8859-* and
address@hidden other such character sets. On VMS or the Mac, we
address@hidden could use the OS's file typing. This is a
address@hidden commonly-desired feature, and something of this sort
address@hidden may make sense. But there are a lot of pitfalls here.
address@hidden
address@hidden Another, probably better, way to tell is to read the
address@hidden file in text mode, write it to a temp file in text
address@hidden mode, and then do a binary mode compare of the two
address@hidden files. If they differ, it is a binary file. This
address@hidden might have problems on VMS (or some other system
address@hidden with several different text modes), but in general
address@hidden should be relatively portable. The only other
address@hidden downside I can think of is that it would be fairly
address@hidden slow, but that is perhaps a small price to pay for
address@hidden not having your files corrupted. Another issue is
address@hidden what happens if you import a text file with bare
address@hidden linefeeds on Windows. Such files will show up on
address@hidden Windows sometimes (I think some native windows
address@hidden programs even write them, on occasion). Perhaps it
address@hidden is reasonable to treat such files as binary; after
address@hidden all it is something of a presumption to assume that
address@hidden the user would want the linefeeds converted to CRLF.
+
address@hidden
---------------------------------------------------------------------
address@hidden Multiple developers
address@hidden Multiple developers
address@hidden Multiple developers
address@hidden Team of developers
address@hidden File locking
address@hidden Locking files
address@hidden Working copy
address@hidden Reserved checkouts
address@hidden Unreserved checkouts
address@hidden RCS-style locking
+
+When more than one person works on a software project
+things often get complicated. Often, two people try to
+edit the same file simultaneously. One solution, known
+as @dfn{file locking} or @dfn{reserved checkouts}, is
+to allow only one person to edit each file at a time.
+This is the only solution with some version control
+systems, including @sc{rcs} and @sc{sccs}. Currently
+the usual way to get reserved checkouts with @sc{cvs}
+is the @code{cvs admin -l} command (@pxref{admin
+options}). This is not as nicely integrated into
address@hidden as the watch features, described below, but it
+seems that most people with a need for reserved
+checkouts find it adequate.
address@hidden Or "find it better than worrying about implementing
address@hidden nicely integrated reserved checkouts" or ...?
+It also may be possible to use the watches
+features described below, together with suitable
+procedures (not enforced by software), to avoid having
+two people edit at the same time.
+
address@hidden Our unreserved checkout model might not
address@hidden be quite the same as others. For example, I
address@hidden think that some systems will tend to create a branch
address@hidden in the case where CVS prints "up-to-date check failed".
address@hidden It isn't clear to me whether we should try to
address@hidden explore these subtleties; it could easily just
address@hidden confuse people.
+The default model with @sc{cvs} is known as
address@hidden checkouts}. In this model, developers
+can edit their own @dfn{working copy} of a file
+simultaneously. The first person that commits his
+changes has no automatic way of knowing that another
+has started to edit it. Others will get an error
+message when they try to commit the file. They must
+then use @sc{cvs} commands to bring their working copy
+up to date with the repository revision. This process
+is almost automatic.
+
address@hidden FIXME? should probably use the word "watch" here, to
address@hidden tie this into the text below and above.
address@hidden also supports mechanisms which facilitate
+various kinds of communication, without actually
+enforcing rules like reserved checkouts do.
+
+The rest of this chapter describes how these various
+models work, and some of the issues involved in
+choosing between them.
+
+
address@hidden
+* File status:: A file can be in several states
+* Updating a file:: Bringing a file up-to-date
+* Conflicts example:: An informative example
+* Informing others:: To cooperate you must inform
+* Concurrency:: Simultaneous repository access
+* Watches:: Mechanisms to track who is editing files
+* Choosing a model:: Reserved or unreserved checkouts?
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden File status
address@hidden File status
address@hidden File status
address@hidden Status of a file
+
address@hidden Shouldn't this start with an example or something,
address@hidden introducing the unreserved checkout model? Before we
address@hidden dive into listing states?
+Based on what operations you have performed on a
+checked out file, and what operations others have
+performed to that file in the repository, one can
+classify a file in a number of states. The states, as
+reported by the @code{status} command, are:
+
address@hidden The order of items is chosen to group logically
address@hidden similar outputs together.
address@hidden People who want alphabetical can use the index...
address@hidden @asis
address@hidden Up-to-date
address@hidden Up-to-date
+The file is identical with the latest revision in the
+repository for the branch in use.
address@hidden FIXME: should we clarify "in use"? The answer is
address@hidden sticky tags, and trying to distinguish branch sticky
address@hidden tags from non-branch sticky tags seems rather awkward
address@hidden here.
address@hidden FIXME: What happens with non-branch sticky tags? Is
address@hidden a stuck file "Up-to-date" or "Needs checkout" or what?
+
address@hidden Locally Modified
address@hidden Locally Modified
+You have edited the file, and not yet committed your changes.
+
address@hidden Locally Added
address@hidden Locally Added
+You have added the file with @code{add}, and not yet
+committed your changes.
address@hidden There are many cases involving the file being
address@hidden added/removed/modified in the working directory, and
address@hidden added/removed/modified in the repository, which we
address@hidden don't try to describe here. I'm not sure that "cvs
address@hidden status" produces a non-confusing output in most of
address@hidden those cases.
+
address@hidden Locally Removed
address@hidden Locally Removed
+You have removed the file with @code{remove}, and not yet
+committed your changes.
+
address@hidden Needs Checkout
address@hidden Needs Checkout
+Someone else has committed a newer revision to the
+repository. The name is slightly misleading; you will
+ordinarily use @code{update} rather than
address@hidden to get that newer revision.
+
address@hidden Needs Patch
address@hidden Needs Patch
address@hidden See also newb-123j0 in sanity.sh (although that case
address@hidden should probably be changed rather than documented).
+Like Needs Checkout, but the @sc{cvs} server will send
+a patch rather than the entire file. Sending a patch or
+sending an entire file accomplishes the same thing.
+
address@hidden Needs Merge
address@hidden Needs Merge
+Someone else has committed a newer revision to the repository, and you
+have also made modifications to the file.
+
address@hidden Unresolved Conflict
address@hidden Unresolved Conflict
address@hidden FIXCVS - This file status needs to be changed to some more
informative
address@hidden text that distinguishes it more clearly from each of the Locally
Added,
address@hidden File had conflicts on merge, and Unknown status types, but an
exact and
address@hidden succinct wording escapes me at the moment.
+A file with the same name as this new file has been added to the repository
+from a second workspace. This file will need to be moved out of the way
+to allow an @code{update} to complete.
+
address@hidden File had conflicts on merge
address@hidden File had conflicts on merge
address@hidden is it worth saying that this message was "Unresolved
address@hidden Conflict" in CVS 1.9 and earlier? I'm inclined to
address@hidden think that is unnecessarily confusing to new users.
+This is like Locally Modified, except that a previous
address@hidden command gave a conflict. If you have not
+already done so, you need to
+resolve the conflict as described in @ref{Conflicts example}.
+
address@hidden Unknown
address@hidden Unknown
address@hidden doesn't know anything about this file. For
+example, you have created a new file and have not run
address@hidden
address@hidden
address@hidden "Entry Invalid" and "Classify Error" are also in the
address@hidden status.c. The latter definitely indicates a CVS bug
address@hidden (should it be worded more like "internal error" so
address@hidden people submit bug reports if they see it?). The former
address@hidden I'm not as sure; I haven't tracked down whether/when it
address@hidden appears in "cvs status" output.
+
address@hidden table
+
+To help clarify the file status, @code{status} also
+reports the @code{Working revision} which is the
+revision that the file in the working directory derives
+from, and the @code{Repository revision} which is the
+latest revision in the repository for the branch in
+use.
address@hidden FIXME: should we clarify "in use"? The answer is
address@hidden sticky tags, and trying to distinguish branch sticky
address@hidden tags from non-branch sticky tags seems rather awkward
address@hidden here.
address@hidden FIXME: What happens with non-branch sticky tags?
address@hidden What is the Repository Revision there? See the
address@hidden comment at vn_rcs in cvs.h, which is kind of
address@hidden confused--we really need to document better what this
address@hidden field contains.
address@hidden Q: Should we document "New file!" and other such
address@hidden outputs or are they self-explanatory?
address@hidden FIXME: what about the date to the right of "Working
address@hidden revision"? It doesn't appear with client/server and
address@hidden seems unnecessary (redundant with "ls -l") so
address@hidden perhaps it should be removed for non-client/server too?
address@hidden FIXME: Need some examples.
address@hidden FIXME: Working revision can also be something like
address@hidden "-1.3" for a locally removed file. Not at all
address@hidden self-explanatory (and it is possible that CVS should
address@hidden be changed rather than documenting this).
+
address@hidden Would be nice to have an @example showing output
address@hidden from cvs status, with comments showing the xref
address@hidden where each part of the output is described. This
address@hidden might fit in nicely if it is desirable to split this
address@hidden node in two; one to introduce "cvs status" and one
address@hidden to list each of the states.
+The options to @code{status} are listed in
address@hidden CVS}. For information on its @code{Sticky tag}
+and @code{Sticky date} output, see @ref{Sticky tags}.
+For information on its @code{Sticky options} output,
+see the @samp{-k} option in @ref{update options}.
+
+You can think of the @code{status} and @code{update}
+commands as somewhat complementary. You use
address@hidden to bring your files up to date, and you
+can use @code{status} to give you some idea of what an
address@hidden would do (of course, the state of the
+repository might change before you actually run
address@hidden). In fact, if you want a command to
+display file status in a more brief format than is
+displayed by the @code{status} command, you can invoke
+
address@hidden update, to display file status
address@hidden
+$ cvs -n -q update
address@hidden example
+
+The @samp{-n} option means to not actually do the
+update, but merely to display statuses; the @samp{-q}
+option avoids printing the name of each directory. For
+more information on the @code{update} command, and
+these options, see @ref{Invoking CVS}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Updating a file
address@hidden Bringing a file up to date
address@hidden Bringing a file up to date
address@hidden Updating a file
address@hidden Merging a file
address@hidden Update, introduction
+
+When you want to update or merge a file, use the @code{update}
+command. For files that are not up to date this is roughly equivalent
+to a @code{checkout} command: the newest revision of the file is
+extracted from the repository and put in your working directory.
+
+Your modifications to a file are never lost when you
+use @code{update}. If no newer revision exists,
+running @code{update} has no effect. If you have
+edited the file, and a newer revision is available,
address@hidden will merge all changes into your working copy.
+
+For instance, imagine that you checked out revision 1.4 and started
+editing it. In the meantime someone else committed revision 1.5, and
+shortly after that revision 1.6. If you run @code{update} on the file
+now, @sc{cvs} will incorporate all changes between revision 1.4 and 1.6 into
+your file.
+
address@hidden Overlap
+If any of the changes between 1.4 and 1.6 were made too
+close to any of the changes you have made, an
address@hidden occurs. In such cases a warning is
+printed, and the resulting file includes both
+versions of the lines that overlap, delimited by
+special markers.
address@hidden, for a complete description of the
address@hidden command.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Conflicts example
address@hidden Conflicts example
address@hidden Merge, an example
address@hidden Example of merge
address@hidden driver.c (merge example)
+
+Suppose revision 1.4 of @file{driver.c} contains this:
+
address@hidden
+#include <stdio.h>
+
+void main()
address@hidden
+ parse();
+ if (nerr == 0)
+ gencode();
+ else
+ fprintf(stderr, "No code generated.\n");
+ exit(nerr == 0 ? 0 : 1);
address@hidden
address@hidden example
+
address@hidden
+Revision 1.6 of @file{driver.c} contains this:
+
address@hidden
+#include <stdio.h>
+
+int main(int argc,
+ char **argv)
address@hidden
+ parse();
+ if (argc != 1)
+ @{
+ fprintf(stderr, "tc: No args expected.\n");
+ exit(1);
+ @}
+ if (nerr == 0)
+ gencode();
+ else
+ fprintf(stderr, "No code generated.\n");
+ exit(!!nerr);
address@hidden
address@hidden example
+
address@hidden
+Your working copy of @file{driver.c}, based on revision
+1.4, contains this before you run @samp{cvs update}:
address@hidden -- Really include "cvs"?
+
address@hidden
+#include <stdlib.h>
+#include <stdio.h>
+
+void main()
address@hidden
+ init_scanner();
+ parse();
+ if (nerr == 0)
+ gencode();
+ else
+ fprintf(stderr, "No code generated.\n");
+ exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
address@hidden
address@hidden example
+
address@hidden
+You run @samp{cvs update}:
address@hidden -- Really include "cvs"?
+
address@hidden
+$ cvs update driver.c
+RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v
+retrieving revision 1.4
+retrieving revision 1.6
+Merging differences between 1.4 and 1.6 into driver.c
+rcsmerge warning: overlaps during merge
+cvs update: conflicts found in driver.c
+C driver.c
address@hidden example
+
address@hidden
address@hidden Conflicts (merge example)
address@hidden tells you that there were some conflicts.
+Your original working file is saved unmodified in
address@hidden The new version of
address@hidden contains this:
+
address@hidden
+#include <stdlib.h>
+#include <stdio.h>
+
+int main(int argc,
+ char **argv)
address@hidden
+ init_scanner();
+ parse();
+ if (argc != 1)
+ @{
+ fprintf(stderr, "tc: No args expected.\n");
+ exit(1);
+ @}
+ if (nerr == 0)
+ gencode();
+ else
+ fprintf(stderr, "No code generated.\n");
address@hidden<<<<<<< driver.c
+ exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
address@hidden
+ exit(!!nerr);
address@hidden>>>>>>> 1.6
address@hidden
address@hidden example
+
address@hidden
address@hidden Markers, conflict
address@hidden Conflict markers
address@hidden <<<<<<<
address@hidden >>>>>>>
address@hidden =======
+
+Note how all non-overlapping modifications are incorporated in your working
+copy, and that the overlapping section is clearly marked with
address@hidden<<<<<<<}, @samp{=======} and @samp{>>>>>>>}.
+
address@hidden Resolving a conflict
address@hidden Conflict resolution
+You resolve the conflict by editing the file, removing the markers and
+the erroneous line. Suppose you end up with this file:
address@hidden -- Add xref to the pcl-cvs manual when it talks
address@hidden -- about this.
address@hidden
+#include <stdlib.h>
+#include <stdio.h>
+
+int main(int argc,
+ char **argv)
address@hidden
+ init_scanner();
+ parse();
+ if (argc != 1)
+ @{
+ fprintf(stderr, "tc: No args expected.\n");
+ exit(1);
+ @}
+ if (nerr == 0)
+ gencode();
+ else
+ fprintf(stderr, "No code generated.\n");
+ exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
address@hidden
address@hidden example
+
address@hidden
+You can now go ahead and commit this as revision 1.7.
+
address@hidden
+$ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c
+Checking in driver.c;
+/usr/local/cvsroot/yoyodyne/tc/driver.c,v <-- driver.c
+new revision: 1.7; previous revision: 1.6
+done
address@hidden example
+
+For your protection, @sc{cvs} will refuse to check in a
+file if a conflict occurred and you have not resolved
+the conflict. Currently to resolve a conflict, you
+must change the timestamp on the file. In previous
+versions of @sc{cvs}, you also needed to
+insure that the file contains no conflict markers.
+Because
+your file may legitimately contain conflict markers (that
+is, occurrences of @samp{>>>>>>> } at the start of a
+line that don't mark a conflict), the current
+version of @sc{cvs} will print a warning and proceed to
+check in the file.
address@hidden The old behavior was really icky; the only way out
address@hidden was to start hacking on
address@hidden the @code{CVS/Entries} file or other such workarounds.
address@hidden
address@hidden If the timestamp thing isn't considered nice enough,
address@hidden maybe there should be a "cvs resolved" command
address@hidden which clears the conflict indication. For a nice user
address@hidden interface, this should be invoked by an interactive
address@hidden merge tool like emerge rather than by the user
address@hidden directly--such a tool can verify that the user has
address@hidden really dealt with each conflict.
+
address@hidden emerge
+If you use release 1.04 or later of pcl-cvs (a @sc{gnu}
+Emacs front-end for @sc{cvs}) you can use an Emacs
+package called emerge to help you resolve conflicts.
+See the documentation for pcl-cvs.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Informing others
address@hidden Informing others about commits
address@hidden Informing others
address@hidden Spreading information
address@hidden Mail, automatic mail on commit
+
+It is often useful to inform others when you commit a
+new revision of a file. The @samp{-i} option of the
address@hidden file, or the @file{loginfo} file, can be
+used to automate this process. @xref{modules}.
address@hidden You can use these features of @sc{cvs}
+to, for instance, instruct @sc{cvs} to mail a
+message to all developers, or post a message to a local
+newsgroup.
address@hidden -- More text would be nice here.
+
address@hidden Concurrency
address@hidden Several developers simultaneously attempting to run CVS
+
address@hidden Locks, cvs, introduction
address@hidden For a discussion of *why* CVS creates locks, see
address@hidden the comment at the start of src/lock.c
+If several developers try to run @sc{cvs} at the same
+time, one may get the following message:
+
address@hidden
+[11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo
address@hidden example
+
address@hidden #cvs.rfl, removing
address@hidden #cvs.wfl, removing
address@hidden #cvs.lock, removing
address@hidden will try again every 30 seconds, and either
+continue with the operation or print the message again,
+if it still needs to wait. If a lock seems to stick
+around for an undue amount of time, find the person
+holding the lock and ask them about the cvs command
+they are running. If they aren't running a cvs
+command, look in the repository directory mentioned in
+the message and remove files which they own whose names
+start with @file{#cvs.rfl},
address@hidden, or @file{#cvs.lock}.
+
+Note that these locks are to protect @sc{cvs}'s
+internal data structures and have no relationship to
+the word @dfn{lock} in the sense used by
address@hidden refers to reserved checkouts
+(@pxref{Multiple developers}).
+
+Any number of people can be reading from a given
+repository at a time; only when someone is writing do
+the locks prevent other people from reading or writing.
+
address@hidden Atomic transactions, lack of
address@hidden Transactions, atomic, lack of
address@hidden the following talks about what one might call commit/update
address@hidden atomicity.
address@hidden Probably also should say something about
address@hidden commit/commit atomicity, that is, "An update will
address@hidden not get partial versions of more than one commit".
address@hidden CVS currently has this property and I guess we can
address@hidden make it a documented feature.
address@hidden For example one person commits
address@hidden a/one.c and b/four.c and another commits a/two.c and
address@hidden b/three.c. Then an update cannot get the new a/one.c
address@hidden and a/two.c and the old b/four.c and b/three.c.
+One might hope for the following property:
+
address@hidden
+If someone commits some changes in one cvs command,
+then an update by someone else will either get all the
+changes, or none of them.
address@hidden quotation
+
address@hidden
+but @sc{cvs} does @emph{not} have this property. For
+example, given the files
+
address@hidden
+a/one.c
+a/two.c
+b/three.c
+b/four.c
address@hidden example
+
address@hidden
+if someone runs
+
address@hidden
+cvs ci a/two.c b/three.c
address@hidden example
+
address@hidden
+and someone else runs @code{cvs update} at the same
+time, the person running @code{update} might get only
+the change to @file{b/three.c} and not the change to
address@hidden/two.c}.
+
address@hidden Watches
address@hidden Mechanisms to track who is editing files
address@hidden Watches
+
+For many groups, use of @sc{cvs} in its default mode is
+perfectly satisfactory. Users may sometimes go to
+check in a modification only to find that another
+modification has intervened, but they deal with it and
+proceed with their check in. Other groups prefer to be
+able to know who is editing what files, so that if two
+people try to edit the same file they can choose to
+talk about who is doing what when rather than be
+surprised at check in time. The features in this
+section allow such coordination, while retaining the
+ability of two developers to edit the same file at the
+same time.
+
address@hidden Some people might ask why CVS does not enforce the
address@hidden rule on chmod, by requiring a cvs edit before a cvs
address@hidden commit. The main reason is that it could always be
address@hidden circumvented--one could edit the file, and
address@hidden then when ready to check it in, do the cvs edit and put
address@hidden in the new contents and do the cvs commit. One
address@hidden implementation note: if we _do_ want to have cvs commit
address@hidden require a cvs edit, we should store the state on
address@hidden whether the cvs edit has occurred in the working
address@hidden directory, rather than having the server try to keep
address@hidden track of what working directories exist.
address@hidden FIXME: should the above discussion be part of the
address@hidden manual proper, somewhere, not just in a comment?
+For maximum benefit developers should use @code{cvs
+edit} (not @code{chmod}) to make files read-write to
+edit them, and @code{cvs release} (not @code{rm}) to
+discard a working directory which is no longer in use,
+but @sc{cvs} is not able to enforce this behavior.
+
address@hidden I'm a little dissatisfied with this presentation,
address@hidden because "watch on"/"edit"/"editors" are one set of
address@hidden functionality, and "watch add"/"watchers" is another
address@hidden which is somewhat orthogonal even though they interact in
address@hidden various ways. But I think it might be
address@hidden confusing to describe them separately (e.g. "watch
address@hidden add" with loginfo). I don't know.
+
address@hidden
+* Setting a watch:: Telling CVS to watch certain files
+* Getting Notified:: Telling CVS to notify you
+* Editing files:: How to edit a file which is being watched
+* Watch information:: Information about who is watching and editing
+* Watches Compatibility:: Watches interact poorly with CVS 1.6 or earlier
address@hidden menu
+
address@hidden Setting a watch
address@hidden Telling CVS to watch certain files
+
+To enable the watch features, you first specify that
+certain files are to be watched.
+
address@hidden watch on (subcommand)
address@hidden Command {cvs watch on} address@hidden address@hidden@dots{}
+
address@hidden Read-only files, and watches
+Specify that developers should run @code{cvs edit}
+before editing @var{files}. @sc{cvs} will create working
+copies of @var{files} read-only, to remind developers
+to run the @code{cvs edit} command before working on
+them.
+
+If @var{files} includes the name of a directory, @sc{cvs}
+arranges to watch all files added to the corresponding
+repository directory, and sets a default for files
+added in the future; this allows the user to set
+notification policies on a per-directory basis. The
+contents of the directory are processed recursively,
+unless the @code{-l} option is given.
+The @code{-R} option can be used to force recursion if the @code{-l}
+option is set in @file{~/.cvsrc} (@pxref{~/.cvsrc}).
+
+If @var{files} is omitted, it defaults to the current directory.
+
address@hidden watch off (subcommand)
address@hidden deffn
+
address@hidden Command {cvs watch off} address@hidden address@hidden@dots{}
+
+Do not create @var{files} read-only on checkout; thus,
+developers will not be reminded to use @code{cvs edit}
+and @code{cvs unedit}.
+
+The @var{files} and options are processed as for @code{cvs
+watch on}.
+
address@hidden deffn
+
address@hidden Getting Notified
address@hidden Telling CVS to notify you
+
+You can tell @sc{cvs} that you want to receive
+notifications about various actions taken on a file.
+You can do this without using @code{cvs watch on} for
+the file, but generally you will want to use @code{cvs
+watch on}, to remind developers to use the @code{cvs edit}
+command.
+
address@hidden watch add (subcommand)
address@hidden Command {cvs watch add} address@hidden address@hidden
@address@hidden address@hidden@dots{}
+
+Add the current user to the list of people to receive notification of
+work done on @var{files}.
+
+The @code{-a} option specifies what kinds of events @sc{cvs} should notify
+the user about. @var{action} is one of the following:
+
address@hidden @code
+
address@hidden edit
+Another user has applied the @code{cvs edit} command (described
+below) to a watched file.
+
address@hidden commit
+Another user has committed changes to one of the named @var{files}.
+
address@hidden unedit
+Another user has abandoned editing a file (other than by committing changes).
+They can do this in several ways, by:
+
address@hidden @bullet
+
address@hidden
+applying the @code{cvs unedit} command (described below) to the file
+
address@hidden
+applying the @code{cvs release} command (@pxref{release}) to the file's parent
directory
+(or recursively to a directory more than one level up)
+
address@hidden
+deleting the file and allowing @code{cvs update} to recreate it
+
address@hidden itemize
+
address@hidden all
+All of the above.
+
address@hidden none
+None of the above. (This is useful with @code{cvs edit},
+described below.)
+
address@hidden table
+
+The @code{-a} option may appear more than once, or not at all. If
+omitted, the action defaults to @code{all}.
+
+The @var{files} and options are processed as for
address@hidden watch on}.
+
address@hidden deffn
+
+
address@hidden watch remove (subcommand)
address@hidden Command {cvs watch remove} address@hidden address@hidden
@address@hidden address@hidden@dots{}
+
+Remove a notification request established using @code{cvs watch add};
+the arguments are the same. If the @code{-a} option is present, only
+watches for the specified actions are removed.
+
address@hidden deffn
+
address@hidden notify (admin file)
+When the conditions exist for notification, @sc{cvs}
+calls the @file{notify} administrative file. Edit
address@hidden as one edits the other administrative
+files (@pxref{Intro administrative files}). This
+file follows the usual conventions for administrative
+files (@pxref{syntax}), where each line is a regular
+expression followed by a command to execute. The
+command should contain a single occurrence of @samp{%s}
+which will be replaced by the user to notify; the rest
+of the information regarding the notification will be
+supplied to the command on standard input. The
+standard thing to put in the @code{notify} file is the
+single line:
+
address@hidden
+ALL mail %s -s "CVS notification"
address@hidden example
+
address@hidden
+This causes users to be notified by electronic mail.
address@hidden FIXME: should it be this hard to set up this
address@hidden behavior (and the result when one fails to do so,
address@hidden silent failure to notify, so non-obvious)? Should
address@hidden CVS give a warning if no line in notify matches (and
address@hidden document the use of "DEFAULT :" for the case where
address@hidden skipping the notification is indeed desired)?
+
address@hidden users (admin file)
+Note that if you set this up in the straightforward
+way, users receive notifications on the server machine.
+One could of course write a @file{notify} script which
+directed notifications elsewhere, but to make this
+easy, @sc{cvs} allows you to associate a notification
+address for each user. To do so create a file
address@hidden in @file{CVSROOT} with a line for each
+user in the format @var{user}:@var{value}. Then
+instead of passing the name of the user to be notified
+to @file{notify}, @sc{cvs} will pass the @var{value}
+(normally an email address on some other machine).
+
address@hidden does not notify you for your own changes.
+Currently this check is done based on whether the user
+name of the person taking the action which triggers
+notification matches the user name of the person
+getting notification. In fact, in general, the watches
+features only track one edit by each user. It probably
+would be more useful if watches tracked each working
+directory separately, so this behavior might be worth
+changing.
address@hidden "behavior might be worth changing" is an effort to
address@hidden point to future directions while also not promising
address@hidden that "they" (as in "why don't they fix CVS to....")
address@hidden will do this.
address@hidden one implementation issue is identifying whether a
address@hidden working directory is same or different. Comparing
address@hidden pathnames/hostnames is hopeless, but having the server
address@hidden supply a serial number which the client stores in the
address@hidden CVS directory as a magic cookie should work.
+
address@hidden Editing files
address@hidden How to edit a file which is being watched
+
address@hidden Checkout, as term for getting ready to edit
+Since a file which is being watched is checked out
+read-only, you cannot simply edit it. To make it
+read-write, and inform others that you are planning to
+edit it, use the @code{cvs edit} command. Some systems
+call this a @dfn{checkout}, but @sc{cvs} uses that term
+for obtaining a copy of the sources (@pxref{Getting the
+source}), an operation which those systems call a
address@hidden or a @dfn{fetch}.
address@hidden Issue to think about: should we transition CVS
address@hidden towards the "get" terminology? "cvs get" is already a
address@hidden synonym for "cvs checkout" and that section of the
address@hidden manual refers to "Getting the source". If this is
address@hidden done, needs to be done gingerly (for example, we should
address@hidden still accept "checkout" in .cvsrc files indefinitely
address@hidden even if the CVS's messages are changed from "cvs checkout: "
address@hidden to "cvs get: ").
address@hidden There is a concern about whether "get" is not as
address@hidden good for novices because it is a more general term
address@hidden than "checkout" (and thus arguably harder to assign
address@hidden a technical meaning for).
+
address@hidden edit (subcommand)
address@hidden Command {cvs edit} address@hidden address@hidden @address@hidden
address@hidden@dots{}
+
+Prepare to edit the working files @var{files}. @sc{cvs} makes the
address@hidden read-write, and notifies users who have requested
address@hidden notification for any of @var{files}.
+
+The @code{cvs edit} command accepts the same options as the
address@hidden watch add} command, and establishes a temporary watch for the
+user on @var{files}; @sc{cvs} will remove the watch when @var{files} are
address@hidden or @code{commit}ted. If the user does not wish to
+receive notifications, she should specify @code{-a none}.
+
+The @var{files} and the options are processed as for the @code{cvs
+watch} commands.
+
+
address@hidden deffn
+
+Normally when you are done with a set of changes, you
+use the @code{cvs commit} command, which checks in your
+changes and returns the watched files to their usual
+read-only state. But if you instead decide to abandon
+your changes, or not to make any changes, you can use
+the @code{cvs unedit} command.
+
address@hidden unedit (subcommand)
address@hidden Abandoning work
address@hidden Reverting to repository version
address@hidden Command {cvs unedit} address@hidden address@hidden@dots{}
+
+Abandon work on the working files @var{files}, and revert them to the
+repository versions on which they are based. @sc{cvs} makes those
address@hidden read-only for which users have requested notification using
address@hidden watch on}. @sc{cvs} notifies users who have requested
@code{unedit}
+notification for any of @var{files}.
+
+The @var{files} and options are processed as for the
address@hidden watch} commands.
+
+If watches are not in use, the @code{unedit} command
+probably does not work, and the way to revert to the
+repository version is with the command @code{cvs update -C file}
+(@pxref{update}).
+The meaning is
+not precisely the same; the latter may also
+bring in some changes which have been made in the
+repository since the last time you updated.
address@hidden It would be a useful enhancement to CVS to make
address@hidden unedit work in the non-watch case as well.
address@hidden deffn
+
+When using client/server @sc{cvs}, you can use the
address@hidden edit} and @code{cvs unedit} commands even if
address@hidden is unable to successfully communicate with the
+server; the notifications will be sent upon the next
+successful @sc{cvs} command.
+
address@hidden Watch information
address@hidden Information about who is watching and editing
+
address@hidden watchers (subcommand)
address@hidden Command {cvs watchers} address@hidden address@hidden@dots{}
+
+List the users currently watching changes to @var{files}. The report
+includes the files being watched, and the mail address of each watcher.
+
+The @var{files} and options are processed as for the
address@hidden watch} commands.
+
address@hidden deffn
+
+
address@hidden editors (subcommand)
address@hidden Command {cvs editors} address@hidden address@hidden@dots{}
+
+List the users currently working on @var{files}. The report
+includes the mail address of each user, the time when the user began
+working with the file, and the host and path of the working directory
+containing the file.
+
+The @var{files} and options are processed as for the
address@hidden watch} commands.
+
address@hidden deffn
+
address@hidden Watches Compatibility
address@hidden Using watches with old versions of CVS
+
address@hidden CVS 1.6, and watches
+If you use the watch features on a repository, it
+creates @file{CVS} directories in the repository and
+stores the information about watches in that directory.
+If you attempt to use @sc{cvs} 1.6 or earlier with the
+repository, you get an error message such as the
+following (all on one line):
+
address@hidden
+cvs update: cannot open CVS/Entries for reading:
+No such file or directory
address@hidden example
+
address@hidden
+and your operation will likely be aborted. To use the
+watch features, you must upgrade all copies of @sc{cvs}
+which use that repository in local or server mode. If
+you cannot upgrade, use the @code{watch off} and
address@hidden remove} commands to remove all watches, and
+that will restore the repository to a state which
address@hidden 1.6 can cope with.
+
address@hidden Choosing a model
address@hidden Choosing between reserved or unreserved checkouts
address@hidden Choosing, reserved or unreserved checkouts
+
+Reserved and unreserved checkouts each have pros and
+cons. Let it be said that a lot of this is a matter of
+opinion or what works given different groups' working
+styles, but here is a brief description of some of the
+issues. There are many ways to organize a team of
+developers. @sc{cvs} does not try to enforce a certain
+organization. It is a tool that can be used in several
+ways.
+
+Reserved checkouts can be very counter-productive. If
+two persons want to edit different parts of a file,
+there may be no reason to prevent either of them from
+doing so. Also, it is common for someone to take out a
+lock on a file, because they are planning to edit it,
+but then forget to release the lock.
+
address@hidden "many groups"? specifics? cites to papers on this?
address@hidden some way to weasel-word it a bit more so we don't
address@hidden need facts :-)?
+People, especially people who are familiar with
+reserved checkouts, often wonder how often conflicts
+occur if unreserved checkouts are used, and how
+difficult they are to resolve. The experience with
+many groups is that they occur rarely and usually are
+relatively straightforward to resolve.
+
+The rarity of serious conflicts may be surprising, until one realizes
+that they occur only when two developers disagree on the proper design
+for a given section of code; such a disagreement suggests that the
+team has not been communicating properly in the first place. In order
+to collaborate under @emph{any} source management regimen, developers
+must agree on the general design of the system; given this agreement,
+overlapping changes are usually straightforward to merge.
+
+In some cases unreserved checkouts are clearly
+inappropriate. If no merge tool exists for the kind of
+file you are managing (for example word processor files
+or files edited by Computer Aided Design programs), and
+it is not desirable to change to a program which uses a
+mergeable data format, then resolving conflicts is
+going to be unpleasant enough that you generally will
+be better off to simply avoid the conflicts instead, by
+using reserved checkouts.
+
+The watches features described above in @ref{Watches}
+can be considered to be an intermediate model between
+reserved checkouts and unreserved checkouts. When you
+go to edit a file, it is possible to find out who else
+is editing it. And rather than having the system
+simply forbid both people editing the file, it can tell
+you what the situation is and let you figure out
+whether it is a problem in that particular case or not.
+Therefore, for some groups it can be considered the
+best of both the reserved checkout and unreserved
+checkout worlds.
+
address@hidden
---------------------------------------------------------------------
address@hidden Revision management
address@hidden Revision management
address@hidden Revision management
+
address@hidden -- This chapter could be expanded a lot.
address@hidden -- Experiences are very welcome!
+
+If you have read this far, you probably have a pretty
+good grasp on what @sc{cvs} can do for you. This
+chapter talks a little about things that you still have
+to decide.
+
+If you are doing development on your own using @sc{cvs}
+you could probably skip this chapter. The questions
+this chapter takes up become more important when more
+than one person is working in a repository.
+
address@hidden
+* When to commit:: Some discussion on the subject
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden When to commit
address@hidden When to commit?
address@hidden When to commit
address@hidden Committing, when to
address@hidden Policy
+
+Your group should decide which policy to use regarding
+commits. Several policies are possible, and as your
+experience with @sc{cvs} grows you will probably find
+out what works for you.
+
+If you commit files too quickly you might commit files
+that do not even compile. If your partner updates his
+working sources to include your buggy file, he will be
+unable to compile the code. On the other hand, other
+persons will not be able to benefit from the
+improvements you make to the code if you commit very
+seldom, and conflicts will probably be more common.
+
+It is common to only commit files after making sure
+that they can be compiled. Some sites require that the
+files pass a test suite. Policies like this can be
+enforced using the commitinfo file
+(@pxref{commitinfo}), but you should think twice before
+you enforce such a convention. By making the
+development environment too controlled it might become
+too regimented and thus counter-productive to the real
+goal, which is to get software written.
+
address@hidden
---------------------------------------------------------------------
address@hidden Keyword substitution
address@hidden Keyword substitution
address@hidden Keyword substitution
address@hidden Keyword expansion
address@hidden Identifying files
+
address@hidden Be careful when editing this chapter.
address@hidden Remember that this file is kept under
address@hidden version control, so we must not accidentally
address@hidden include a valid keyword in the running text.
+
+As long as you edit source files inside a working
+directory you can always find out the state of
+your files via @samp{cvs status} and @samp{cvs log}.
+But as soon as you export the files from your
+development environment it becomes harder to identify
+which revisions they are.
+
address@hidden can use a mechanism known as @dfn{keyword
+substitution} (or @dfn{keyword expansion}) to help
+identifying the files. Embedded strings of the form
address@hidden@var{keyword}$} and
address@hidden@var{keyword}:@dots{}$} in a file are replaced
+with strings of the form
address@hidden@var{keyword}:@var{value}$} whenever you obtain
+a new revision of the file.
+
address@hidden
+* Keyword list:: Keywords
+* Using keywords:: Using keywords
+* Avoiding substitution:: Avoiding substitution
+* Substitution modes:: Substitution modes
+* Configuring keyword expansion:: Configuring keyword expansion
+* Log keyword:: Problems with the address@hidden keyword.
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Keyword list
address@hidden Keyword List
address@hidden Keyword List
+
address@hidden FIXME: need some kind of example here I think,
address@hidden perhaps in a
address@hidden "Keyword intro" node. The intro in the "Keyword
address@hidden substitution" node itself seems OK, but to launch
address@hidden into a list of the keywords somehow seems too abrupt.
+
+This is a list of the keywords:
+
address@hidden @code
address@hidden Author keyword
address@hidden address@hidden
+The login name of the user who checked in the revision.
+
address@hidden CVSHeader keyword
address@hidden address@hidden
+A standard header (similar to address@hidden, but with
+the CVS root stripped off). It contains the relative
+pathname of the @sc{rcs} file to the CVS root, the
+revision number, the date (UTC), the author, the state,
+and the locker (if locked). Files will normally never
+be locked when you use @sc{cvs}.
+
+Note that this keyword has only been recently
+introduced to @sc{cvs} and may cause problems with
+existing installations if address@hidden is already
+in the files for a different purpose. This keyword may
+be excluded using the @code{KeywordExpansion=eCVSHeader}
+in the @file{CVSROOT/config} file.
+See @ref{Configuring keyword expansion} for more details.
+
address@hidden Date keyword
address@hidden address@hidden
+The date and time (UTC) the revision was checked in.
+
address@hidden Header keyword
address@hidden address@hidden
+A standard header containing the full pathname of the
address@hidden file, the revision number, the date (UTC), the
+author, the state, and the locker (if locked). Files
+will normally never be locked when you use @sc{cvs}.
+
address@hidden Id keyword
address@hidden address@hidden
+Same as @address@hidden, except that the @sc{rcs}
+filename is without a path.
+
address@hidden Name keyword
address@hidden address@hidden
+Tag name used to check out this file. The keyword is
+expanded only if one checks out with an explicit tag
+name. For example, when running the command @code{cvs
+co -r first}, the keyword expands to @samp{Name: first}.
+
address@hidden Locker keyword
address@hidden address@hidden
+The login name of the user who locked the revision
+(empty if not locked, which is the normal case unless
address@hidden admin -l} is in use).
+
address@hidden Log keyword
address@hidden address@hidden
+The log message supplied during commit, preceded by a
+header containing the @sc{rcs} filename, the revision
+number, the author, and the date (UTC). Existing log
+messages are @emph{not} replaced. Instead, the new log
+message is inserted after @address@hidden:@dots{}$}.
+Each new line is prefixed with the same string which
+precedes the @code{$Log} keyword. For example, if the
+file contains:
+
address@hidden
+ /* Here is what people have been up to:
+ *
+ * address@hidden: frob.c,v $
+ * Revision 1.1 1997/01/03 14:23:51 joe
+ * Add the superfrobnicate option
+ *
+ */
address@hidden example
+
address@hidden
+then additional lines which are added when expanding
+the @code{$Log} keyword will be preceded by @samp{ * }.
+Unlike previous versions of @sc{cvs} and @sc{rcs}, the
address@hidden leader} from the @sc{rcs} file is not used.
+The @code{$Log} keyword is useful for
+accumulating a complete change log in a source file,
+but for several reasons it can be problematic.
address@hidden keyword}.
+
address@hidden RCSfile keyword
address@hidden address@hidden
+The name of the RCS file without a path.
+
address@hidden Revision keyword
address@hidden address@hidden
+The revision number assigned to the revision.
+
address@hidden Source keyword
address@hidden address@hidden
+The full pathname of the RCS file.
+
address@hidden State keyword
address@hidden address@hidden
+The state assigned to the revision. States can be
+assigned with @code{cvs admin -s}---see @ref{admin options}.
+
address@hidden Local keyword
address@hidden Local keyword
+The @code{LocalKeyword} option in the @file{CVSROOT/config} file
+may be used to specify a local keyword which is to be
+used as an alias for one of the other keywords. For
+example, if the @file{CVSROOT/config} file contains
+a line with @code{LocalKeyword=MYBSD=CVSHeader}, then a
+file with the local keyword address@hidden will be
+expanded as if it were a address@hidden keyword. If
+the src/frob.c file contained this keyword, it might
+look something like this:
+
address@hidden
+ /*
+ * address@hidden: src/frob.c,v 1.1 2003/05/04 09:27:45 john Exp $
+ */
address@hidden example
+
+Many repositories make use of a such a ``local
+keyword'' feature. An old patch to @sc{cvs} provided
+the @code{LocalKeyword} feature using a @code{tag=}
+option and called this the ``custom tag'' or ``local
+tag'' feature. It was used in conjunction with the
+what they called the @code{tagexpand=} option. In
address@hidden this other option is known as the
address@hidden option.
+See @ref{Configuring keyword expansion} for more
+details.
+
+Examples from popular projects include:
address@hidden, address@hidden,
address@hidden, address@hidden,
address@hidden
+
+The advantage of this is that you can include your
+local version information in a file using this local
+keyword without disrupting the upstream version
+information (which may be a different local keyword or
+a standard keyword). Allowing bug reports and the like
+to more properly identify the source of the original
+bug to the third-party and reducing the number of
+conflicts that arise during an import of a new version.
+
+All keyword expansion except the local keyword may be
+disabled using the @code{KeywordExpansion} option in
+the @file{CVSROOT/config} file---see
address@hidden keyword expansion} for more details.
+
address@hidden table
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Using keywords
address@hidden Using keywords
+
+To include a keyword string you simply include the
+relevant text string, such as @address@hidden, inside the
+file, and commit the file. @sc{cvs} will automatically
+expand the string as part of the commit operation.
+
+It is common to embed the @address@hidden string in
+the source files so that it gets passed through to
+generated files. For example, if you are managing
+computer program source code, you might include a
+variable which is initialized to contain that string.
+Or some C compilers may provide a @code{#pragma ident}
+directive. Or a document management system might
+provide a way to pass a string through to generated
+files.
+
address@hidden Would be nice to give an example, but doing this in
address@hidden portable C is not possible and the problem with
address@hidden picking any one language (VMS HELP files, Ada,
address@hidden troff, whatever) is that people use CVS for all
address@hidden kinds of files.
+
address@hidden Ident (shell command)
+The @code{ident} command (which is part of the @sc{rcs}
+package) can be used to extract keywords and their
+values from a file. This can be handy for text files,
+but it is even more useful for extracting keywords from
+binary files.
+
address@hidden
+$ ident samp.c
+samp.c:
+ address@hidden: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
+$ gcc samp.c
+$ ident a.out
+a.out:
+ address@hidden: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
address@hidden example
+
address@hidden What (shell command)
address@hidden is another popular revision control system.
+It has a command, @code{what}, which is very similar to
address@hidden and used for the same purpose. Many sites
+without @sc{rcs} have @sc{sccs}. Since @code{what}
+looks for the character sequence @code{@@(#)} it is
+easy to include keywords that are detected by either
+command. Simply prefix the keyword with the
+magic @sc{sccs} phrase, like this:
+
address@hidden
+static char *id="@@(#) address@hidden: ab.c,v 1.5 1993/10/19 14:57:32 ceder
Exp $";
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Avoiding substitution
address@hidden Avoiding substitution
+
+Keyword substitution has its disadvantages. Sometimes
+you might want the literal text string
address@hidden@i{}Author$} to appear inside a file without
address@hidden interpreting it as a keyword and expanding it
+into something like @address@hidden: ceder $}.
+
+There is unfortunately no way to selectively turn off
+keyword substitution. You can use @samp{-ko}
+(@pxref{Substitution modes}) to turn off keyword
+substitution entirely.
+
+In many cases you can avoid using keywords in
+the source, even though they appear in the final
+product. For example, the source for this manual
+contains @samp{$@@address@hidden@}Author$} whenever the text
address@hidden@i{}Author$} should appear. In @code{nroff}
+and @code{troff} you can embed the null-character
address@hidden&} inside the keyword for a similar effect.
+
+It is also possible to specify an explicit list of
+keywords to include or exclude using the
address@hidden option in the
address@hidden/config} file--see @ref{Configuring keyword expansion}
+for more details. This feature is intended primarily
+for use with the @code{LocalKeyword} option--see
address@hidden list}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Substitution modes
address@hidden Substitution modes
address@hidden Keyword substitution, changing modes
address@hidden -k (keyword substitution)
address@hidden Kflag
+
address@hidden FIXME: This could be made more coherent, by expanding it
address@hidden with more examples or something.
+Each file has a stored default substitution mode, and
+each working directory copy of a file also has a
+substitution mode. The former is set by the @samp{-k}
+option to @code{cvs add} and @code{cvs admin}; the
+latter is set by the @samp{-k} or @samp{-A} options to @code{cvs
+checkout} or @code{cvs update}. @code{cvs diff} also
+has a @samp{-k} option. For some examples,
+see @ref{Binary files}, and @ref{Merging and keywords}.
address@hidden The fact that -A is overloaded to mean both reset
address@hidden sticky options and reset sticky tags/dates is
address@hidden somewhat questionable. Perhaps there should be
address@hidden separate options to reset sticky options (e.g. -k
address@hidden A") and tags/dates (someone suggested -r HEAD could
address@hidden do this instead of setting a sticky tag of "HEAD"
address@hidden as in the status quo but I haven't thought much
address@hidden about that idea. Of course -r .reset or something
address@hidden could be coined if this needs to be a new option).
address@hidden On the other hand, having -A mean "get things back
address@hidden into the state after a fresh checkout" has a certain
address@hidden appeal, and maybe there is no sufficient reason for
address@hidden creeping featurism in this area.
+
+The modes available are:
+
address@hidden @samp
address@hidden -kkv
+Generate keyword strings using the default form, e.g.
address@hidden@i{}Revision: 5.7 $} for the @code{Revision}
+keyword.
+
address@hidden -kkvl
+Like @samp{-kkv}, except that a locker's name is always
+inserted if the given revision is currently locked.
+The locker's name is only relevant if @code{cvs admin
+-l} is in use.
+
address@hidden -kk
+Generate only keyword names in keyword strings; omit
+their values. For example, for the @code{Revision}
+keyword, generate the string @address@hidden
+instead of @address@hidden: 5.7 $}. This option
+is useful to ignore differences due to keyword
+substitution when comparing different revisions of a
+file (@pxref{Merging and keywords}).
+
address@hidden -ko
+Generate the old keyword string, present in the working
+file just before it was checked in. For example, for
+the @code{Revision} keyword, generate the string
address@hidden@i{}Revision: 1.1 $} instead of
address@hidden@i{}Revision: 5.7 $} if that is how the
+string appeared when the file was checked in.
+
address@hidden -kb
+Like @samp{-ko}, but also inhibit conversion of line
+endings between the canonical form in which they are
+stored in the repository (linefeed only), and the form
+appropriate to the operating system in use on the
+client. For systems, like unix, which use linefeed
+only to terminate lines, this is very similar to
address@hidden For more information on binary files, see
address@hidden files}. In @sc{cvs} version 1.12.2 and later
address@hidden, as set by @code{cvs add}, @code{cvs admin}, or
address@hidden import} may not be overridden by a @samp{-k} option
+specified on the command line.
+
address@hidden -kv
+Generate only keyword values for keyword strings. For
+example, for the @code{Revision} keyword, generate the string
address@hidden instead of @address@hidden: 5.7 $}.
+This can help generate files in programming languages
+where it is hard to strip keyword delimiters like
address@hidden@i{}Revision: $} from a string. However,
+further keyword substitution cannot be performed once
+the keyword names are removed, so this option should be
+used with care.
+
+One often would like to use @samp{-kv} with @code{cvs
address@hidden But be aware that doesn't
+handle an export containing binary files correctly.
+
address@hidden table
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Configuring keyword expansion
address@hidden Configuring Keyord Expansion
address@hidden Configuring keyword expansion
+
+In a repository that includes third-party software on
+vendor branches, it is sometimes helpful to configure
+CVS to use a local keyword instead of the standard
address@hidden or address@hidden keywords. Examples from
+real projects includ, address@hidden, address@hidden,
address@hidden, address@hidden,
address@hidden, and even address@hidden
+The advantage of this is that
+you can include your local version information in a
+file using this local keyword (sometimes called a
+``custom tag'' or a ``local tag'') without disrupting
+the upstream version information (which may be a
+different local keyword or a standard keyword). In
+these cases, it is typically desirable to disable the
+expansion of all keywords except the configured local
+keyword.
+
+The @code{KeywordExpansion} option in the
address@hidden/config} file is intended to allow for the
+either the explicit exclusion of a keyword or list of
+keywords, or for the explicit inclusion of a keyword or
+a list of keywords. This list may include the
address@hidden that has been configured.
+
+The @code{KeywordExpansion} option is followed by
address@hidden and the next character may either be @code{i}
+to start an inclusion list or @code{e} to start an
+exclusion list. If the following lines were added to
+the @file{CVSROOT/config} file:
+
address@hidden
+ # Add a "MyBSD" keyword and restrict keyword
+ # expansion
+ LocalKeyword=MyBSD=CVSHeader
+ KeywordExpand=iMyBSD
address@hidden example
+
+then only the address@hidden keyword would be expanded.
+A list may be used. The this example:
+
address@hidden
+ # Add a "MyBSD" keyword and restrict keyword
+ # expansion to the MyBSD, Name and Date keywords.
+ LocalKeyword=MyBSD=CVSHeader
+ KeywordExpand=iMyBSD,Name,Date
address@hidden example
+
+would allow address@hidden, address@hidden, and
address@hidden to be expanded.
+
+It is also possible to configure an exclusion list
+using the following:
+
address@hidden
+ # Do not expand the non-RCS keyword CVSHeader
+ KeywordExpand=eCVSHeader
address@hidden example
+
+This allows @sc{cvs} to ignore the recently introduced
address@hidden keyword and retain all of the
+others. The exclusion entry could also contain the
+standard RCS keyword list, but this could be confusing
+to users that expect RCS keywords to be expanded, so
+ycare should be taken to properly set user expectations
+for a repository that is configured in that manner.
+
+If there is a desire to not have any RCS keywords
+expanded and not use the @code{-ko} flags everywhere,
+an administrator may disable all keyword expansion
+using the @file{CVSROOT/config} line:
+
address@hidden
+ # Do not expand any RCS keywords
+ KeywordExpand=i
address@hidden example
+
+this could be confusing to users that expect RCS
+keywords like address@hidden to be expanded properly,
+so care should be taken to properly set user
+expectations for a repository so configured.
+
+It should be noted that a patch to provide both the
address@hidden and @code{LocalKeyword} features
+has been around a long time. However, that patch
+implemented these features using @code{tag=} and
address@hidden keywords and those keywords are NOT
+recognized.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Log keyword
address@hidden Problems with the address@hidden keyword.
+
+The @address@hidden keyword is somewhat
+controversial. As long as you are working on your
+development system the information is easily accessible
+even if you do not use the @address@hidden
+keyword---just do a @code{cvs log}. Once you export
+the file the history information might be useless
+anyhow.
+
+A more serious concern is that @sc{cvs} is not good at
+handling @address@hidden entries when a branch is
+merged onto the main trunk. Conflicts often result
+from the merging operation.
address@hidden Might want to check whether the CVS implementation
address@hidden of RCS_merge has this problem the same way rcsmerge
address@hidden does. I would assume so....
+
+People also tend to "fix" the log entries in the file
+(correcting spelling mistakes and maybe even factual
+errors). If that is done the information from
address@hidden log} will not be consistent with the
+information inside the file. This may or may not be a
+problem in real life.
+
+It has been suggested that the @address@hidden
+keyword should be inserted @emph{last} in the file, and
+not in the files header, if it is to be used at all.
+That way the long list of change messages will not
+interfere with everyday source file browsing.
+
address@hidden
---------------------------------------------------------------------
address@hidden Tracking sources
address@hidden Tracking third-party sources
address@hidden Third-party sources
address@hidden Tracking sources
+
address@hidden FIXME: Need discussion of added and removed files.
address@hidden FIXME: This doesn't really adequately introduce the
address@hidden concepts of "vendor" and "you". They don't *have*
address@hidden to be separate organizations or separate people.
address@hidden We want a description which is somewhat more based on
address@hidden the technical issues of which sources go where, but
address@hidden also with enough examples of how this relates to
address@hidden relationships like customer-supplier, developer-QA,
address@hidden maintainer-contributor, or whatever, to make it
address@hidden seem concrete.
+If you modify a program to better fit your site, you
+probably want to include your modifications when the next
+release of the program arrives. @sc{cvs} can help you with
+this task.
+
address@hidden Vendor
address@hidden Vendor branch
address@hidden Branch, vendor-
+In the terminology used in @sc{cvs}, the supplier of the
+program is called a @dfn{vendor}. The unmodified
+distribution from the vendor is checked in on its own
+branch, the @dfn{vendor branch}. @sc{cvs} reserves branch
+1.1.1 for this use.
+
+When you modify the source and commit it, your revision
+will end up on the main trunk. When a new release is
+made by the vendor, you commit it on the vendor branch
+and copy the modifications onto the main trunk.
+
+Use the @code{import} command to create and update
+the vendor branch. When you import a new file,
+the vendor branch is made the `head' revision, so
+anyone that checks out a copy of the file gets that
+revision. When a local modification is committed it is
+placed on the main trunk, and made the `head'
+revision.
+
address@hidden
+* First import:: Importing for the first time
+* Update imports:: Updating with the import command
+* Reverting local changes:: Reverting to the latest vendor release
+* Binary files in imports:: Binary files require special handling
+* Keywords in imports:: Keyword substitution might be undesirable
+* Multiple vendor branches:: What if you get sources from several places?
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden First import
address@hidden Importing for the first time
address@hidden Importing modules
+
address@hidden Should mention naming conventions for vendor tags,
address@hidden release tags, and perhaps directory names.
+Use the @code{import} command to check in the sources
+for the first time. When you use the @code{import}
+command to track third-party sources, the @dfn{vendor
+tag} and @dfn{release tags} are useful. The
address@hidden tag} is a symbolic name for the branch
+(which is always 1.1.1, unless you use the @samp{-b
address@hidden flag---see @ref{Multiple vendor branches}.). The
address@hidden tags} are symbolic names for a particular
+release, such as @samp{FSF_0_04}.
+
address@hidden I'm not completely sure this belongs here. But
address@hidden we need to say it _somewhere_ reasonably obvious; it
address@hidden is a common misconception among people first learning CVS
+Note that @code{import} does @emph{not} change the
+directory in which you invoke it. In particular, it
+does not set up that directory as a @sc{cvs} working
+directory; if you want to work with the sources import
+them first and then check them out into a different
+directory (@pxref{Getting the source}).
+
address@hidden wdiff (import example)
+Suppose you have the sources to a program called
address@hidden in a directory @file{wdiff-0.04},
+and are going to make private modifications that you
+want to be able to use even when new releases are made
+in the future. You start by importing the source to
+your repository:
+
address@hidden
+$ cd wdiff-0.04
+$ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04
address@hidden example
+
+The vendor tag is named @samp{FSF_DIST} in the above
+example, and the only release tag assigned is
address@hidden
address@hidden FIXME: Need to say where fsf/wdiff comes from.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Update imports
address@hidden Updating with the import command
+
+When a new release of the source arrives, you import it into the
+repository with the same @code{import} command that you used to set up
+the repository in the first place. The only difference is that you
+specify a different release tag this time:
+
address@hidden
+$ tar xfz wdiff-0.05.tar.gz
+$ cd wdiff-0.05
+$ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05
address@hidden example
+
+For files that have not been modified locally, the newly created
+revision becomes the head revision. If you have made local
+changes, @code{import} will warn you that you must merge the changes
+into the main trunk, and tell you to use @samp{checkout -j} to do so:
+
address@hidden FIXME: why "wdiff" here and "fsf/wdiff" in the
address@hidden "import"? I think the assumption is that one has
address@hidden "wdiff fsf/wdiff" or some such in modules, but it
address@hidden would be better to not use modules in this example.
address@hidden
+$ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff
address@hidden example
+
address@hidden
+The above command will check out the latest revision of
address@hidden, merging the changes made on the vendor branch @samp{FSF_DIST}
+since yesterday into the working copy. If any conflicts arise during
+the merge they should be resolved in the normal way (@pxref{Conflicts
+example}). Then, the modified files may be committed.
+
+However, it is much better to use the two release tags rather than using
+a date on the branch as suggested above:
+
address@hidden
+$ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff
address@hidden example
+
address@hidden
+The reason this is better is that
+using a date, as suggested above, assumes that you do
+not import more than one release of a product per day.
+More importantly, using the release tags allows @sc{cvs} to detect files
+that were removed between the two vendor releases and mark them for
+removal. Since @code{import} has no way to detect removed files, you
+should do a merge like this even if @code{import} doesn't tell you to.
+
address@hidden Reverting local changes
address@hidden Reverting to the latest vendor release
+
+You can also revert local changes completely and return
+to the latest vendor release by changing the `head'
+revision back to the vendor branch on all files. For
+example, if you have a checked-out copy of the sources
+in @file{~/work.d/wdiff}, and you want to revert to the
+vendor's version for all the files in that directory,
+you would type:
+
address@hidden
+$ cd ~/work.d/wdiff
+$ cvs admin -bWDIFF .
address@hidden example
+
address@hidden
+You must specify the @samp{-bWDIFF} without any space
+after the @samp{-b}. @xref{admin options}.
+
address@hidden Binary files in imports
address@hidden How to handle binary files with cvs import
+
+Use the @samp{-k} wrapper option to tell import which
+files are binary. @xref{Wrappers}.
+
address@hidden Keywords in imports
address@hidden How to handle keyword substitution with cvs import
+
+The sources which you are importing may contain
+keywords (@pxref{Keyword substitution}). For example,
+the vendor may use @sc{cvs} or some other system
+which uses similar keyword expansion syntax. If you
+just import the files in the default fashion, then
+the keyword expansions supplied by the vendor will
+be replaced by keyword expansions supplied by your
+own copy of @sc{cvs}. It may be more convenient to
+maintain the expansions supplied by the vendor, so
+that this information can supply information about
+the sources that you imported from the vendor.
+
+To maintain the keyword expansions supplied by the
+vendor, supply the @samp{-ko} option to @code{cvs
+import} the first time you import the file.
+This will turn off keyword expansion
+for that file entirely, so if you want to be more
+selective you'll have to think about what you want
+and use the @samp{-k} option to @code{cvs update} or
address@hidden admin} as appropriate.
address@hidden Supplying -ko to import if the file already existed
address@hidden has no effect. Not clear to me whether it should
address@hidden or not.
+
address@hidden Multiple vendor branches
address@hidden Multiple vendor branches
+
+All the examples so far assume that there is only one
+vendor from which you are getting sources. In some
+situations you might get sources from a variety of
+places. For example, suppose that you are dealing with
+a project where many different people and teams are
+modifying the software. There are a variety of ways to
+handle this, but in some cases you have a bunch of
+source trees lying around and what you want to do more
+than anything else is just to all put them in @sc{cvs} so
+that you at least have them in one place.
+
+For handling situations in which there may be more than
+one vendor, you may specify the @samp{-b} option to
address@hidden import}. It takes as an argument the vendor
+branch to import to. The default is @samp{-b 1.1.1}.
+
+For example, suppose that there are two teams, the red
+team and the blue team, that are sending you sources.
+You want to import the red team's efforts to branch
+1.1.1 and use the vendor tag RED. You want to import
+the blue team's efforts to branch 1.1.3 and use the
+vendor tag BLUE. So the commands you might use are:
+
address@hidden
+$ cvs import dir RED RED_1-0
+$ cvs import -b 1.1.3 dir BLUE BLUE_1-5
address@hidden example
+
+Note that if your vendor tag does not match your
address@hidden option, @sc{cvs} will not detect this case! For
+example,
+
address@hidden
+$ cvs import -b 1.1.3 dir RED RED_1-0
address@hidden example
+
address@hidden
+Be careful; this kind of mismatch is sure to sow
+confusion or worse. I can't think of a useful purpose
+for the ability to specify a mismatch here, but if you
+discover such a use, don't. @sc{cvs} is likely to make this
+an error in some future release.
+
address@hidden Probably should say more about the semantics of
address@hidden multiple branches. What about the default branch?
address@hidden What about joining (perhaps not as useful with
address@hidden multiple branches, or perhaps it is. Either way
address@hidden should be mentioned).
+
address@hidden I'm not sure about the best location for this. In
address@hidden one sense, it might belong right after we've introduced
address@hidden CVS's basic version control model, because people need
address@hidden to figure out builds right away. The current location
address@hidden is based on the theory that it kind of akin to the
address@hidden "Revision management" section.
address@hidden Builds
address@hidden How your build system interacts with CVS
address@hidden Builds
address@hidden make
+
+As mentioned in the introduction, @sc{cvs} does not
+contain software for building your software from source
+code. This section describes how various aspects of
+your build system might interact with @sc{cvs}.
+
address@hidden Is there a way to discuss this without reference to
address@hidden tools other than CVS? I'm not sure there is; I
address@hidden wouldn't think that people who learn CVS first would
address@hidden even have this concern.
+One common question, especially from people who are
+accustomed to @sc{rcs}, is how to make their build get
+an up to date copy of the sources. The answer to this
+with @sc{cvs} is two-fold. First of all, since
address@hidden itself can recurse through directories, there
+is no need to modify your @file{Makefile} (or whatever
+configuration file your build tool uses) to make sure
+each file is up to date. Instead, just use two
+commands, first @code{cvs -q update} and then
address@hidden or whatever the command is to invoke your
+build tool. Secondly, you do not necessarily
address@hidden to get a copy of a change someone else made
+until you have finished your own work. One suggested
+approach is to first update your sources, then
+implement, build and
+test the change you were thinking of, and then commit
+your sources (updating first if necessary). By
+periodically (in between changes, using the approach
+just described) updating your entire tree, you ensure
+that your sources are sufficiently up to date.
+
address@hidden Bill of materials
+One common need is to record which versions of which
+source files went into a particular build. This kind
+of functionality is sometimes called @dfn{bill of
+materials} or something similar. The best way to do
+this with @sc{cvs} is to use the @code{tag} command to
+record which versions went into a given build
+(@pxref{Tags}).
+
+Using @sc{cvs} in the most straightforward manner
+possible, each developer will have a copy of the entire
+source tree which is used in a particular build. If
+the source tree is small, or if developers are
+geographically dispersed, this is the preferred
+solution. In fact one approach for larger projects is
+to break a project down into smaller
address@hidden I say subsystem instead of module because they may or
address@hidden may not use the modules file.
+separately-compiled subsystems, and arrange a way of
+releasing them internally so that each developer need
+check out only those subsystems which they are
+actively working on.
+
+Another approach is to set up a structure which allows
+developers to have their own copies of some files, and
+for other files to access source files from a central
+location. Many people have come up with some such a
address@hidden two such people are address@hidden (for
address@hidden a previous employer)
address@hidden and address@hidden (spicm and related tools),
address@hidden but as far as I know
address@hidden no one has nicely packaged or released such a system (or
address@hidden instructions for constructing one).
+system using features such as the symbolic link feature
+found in many operating systems, or the @code{VPATH}
+feature found in many versions of @code{make}. One build
+tool which is designed to help with this kind of thing
+is Odin (see
address@hidden://ftp.cs.colorado.edu/pub/distribs/odin}).
address@hidden Should we be saying more about Odin? Or how you use
address@hidden it with CVS? Also, the Prime Time Freeware for Unix
address@hidden disk (see http://www.ptf.com/) has Odin (with a nice
address@hidden paragraph summarizing it on the web), so that might be a
address@hidden semi-"official" place to point people.
address@hidden
address@hidden Of course, many non-CVS systems have this kind of
address@hidden functionality, for example OSF's ODE
address@hidden (http://www.osf.org/ode/) or mk
address@hidden (http://www.grin.net/~pzi/mk-3.18.4.docs/mk_toc.html
address@hidden He has changed providers in the past; a search engine search
address@hidden for "Peter Ziobrzynski" probably won't get too many
address@hidden spurious hits :-). A more stable URL might be
address@hidden ftp://ftp.uu.net/pub/cmvc/mk). But I'm not sure
address@hidden there is any point in mentioning them here unless they
address@hidden can work with CVS.
+
address@hidden
---------------------------------------------------------------------
address@hidden Special Files
address@hidden Special Files
+
address@hidden Special files
address@hidden Device nodes
address@hidden Ownership, saving in CVS
address@hidden Permissions, saving in CVS
address@hidden Hard links
address@hidden Symbolic links
+
+In normal circumstances, @sc{cvs} works only with regular
+files. Every file in a project is assumed to be
+persistent; it must be possible to open, read and close
+them; and so on. @sc{cvs} also ignores file permissions and
+ownerships, leaving such issues to be resolved by the
+developer at installation time. In other words, it is
+not possible to "check in" a device into a repository;
+if the device file cannot be opened, @sc{cvs} will refuse to
+handle it. Files also lose their ownerships and
+permissions during repository transactions.
+
+
address@hidden
---------------------------------------------------------------------
address@hidden CVS commands
address@hidden Guide to CVS commands
+
+This appendix describes the overall structure of
address@hidden commands, and describes some commands in
+detail (others are described elsewhere; for a quick
+reference to @sc{cvs} commands, @pxref{Invoking CVS}).
address@hidden The idea is that we want to move the commands which
address@hidden are described here into the main body of the manual,
address@hidden in the process reorganizing the manual to be
address@hidden organized around what the user wants to do, not
address@hidden organized around CVS commands.
address@hidden
address@hidden Note that many users do expect a manual which is
address@hidden organized by command. At least some users do.
address@hidden One good addition to the "organized by command"
address@hidden section (if any) would be "see also" links.
address@hidden The awk manual might be a good example; it has a
address@hidden reference manual which is more verbose than Invoking
address@hidden CVS but probably somewhat less verbose than CVS
address@hidden Commands.
+
address@hidden
+* Structure:: Overall structure of CVS commands
+* Exit status:: Indicating CVS's success or failure
+* ~/.cvsrc:: Default options with the ~/.csvrc file
+* Global options:: Options you give to the left of cvs_command
+* Common options:: Options you give to the right of cvs_command
+* admin:: Administration
+* checkout:: Checkout sources for editing
+* commit:: Check files into the repository
+* diff:: Show differences between revisions
+* export:: Export sources from CVS, similar to checkout
+* history:: Show status of files and users
+* import:: Import sources into CVS, using vendor branches
+* log:: Show log messages for files
+* rdiff:: 'patch' format diffs between releases
+* release:: Indicate that a directory is no longer in use
+* update:: Bring work tree in sync with repository
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Structure
address@hidden Overall structure of CVS commands
address@hidden Structure
address@hidden CVS command structure
address@hidden Command structure
address@hidden Format of CVS commands
+
+The overall format of all @sc{cvs} commands is:
+
address@hidden
+cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ]
address@hidden example
+
address@hidden @code
address@hidden cvs
+The name of the @sc{cvs} program.
+
address@hidden cvs_options
+Some options that affect all sub-commands of @sc{cvs}. These are
+described below.
+
address@hidden cvs_command
+One of several different sub-commands. Some of the commands have
+aliases that can be used instead; those aliases are noted in the
+reference manual for that command. There are only two situations
+where you may omit @samp{cvs_command}: @samp{cvs -H} elicits a
+list of available commands, and @samp{cvs -v} displays version
+information on @sc{cvs} itself.
+
address@hidden command_options
+Options that are specific for the command.
+
address@hidden command_args
+Arguments to the commands.
address@hidden table
+
+There is unfortunately some confusion between
address@hidden and @code{command_options}.
address@hidden, when given as a @code{cvs_option}, only
+affects some of the commands. When it is given as a
address@hidden is has a different meaning, and
+is accepted by more commands. In other words, do not
+take the above categorization too seriously. Look at
+the documentation instead.
+
address@hidden Exit status
address@hidden CVS's exit status
address@hidden Exit status, of CVS
+
address@hidden can indicate to the calling environment whether it
+succeeded or failed by setting its @dfn{exit status}.
+The exact way of testing the exit status will vary from
+one operating system to another. For example in a unix
+shell script the @samp{$?} variable will be 0 if the
+last command returned a successful exit status, or
+greater than 0 if the exit status indicated failure.
+
+If @sc{cvs} is successful, it returns a successful status;
+if there is an error, it prints an error message and
+returns a failure status. The one exception to this is
+the @code{cvs diff} command. It will return a
+successful status if it found no differences, or a
+failure status if there were differences or if there
+was an error. Because this behavior provides no good
+way to detect errors, in the future it is possible that
address@hidden diff} will be changed to behave like the
+other @sc{cvs} commands.
address@hidden It might seem like checking whether cvs -q diff
address@hidden produces empty or non-empty output can tell whether
address@hidden there were differences or not. But it seems like
address@hidden there are cases with output but no differences
address@hidden (testsuite basica-8b). It is not clear to me how
address@hidden useful it is for a script to be able to check
address@hidden whether there were differences.
address@hidden FIXCVS? In previous versions of CVS, cvs diff
address@hidden returned 0 for no differences, 1 for differences, or
address@hidden 2 for errors. Is this behavior worth trying to
address@hidden bring back (but what does it mean for VMS?)?
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden ~/.cvsrc
address@hidden Default options and the ~/.cvsrc file
address@hidden .cvsrc file
address@hidden Option defaults
+
+There are some @code{command_options} that are used so
+often that you might have set up an alias or some other
+means to make sure you always specify that option. One
+example (the one that drove the implementation of the
address@hidden support, actually) is that many people find the
+default output of the @samp{diff} command to be very
+hard to read, and that either context diffs or unidiffs
+are much easier to understand.
+
+The @file{~/.cvsrc} file is a way that you can add
+default options to @code{cvs_commands} within cvs,
+instead of relying on aliases or other shell scripts.
+
+The format of the @file{~/.cvsrc} file is simple. The
+file is searched for a line that begins with the same
+name as the @code{cvs_command} being executed. If a
+match is found, then the remainder of the line is split
+up (at whitespace characters) into separate options and
+added to the command arguments @emph{before} any
+options from the command line.
+
+If a command has two names (e.g., @code{checkout} and
address@hidden), the official name, not necessarily the one
+used on the command line, will be used to match against
+the file. So if this is the contents of the user's
address@hidden/.cvsrc} file:
+
address@hidden
+log -N
+diff -uN
+rdiff -u
+update -Pd
+checkout -P
+release -d
address@hidden example
+
address@hidden
+the command @samp{cvs checkout foo} would have the
address@hidden option added to the arguments, as well as
address@hidden co foo}.
+
+With the example file above, the output from @samp{cvs
+diff foobar} will be in unidiff format. @samp{cvs diff
+-c foobar} will provide context diffs, as usual.
+Getting "old" format diffs would be slightly more
+complicated, because @code{diff} doesn't have an option
+to specify use of the "old" format, so you would need
address@hidden -f diff foobar}.
+
+In place of the command name you can use @code{cvs} to
+specify global options (@pxref{Global options}). For
+example the following line in @file{.cvsrc}
+
address@hidden
+cvs -z6
address@hidden example
+
address@hidden
+causes @sc{cvs} to use compression level 6.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Global options
address@hidden Global options
address@hidden Options, global
address@hidden Global options
address@hidden Left-hand options
+
+The available @samp{cvs_options} (that are given to the
+left of @samp{cvs_command}) are:
+
address@hidden @code
address@hidden address@hidden
+Specify legal @sc{cvsroot} directory. See
address@hidden authentication server}.
+
address@hidden Authentication, stream
address@hidden Stream authentication
address@hidden -a
+Authenticate all communication between the client and
+the server. Only has an effect on the @sc{cvs} client.
+As of this writing, this is only implemented when using
+a GSSAPI connection (@pxref{GSSAPI authenticated}).
+Authentication prevents certain sorts of attacks
+involving hijacking the active @sc{tcp} connection.
+Enabling authentication does not enable encryption.
+
address@hidden RCSBIN, overriding
address@hidden Overriding RCSBIN
address@hidden -b @var{bindir}
+In @sc{cvs} 1.9.18 and older, this specified that
address@hidden programs are in the @var{bindir} directory.
+Current versions of @sc{cvs} do not run @sc{rcs}
+programs; for compatibility this option is accepted,
+but it does nothing.
+
address@hidden TMPDIR, overriding
address@hidden Overriding TMPDIR
address@hidden -T @var{tempdir}
+Use @var{tempdir} as the directory where temporary files are
+located. Overrides the setting of the @code{$TMPDIR} environment
+variable and any precompiled directory. This parameter should be
+specified as an absolute pathname.
+(When running client/server, @samp{-T} affects only the local process;
+specifying @samp{-T} for the client has no effect on the server and
+vice versa.)
+
address@hidden CVSROOT, overriding
address@hidden Overriding CVSROOT
address@hidden -d @var{cvs_root_directory}
+Use @var{cvs_root_directory} as the root directory
+pathname of the repository. Overrides the setting of
+the @code{$CVSROOT} environment variable. @xref{Repository}.
+
address@hidden EDITOR, overriding
address@hidden Overriding EDITOR
address@hidden -e @var{editor}
+Use @var{editor} to enter revision log information. Overrides the
+setting of the @code{$CVSEDITOR} and @code{$EDITOR}
+environment variables. For more information, see
address@hidden your changes}.
+
address@hidden -f
+Do not read the @file{~/.cvsrc} file. This
+option is most often used because of the
+non-orthogonality of the @sc{cvs} option set. For
+example, the @samp{cvs log} option @samp{-N} (turn off
+display of tag names) does not have a corresponding
+option to turn the display on. So if you have
address@hidden in the @file{~/.cvsrc} entry for @samp{log},
+you may need to use @samp{-f} to show the tag names.
+
address@hidden -H
address@hidden --help
+Display usage information about the specified @samp{cvs_command}
+(but do not actually execute the command). If you don't specify
+a command name, @samp{cvs -H} displays overall help for
address@hidden, including a list of other help options.
address@hidden It seems to me it is better to document it this way
address@hidden rather than trying to update this documentation
address@hidden every time that we add a --help-foo option. But
address@hidden perhaps that is confusing...
+
address@hidden -l
+Do not log the @samp{cvs_command} in the command history (but execute it
+anyway). @xref{history}, for information on command history.
+
address@hidden Read-only repository mode
address@hidden -R
+Turns on read-only repository mode. This allows one to check out from a
+read-only repository, such as within an anoncvs server, or from a CDROM
+repository.
+
+Same effect as if the @code{CVSREADONLYFS} environment
+variable is set. Using @samp{-R} can also considerably
+speed up checkout's over NFS.
+
address@hidden Read-only mode
address@hidden -n
+Do not change any files. Attempt to execute the
address@hidden, but only to issue reports; do not remove,
+update, or merge any existing files, or create any new files.
+
+Note that @sc{cvs} will not necessarily produce exactly
+the same output as without @samp{-n}. In some cases
+the output will be the same, but in other cases
address@hidden will skip some of the processing that would
+have been required to produce the exact same output.
+
address@hidden -Q
+Cause the command to be really quiet; the command will only
+generate output for serious problems.
+
address@hidden -q
+Cause the command to be somewhat quiet; informational messages,
+such as reports of recursion through subdirectories, are
+suppressed.
+
address@hidden Read-only files, and -r
address@hidden -r
+Make new working files read-only. Same effect
+as if the @code{$CVSREAD} environment variable is set
+(@pxref{Environment variables}). The default is to
+make working files writable, unless watches are on
+(@pxref{Watches}).
+
address@hidden -s @address@hidden
+Set a user variable (@pxref{Variables}).
+
address@hidden Trace
address@hidden -t
+Trace program execution; display messages showing the steps of
address@hidden activity. Particularly useful with @samp{-n} to explore the
+potential impact of an unfamiliar command.
+
address@hidden -v
address@hidden --version
+Display version and copyright information for @sc{cvs}.
+
address@hidden CVSREAD, overriding
address@hidden Overriding CVSREAD
address@hidden -w
+Make new working files read-write. Overrides the
+setting of the @code{$CVSREAD} environment variable.
+Files are created read-write by default, unless @code{$CVSREAD} is
+set or @samp{-r} is given.
address@hidden Note that -w only overrides -r and CVSREAD; it has
address@hidden no effect on files which are readonly because of
address@hidden "cvs watch on". My guess is that is the way it
address@hidden should be (or should "cvs -w get" on a watched file
address@hidden be the same as a get and a cvs edit?), but I'm not
address@hidden completely sure whether to document it this way.
+
address@hidden -x
address@hidden Encryption
+Encrypt all communication between the client and the
+server. Only has an effect on the @sc{cvs} client. As
+of this writing, this is only implemented when using a
+GSSAPI connection (@pxref{GSSAPI authenticated}) or a
+Kerberos connection (@pxref{Kerberos authenticated}).
+Enabling encryption implies that message traffic is
+also authenticated. Encryption support is not
+available by default; it must be enabled using a
+special configure option, @file{--enable-encryption},
+when you build @sc{cvs}.
+
address@hidden -z @var{gzip-level}
address@hidden Compression
address@hidden Gzip
+Set the compression level.
+Valid levels are 1 (high speed, low compression) to
+9 (low speed, high compression), or 0 to disable
+compression (the default).
+Only has an effect on the @sc{cvs} client.
+
address@hidden table
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Common options
address@hidden Common command options
address@hidden Common options
address@hidden Right-hand options
+
+This section describes the @samp{command_options} that
+are available across several @sc{cvs} commands. These
+options are always given to the right of
address@hidden Not all
+commands support all of these options; each option is
+only supported for commands where it makes sense.
+However, when a command has one of these options you
+can almost always count on the same behavior of the
+option as in other commands. (Other command options,
+which are listed with the individual commands, may have
+different behavior from one @sc{cvs} command to the other).
+
address@hidden: the @samp{history} command is an exception; it supports
+many options that conflict even with these standard options.}
+
address@hidden @code
address@hidden Dates
address@hidden Time
address@hidden Specifying dates
address@hidden -D @var{date_spec}
+Use the most recent revision no later than @var{date_spec}.
address@hidden is a single argument, a date description
+specifying a date in the past.
+
+The specification is @dfn{sticky} when you use it to make a
+private copy of a source file; that is, when you get a working
+file using @samp{-D}, @sc{cvs} records the date you specified, so that
+further updates in the same directory will use the same date
+(for more information on sticky tags/dates, @pxref{Sticky tags}).
+
address@hidden is available with the @code{annotate}, @code{checkout},
address@hidden, @code{export}, @code{history},
address@hidden, @code{rtag}, @code{tag}, and @code{update} commands.
+(The @code{history} command uses this option in a
+slightly different way; @pxref{history options}).
+
address@hidden What other formats should we accept? I don't want
address@hidden to start accepting a whole mess of non-standard
address@hidden new formats (there are a lot which are in wide use in
address@hidden one context or another), but practicality does
address@hidden dictate some level of flexibility.
address@hidden * POSIX.2 (e.g. touch, ls output, date) and other
address@hidden POSIX and/or de facto unix standards (e.g. at). The
address@hidden practice here is too inconsistent to be of any use.
address@hidden * VMS dates. This is not a formal standard, but
address@hidden there is a published specification (see SYS$ASCTIM
address@hidden and SYS$BINTIM in the _VMS System Services Reference
address@hidden Manual_), it is implemented consistently in VMS
address@hidden utilities, and VMS users will expect CVS running on
address@hidden VMS to support this format (and if we're going to do
address@hidden that, better to make CVS support it on all
address@hidden platforms. Maybe).
address@hidden
address@hidden NOTE: The tar manual has some documentation for
address@hidden getdate.y (just for our info; we don't want to
address@hidden attempt to document all the formats accepted by
address@hidden getdate.y).
address@hidden
address@hidden One more note: In output, CVS should consistently
address@hidden use one date format, and that format should be one that
address@hidden it accepts in input as well. The former isn't
address@hidden really true (see survey below), and I'm not
address@hidden sure that either of those formats is accepted in
address@hidden input.
address@hidden
address@hidden cvs log
address@hidden current 1996/01/02 13:45:31
address@hidden Internet 02 Jan 1996 13:45:31 UT
address@hidden ISO 1996-01-02 13:45:31
address@hidden cvs ann
address@hidden current 02-Jan-96
address@hidden Internet-like 02 Jan 96
address@hidden ISO 96-01-02
address@hidden cvs status
address@hidden current Tue Jun 11 02:54:53 1996
address@hidden Internet [Tue,] 11 Jun 1996 02:54:53
address@hidden ISO 1996-06-11 02:54:53
address@hidden note: date possibly should be omitted entirely for
address@hidden other reasons.
address@hidden cvs editors
address@hidden current Tue Jun 11 02:54:53 1996 GMT
address@hidden cvs history
address@hidden current 06/11 02:54 +0000
address@hidden any others?
address@hidden There is a good chance the proper solution has to
address@hidden involve at least some level of letting the user
address@hidden decide which format (with the default being the
address@hidden formats CVS has always used; changing these might be
address@hidden _very_ disruptive since scripts may very well be
address@hidden parsing them).
address@hidden
address@hidden Another random bit of prior art concerning dates is
address@hidden the strptime function which takes templates such as
address@hidden "%m/%d/%y", and apparent a variant of getdate()
address@hidden which also honors them. See
address@hidden X/Open CAE Specification, System Interfaces and
address@hidden Headers Issue 4, Version 2 (September 1994), in the
address@hidden entry for getdate() on page 231
+
address@hidden Timezone, in input
address@hidden Zone, time, in input
+A wide variety of date formats are supported by
address@hidden The most standard ones are ISO8601 (from the
+International Standards Organization) and the Internet
+e-mail standard (specified in RFC822 as amended by
+RFC1123).
+
address@hidden Probably should be doing more to spell out just what
address@hidden the rules are, rather than just giving examples.
address@hidden But I want to keep this simple too.
address@hidden So I don't know....
address@hidden A few specific issues: (1) Maybe should reassure
address@hidden people that years after 2000
address@hidden work (they are in the testsuite, so they do indeed
address@hidden work). (2) What do two digit years
address@hidden mean? Where do we accept them? (3) Local times can
address@hidden be ambiguous or nonexistent if they fall during the
address@hidden hour when daylight savings time goes into or out of
address@hidden effect. Pretty obscure, so I'm not at all sure we
address@hidden should be documenting the behavior in that case.
+ISO8601 dates have many variants but a few examples
+are:
+
address@hidden
+1972-09-24
+1972-09-24 20:05
address@hidden example
address@hidden I doubt we really accept all ISO8601 format dates
address@hidden (for example, decimal hours like 1972-09-24 20,2)
address@hidden I'm not sure we should, many of them are pretty
address@hidden bizarre and it has lots of gratuitous multiple ways
address@hidden to specify the same thing.
+
+There are a lot more ISO8601 date formats, and @sc{cvs}
+accepts many of them, but you probably don't want to
+hear the @emph{whole} long story :-).
+
address@hidden Citing a URL here is kind of problematic given how
address@hidden much they change and people who have old versions of
address@hidden this manual, but in case we want to reinstate an
address@hidden ISO8601 URL, a few are:
address@hidden http://www.saqqara.demon.co.uk/datefmt.htm
address@hidden http://www.cl.cam.ac.uk/~mgk25/iso-time.html
address@hidden Citing some other ISO8601 source is probably even
address@hidden worse :-).
+
+In addition to the dates allowed in Internet e-mail
+itself, @sc{cvs} also allows some of the fields to be
+omitted. For example:
address@hidden FIXME: Need to figure out better, and document,
address@hidden what we want to allow the user to omit.
address@hidden NOTE: "omit" does not imply "reorder".
address@hidden FIXME: Need to cite a web page describing how to get
address@hidden RFC's.
+
address@hidden
+24 Sep 1972 20:05
+24 Sep
address@hidden example
+
+The date is interpreted as being in the
+local timezone, unless a specific timezone is
+specified.
+
+These two date formats are preferred. However,
address@hidden currently accepts a wide variety of other date
+formats. They are intentionally not documented here in
+any detail, and future versions of @sc{cvs} might not
+accept all of them.
address@hidden We should document and testsuite "now" and
address@hidden "yesterday". "now" is mentioned in the FAQ and
address@hidden "yesterday" is mentioned in this document (and the
address@hidden message from "cvs import" suggesting a merge
address@hidden command). What else? Probably some/all of the "3
address@hidden weeks ago" family.
address@hidden
address@hidden Maybe at
address@hidden some point have CVS start give warnings on "unofficial"
address@hidden formats (many of which might be typos or user
address@hidden misunderstandings, and/or formats people never/rarely
address@hidden use to specify dates)?
+
+One such format is
address@hidden@var{month}/@var{day}/@var{year}}. This may
+confuse people who are accustomed to having the month
+and day in the other order; @samp{1/4/96} is January 4,
+not April 1.
+
+Remember to quote the argument to the @samp{-D}
+flag so that your shell doesn't interpret spaces as
+argument separators. A command using the @samp{-D}
+flag can look like this:
+
address@hidden
+$ cvs diff -D "1 hour ago" cvs.texinfo
address@hidden example
+
address@hidden Forcing a tag match
address@hidden -f
+When you specify a particular date or tag to @sc{cvs} commands, they
+normally ignore files that do not contain the tag (or did not
+exist prior to the date) that you specified. Use the @samp{-f} option
+if you want files retrieved even when there is no match for the
+tag or date. (The most recent revision of the file
+will be used).
+
+Note that even with @samp{-f}, a tag that you specify
+must exist (that is, in some file, not necessary in
+every file). This is so that @sc{cvs} will continue to
+give an error if you mistype a tag name.
+
address@hidden 800
address@hidden is available with these commands:
address@hidden, @code{checkout}, @code{export},
address@hidden, @code{rtag}, and @code{update}.
+
address@hidden: The @code{commit} and @code{remove}
+commands also have a
address@hidden option, but it has a different behavior for
+those commands. See @ref{commit options}, and
address@hidden files}.}
+
address@hidden -k @var{kflag}
+Override the default processing of RCS keywords other than
address@hidden @xref{Keyword substitution}, for the meaning of
address@hidden Used with the @code{checkout} and @code{update}
+commands, your @var{kflag} specification is
address@hidden; that is, when you use this option
+with a @code{checkout} or @code{update} command,
address@hidden associates your selected @var{kflag} with any files
+it operates on, and continues to use that @var{kflag} with future
+commands on the same files until you specify otherwise.
+
+The @samp{-k} option is available with the @code{add},
address@hidden, @code{diff}, @code{export}, @code{import} and
address@hidden commands.
+
address@hidden: Prior to CVS version 1.12.2, the @samp{-k} flag
+overrode the @samp{-kb} indication for a binary file. This could
+sometimes corrupt binary files. @xref{Merging and keywords}, for
+more.}
+
address@hidden -l
+Local; run only in current working directory, rather than
+recursing through subdirectories.
+
+Available with the following commands: @code{annotate}, @code{checkout},
address@hidden, @code{diff}, @code{edit}, @code{editors}, @code{export},
address@hidden, @code{rdiff}, @code{remove}, @code{rtag},
address@hidden, @code{tag}, @code{unedit}, @code{update}, @code{watch},
+and @code{watchers}.
+
address@hidden Editor, avoiding invocation of
address@hidden Avoiding editor invocation
address@hidden -m @var{message}
+Use @var{message} as log information, instead of
+invoking an editor.
+
+Available with the following commands: @code{add},
address@hidden and @code{import}.
+
address@hidden -n
+Do not run any tag program. (A program can be
+specified to run in the modules
+database (@pxref{modules}); this option bypasses it).
+
address@hidden: this is not the same as the @samp{cvs -n}
+program option, which you can specify to the left of a cvs command!}
+
+Available with the @code{checkout}, @code{commit}, @code{export},
+and @code{rtag} commands.
+
address@hidden -P
+Prune empty directories. See @ref{Removing directories}.
+
address@hidden -p
+Pipe the files retrieved from the repository to standard output,
+rather than writing them in the current directory. Available
+with the @code{checkout} and @code{update} commands.
+
address@hidden -R
+Process directories recursively. This is on by default.
+
+Available with the following commands: @code{annotate}, @code{checkout},
address@hidden, @code{diff}, @code{edit}, @code{editors}, @code{export},
address@hidden, @code{remove}, @code{rtag},
address@hidden, @code{tag}, @code{unedit}, @code{update}, @code{watch},
+and @code{watchers}.
+
address@hidden -r @var{tag}
address@hidden HEAD, special tag
address@hidden BASE, special tag
+Use the revision specified by the @var{tag} argument instead of the
+default @dfn{head} revision. As well as arbitrary tags defined
+with the @code{tag} or @code{rtag} command, two special tags are
+always available: @samp{HEAD} refers to the most recent version
+available in the repository, and @samp{BASE} refers to the
+revision you last checked out into the current working directory.
+
address@hidden FIXME: What does HEAD really mean? I believe that
address@hidden the current answer is the head of the default branch
address@hidden for all cvs commands except diff. For diff, it
address@hidden seems to be (a) the head of the trunk (or the default
address@hidden branch?) if there is no sticky tag, (b) the head of the
address@hidden branch for the sticky tag, if there is a sticky tag.
address@hidden (b) is ugly as it differs
address@hidden from what HEAD means for other commands, but people
address@hidden and/or scripts are quite possibly used to it.
address@hidden See "head" tests in sanity.sh.
address@hidden Probably the best fix is to introduce two new
address@hidden special tags, ".thead" for the head of the trunk,
address@hidden and ".bhead" for the head of the current branch.
address@hidden Then deprecate HEAD. This has the advantage of
address@hidden not surprising people with a change to HEAD, and a
address@hidden side benefit of also phasing out the poorly-named
address@hidden HEAD (see discussion of reserved tag names in node
address@hidden "Tags"). Of course, .thead and .bhead should be
address@hidden carefully implemented (with the implementation the
address@hidden same for "diff" as for everyone else), test cases
address@hidden written (similar to the ones in "head"), new tests
address@hidden cases written for things like default branches, &c.
+
+The tag specification is sticky when you use this
address@hidden option
+with @code{checkout} or @code{update} to make your own
+copy of a file: @sc{cvs} remembers the tag and continues to use it on
+future update commands, until you specify otherwise (for more information
+on sticky tags/dates, @pxref{Sticky tags}).
+
+The tag can be either a symbolic or numeric tag, as
+described in @ref{Tags}, or the name of a branch, as
+described in @ref{Branching and merging}.
+
+Specifying the @samp{-q} global option along with the
address@hidden command option is often useful, to suppress
+the warning messages when the @sc{rcs} file
+does not contain the specified tag.
+
address@hidden: this is not the same as the overall @samp{cvs -r} option,
+which you can specify to the left of a @sc{cvs} command!}
+
address@hidden is available with the @code{checkout}, @code{commit},
address@hidden, @code{history}, @code{export}, @code{rdiff},
address@hidden, and @code{update} commands.
+
address@hidden -W
+Specify file names that should be filtered. You can
+use this option repeatedly. The spec can be a file
+name pattern of the same type that you can specify in
+the @file{.cvswrappers} file.
+Available with the following commands: @code{import},
+and @code{update}.
+
address@hidden table
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden admin
address@hidden admin---Administration
address@hidden Admin (subcommand)
+
address@hidden @bullet
address@hidden
+Requires: repository, working directory.
address@hidden
+Changes: repository.
address@hidden
+Synonym: rcs
address@hidden itemize
+
+This is the @sc{cvs} interface to assorted
+administrative facilities. Some of them have
+questionable usefulness for @sc{cvs} but exist for
+historical purposes. Some of the questionable options
+are likely to disappear in the future. This command
address@hidden work recursively, so extreme care should be
+used.
+
address@hidden cvsadmin
address@hidden UserAdminOptions, in CVSROOT/config
+On unix, if there is a group named @code{cvsadmin},
+only members of that group can run @code{cvs admin}
+commands, except for those specified using the
address@hidden configuration option in the
address@hidden/config} file. Options specified using
address@hidden can be run by any user. See
address@hidden for more on @code{UserAdminOptions}.
+
+The @code{cvsadmin} group should exist on the server,
+or any system running the non-client/server @sc{cvs}.
+To disallow @code{cvs admin} for all users, create a
+group with no users in it. On NT, the @code{cvsadmin}
+feature does not exist and all users
+can run @code{cvs admin}.
+
address@hidden
+* admin options:: admin options
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden admin options
address@hidden admin options
+
+Some of these options have questionable usefulness for
address@hidden but exist for historical purposes. Some even
+make it impossible to use @sc{cvs} until you undo the
+effect!
+
address@hidden @code
address@hidden address@hidden
+Might not work together with @sc{cvs}. Append the
+access list of @var{oldfile} to the access list of the
address@hidden file.
+
address@hidden address@hidden
+Might not work together with @sc{cvs}. Append the
+login names appearing in the comma-separated list
address@hidden to the access list of the @sc{rcs} file.
+
address@hidden address@hidden
+Set the default branch to @var{rev}. In @sc{cvs}, you
+normally do not manipulate default branches; sticky
+tags (@pxref{Sticky tags}) are a better way to decide
+which branch you want to work on. There is one reason
+to run @code{cvs admin -b}: to revert to the vendor's
+version when using vendor branches (@pxref{Reverting
+local changes}).
+There can be no space between @samp{-b} and its argument.
address@hidden Hmm, we don't document the usage where rev is
address@hidden omitted. Maybe that usage can/should be deprecated
address@hidden (and replaced with -bHEAD or something?) (so we can toss
address@hidden the optional argument). Note that -bHEAD does not
address@hidden work, as of 17 Sep 1997, but probably will once "cvs
address@hidden admin" is internal to CVS.
+
address@hidden Comment leader
address@hidden address@hidden
+Sets the comment leader to @var{string}. The comment
+leader is not used by current versions of @sc{cvs} or
address@hidden 5.7. Therefore, you can almost surely not
+worry about it. @xref{Keyword substitution}.
+
address@hidden address@hidden
+Might not work together with @sc{cvs}. Erase the login
+names appearing in the comma-separated list
address@hidden from the access list of the RCS file. If
address@hidden is omitted, erase the entire access list.
+There can be no space between @samp{-e} and its argument.
+
address@hidden -I
+Run interactively, even if the standard input is not a
+terminal. This option does not work with the
+client/server @sc{cvs} and is likely to disappear in
+a future release of @sc{cvs}.
+
address@hidden -i
+Useless with @sc{cvs}. This creates and initializes a
+new @sc{rcs} file, without depositing a revision. With
address@hidden, add files with the @code{cvs add} command
+(@pxref{Adding files}).
+
address@hidden address@hidden
+Set the default keyword
+substitution to @var{subst}. @xref{Keyword
+substitution}. Giving an explicit @samp{-k} option to
address@hidden update}, @code{cvs export}, or @code{cvs
+checkout} overrides this default.
+
address@hidden address@hidden
+Lock the revision with number @var{rev}. If a branch
+is given, lock the latest revision on that branch. If
address@hidden is omitted, lock the latest revision on the
+default branch. There can be no space between
address@hidden and its argument.
+
+This can be used in conjunction with the
address@hidden script in the @file{contrib}
+directory of the @sc{cvs} source distribution to
+provide reserved checkouts (where only one user can be
+editing a given file at a time). See the comments in
+that file for details (and see the @file{README} file
+in that directory for disclaimers about the unsupported
+nature of contrib). According to comments in that
+file, locking must set to strict (which is the default).
+
address@hidden -L
+Set locking to strict. Strict locking means that the
+owner of an RCS file is not exempt from locking for
+checkin. For use with @sc{cvs}, strict locking must be
+set; see the discussion under the @samp{-l} option above.
+
address@hidden Changing a log message
address@hidden Replacing a log message
address@hidden Correcting a log message
address@hidden Fixing a log message
address@hidden Log message, correcting
address@hidden address@hidden:@var{msg}
+Replace the log message of revision @var{rev} with
address@hidden
+
address@hidden The rcs -M option, to suppress sending mail, has never been
address@hidden documented as a cvs admin option.
+
address@hidden address@hidden:address@hidden
+Act like @samp{-n}, except override any previous
+assignment of @var{name}. For use with magic branches,
+see @ref{Magic branch numbers}.
+
address@hidden address@hidden:address@hidden
+Associate the symbolic name @var{name} with the branch
+or revision @var{rev}. It is normally better to use
address@hidden tag} or @samp{cvs rtag} instead. Delete the
+symbolic name if both @samp{:} and @var{rev} are
+omitted; otherwise, print an error message if
address@hidden is already associated with another number.
+If @var{rev} is symbolic, it is expanded before
+association. A @var{rev} consisting of a branch number
+followed by a @samp{.} stands for the current latest
+revision in the branch. A @samp{:} with an empty
address@hidden stands for the current latest revision on the
+default branch, normally the trunk. For example,
address@hidden admin address@hidden:} associates @var{name} with the
+current latest revision of all the RCS files;
+this contrasts with @samp{cvs admin address@hidden:$} which
+associates @var{name} with the revision numbers
+extracted from keyword strings in the corresponding
+working files.
+
address@hidden Deleting revisions
address@hidden Outdating revisions
address@hidden Saving space
address@hidden address@hidden
+Deletes (@dfn{outdates}) the revisions given by
address@hidden
+
+Note that this command can be quite dangerous unless
+you know @emph{exactly} what you are doing (for example
+see the warnings below about how the
address@hidden:@var{rev2} syntax is confusing).
+
+If you are short on disc this option might help you.
+But think twice before using it---there is no way short
+of restoring the latest backup to undo this command!
+If you delete different revisions than you planned,
+either due to carelessness or (heaven forbid) a @sc{cvs}
+bug, there is no opportunity to correct the error
+before the revisions are deleted. It probably would be
+a good idea to experiment on a copy of the repository
+first.
+
+Specify @var{range} in one of the following ways:
+
address@hidden @code
address@hidden @var{rev1}::@var{rev2}
+Collapse all revisions between rev1 and rev2, so that
address@hidden only stores the differences associated with going
+from rev1 to rev2, not intermediate steps. For
+example, after @samp{-o 1.3::1.5} one can retrieve
+revision 1.3, revision 1.5, or the differences to get
+from 1.3 to 1.5, but not the revision 1.4, or the
+differences between 1.3 and 1.4. Other examples:
address@hidden 1.3::1.4} and @samp{-o 1.3::1.3} have no
+effect, because there are no intermediate revisions to
+remove.
+
address@hidden ::@var{rev}
+Collapse revisions between the beginning of the branch
+containing @var{rev} and @var{rev} itself. The
+branchpoint and @var{rev} are left intact. For
+example, @samp{-o ::1.3.2.6} deletes revision 1.3.2.1,
+revision 1.3.2.5, and everything in between, but leaves
+1.3 and 1.3.2.6 intact.
+
address@hidden @var{rev}::
+Collapse revisions between @var{rev} and the end of the
+branch containing @var{rev}. Revision @var{rev} is
+left intact but the head revision is deleted.
+
address@hidden @var{rev}
+Delete the revision @var{rev}. For example, @samp{-o
+1.3} is equivalent to @samp{-o 1.2::1.4}.
+
address@hidden @var{rev1}:@var{rev2}
+Delete the revisions from @var{rev1} to @var{rev2},
+inclusive, on the same branch. One will not be able to
+retrieve @var{rev1} or @var{rev2} or any of the
+revisions in between. For example, the command
address@hidden admin -oR_1_01:R_1_02 .} is rarely useful.
+It means to delete revisions up to, and including, the
+tag R_1_02. But beware! If there are files that have not
+changed between R_1_02 and R_1_03 the file will have
address@hidden same} numerical revision number assigned to
+the tags R_1_02 and R_1_03. So not only will it be
+impossible to retrieve R_1_02; R_1_03 will also have to
+be restored from the tapes! In most cases you want to
+specify @var{rev1}::@var{rev2} instead.
+
address@hidden :@var{rev}
+Delete revisions from the beginning of the
+branch containing @var{rev} up to and including
address@hidden
+
address@hidden @var{rev}:
+Delete revisions from revision @var{rev}, including
address@hidden itself, to the end of the branch containing
address@hidden
address@hidden table
+
+None of the revisions to be deleted may have
+branches or locks.
+
+If any of the revisions to be deleted have symbolic
+names, and one specifies one of the @samp{::} syntaxes,
+then @sc{cvs} will give an error and not delete any
+revisions. If you really want to delete both the
+symbolic names and the revisions, first delete the
+symbolic names with @code{cvs tag -d}, then run
address@hidden admin -o}. If one specifies the
address@hidden::} syntaxes, then @sc{cvs} will delete the
+revisions but leave the symbolic names pointing to
+nonexistent revisions. This behavior is preserved for
+compatibility with previous versions of @sc{cvs}, but
+because it isn't very useful, in the future it may
+change to be like the @samp{::} case.
+
+Due to the way @sc{cvs} handles branches @var{rev}
+cannot be specified symbolically if it is a branch.
address@hidden branch numbers}, for an explanation.
address@hidden FIXME: is this still true? I suspect not.
+
+Make sure that no-one has checked out a copy of the
+revision you outdate. Strange things will happen if he
+starts to edit it and tries to check it back in. For
+this reason, this option is not a good way to take back
+a bogus commit; commit a new revision undoing the bogus
+change instead (@pxref{Merging two revisions}).
+
address@hidden -q
+Run quietly; do not print diagnostics.
+
address@hidden address@hidden:@var{rev}]
+Useful with @sc{cvs}. Set the state attribute of the
+revision @var{rev} to @var{state}. If @var{rev} is a
+branch number, assume the latest revision on that
+branch. If @var{rev} is omitted, assume the latest
+revision on the default branch. Any identifier is
+acceptable for @var{state}. A useful set of states is
address@hidden (for experimental), @samp{Stab} (for
+stable), and @samp{Rel} (for released). By default,
+the state of a new revision is set to @samp{Exp} when
+it is created. The state is visible in the output from
address@hidden log} (@pxref{log}), and in the
address@hidden@i{}Log$} and @address@hidden keywords
+(@pxref{Keyword substitution}). Note that @sc{cvs}
+uses the @code{dead} state for its own purposes; to
+take a file to or from the @code{dead} state use
+commands like @code{cvs remove} and @code{cvs add}, not
address@hidden admin -s}.
+
address@hidden address@hidden
+Useful with @sc{cvs}. Write descriptive text from the
+contents of the named @var{file} into the RCS file,
+deleting the existing text. The @var{file} pathname
+may not begin with @samp{-}. The descriptive text can be seen in the
+output from @samp{cvs log} (@pxref{log}).
+There can be no space between @samp{-t} and its argument.
+
+If @var{file} is omitted,
+obtain the text from standard input, terminated by
+end-of-file or by a line containing @samp{.} by itself.
+Prompt for the text if interaction is possible; see
address@hidden
+
address@hidden address@hidden
+Similar to @address@hidden Write descriptive text
+from the @var{string} into the @sc{rcs} file, deleting
+the existing text.
+There can be no space between @samp{-t} and its argument.
+
address@hidden The rcs -T option, do not update last-mod time for
address@hidden minor changes, has never been documented as a
address@hidden cvs admin option.
+
address@hidden -U
+Set locking to non-strict. Non-strict locking means
+that the owner of a file need not lock a revision for
+checkin. For use with @sc{cvs}, strict locking must be
+set; see the discussion under the @samp{-l} option
+above.
+
address@hidden address@hidden
+See the option @samp{-l} above, for a discussion of
+using this option with @sc{cvs}. Unlock the revision
+with number @var{rev}. If a branch is given, unlock
+the latest revision on that branch. If @var{rev} is
+omitted, remove the latest lock held by the caller.
+Normally, only the locker of a revision may unlock it;
+somebody else unlocking a revision breaks the lock.
+This causes the original locker to be sent a @code{commit}
+notification (@pxref{Getting Notified}).
+There can be no space between @samp{-u} and its argument.
+
address@hidden address@hidden
+In previous versions of @sc{cvs}, this option meant to
+write an @sc{rcs} file which would be acceptable to
address@hidden version @var{n}, but it is now obsolete and
+specifying it will produce an error.
address@hidden Note that -V without an argument has never been
address@hidden documented as a cvs admin option.
+
address@hidden address@hidden
+In previous versions of @sc{cvs}, this was documented
+as a way of specifying the names of the @sc{rcs}
+files. However, @sc{cvs} has always required that the
address@hidden files used by @sc{cvs} end in @samp{,v}, so
+this option has never done anything useful.
+
address@hidden The rcs -z option, to specify the timezone, has
address@hidden never been documented as a cvs admin option.
address@hidden table
+
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden checkout
address@hidden checkout---Check out sources for editing
address@hidden checkout (subcommand)
address@hidden co (subcommand)
+
address@hidden @bullet
address@hidden
+Synopsis: checkout [options] address@hidden
address@hidden
+Requires: repository.
address@hidden
+Changes: working directory.
address@hidden
+Synonyms: co, get
address@hidden itemize
+
+Create or update a working directory containing copies of the
+source files specified by @var{modules}. You must execute
address@hidden before using most of the other @sc{cvs}
+commands, since most of them operate on your working
+directory.
+
+The @var{modules} are either
+symbolic names for some
+collection of source directories and files, or paths to
+directories or files in the repository. The symbolic
+names are defined in the @samp{modules} file.
address@hidden
address@hidden Needs an example, particularly of the non-"modules"
address@hidden case but probably of both.
+
address@hidden FIXME: this seems like a very odd place to introduce
address@hidden people to how CVS works. The bit about unreserved
address@hidden checkouts is also misleading as it depends on how
address@hidden things are set up.
+Depending on the modules you specify, @code{checkout} may
+recursively create directories and populate them with
+the appropriate source files. You can then edit these
+source files at any time (regardless of whether other
+software developers are editing their own copies of the
+sources); update them to include new changes applied by
+others to the source repository; or commit your work as
+a permanent change to the source repository.
+
+Note that @code{checkout} is used to create
+directories. The top-level directory created is always
+added to the directory where @code{checkout} is
+invoked, and usually has the same name as the specified
+module. In the case of a module alias, the created
+sub-directory may have a different name, but you can be
+sure that it will be a sub-directory, and that
address@hidden will show the relative path leading to
+each file as it is extracted into your private work
+area (unless you specify the @samp{-Q} global option).
+
+The files created by @code{checkout} are created
+read-write, unless the @samp{-r} option to @sc{cvs}
+(@pxref{Global options}) is specified, the
address@hidden environment variable is specified
+(@pxref{Environment variables}), or a watch is in
+effect for that file (@pxref{Watches}).
+
+Note that running @code{checkout} on a directory that was already
+built by a prior @code{checkout} is also permitted.
+This is similar to specifying the @samp{-d} option
+to the @code{update} command in the sense that new
+directories that have been created in the repository
+will appear in your work area.
+However, @code{checkout} takes a module name whereas
address@hidden takes a directory name. Also
+to use @code{checkout} this way it must be run from the
+top level directory (where you originally ran
address@hidden from), so before you run
address@hidden to update an existing directory, don't
+forget to change your directory to the top level
+directory.
+
+For the output produced by the @code{checkout} command
+see @ref{update output}.
+
address@hidden
+* checkout options:: checkout options
+* checkout examples:: checkout examples
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden checkout options
address@hidden checkout options
+
+These standard options are supported by @code{checkout}
+(@pxref{Common options}, for a complete description of
+them):
+
address@hidden @code
address@hidden -D @var{date}
+Use the most recent revision no later than @var{date}.
+This option is sticky, and implies @samp{-P}. See
address@hidden tags}, for more information on sticky tags/dates.
+
address@hidden -f
+Only useful with the @samp{-D @var{date}} or @samp{-r
address@hidden flags. If no matching revision is found,
+retrieve the most recent revision (instead of ignoring
+the file).
+
address@hidden -k @var{kflag}
+Process keywords according to @var{kflag}. See
address@hidden substitution}.
+This option is sticky; future updates of
+this file in this working directory will use the same
address@hidden The @code{status} command can be viewed
+to see the sticky options. See @ref{Invoking CVS}, for
+more information on the @code{status} command.
+
address@hidden -l
+Local; run only in current working directory.
+
address@hidden -n
+Do not run any checkout program (as specified
+with the @samp{-o} option in the modules file;
address@hidden).
+
address@hidden -P
+Prune empty directories. See @ref{Moving directories}.
+
address@hidden -p
+Pipe files to the standard output.
+
address@hidden -R
+Checkout directories recursively. This option is on by default.
+
address@hidden -r @var{tag}
+Use revision @var{tag}. This option is sticky, and implies @samp{-P}.
+See @ref{Sticky tags}, for more information on sticky tags/dates.
address@hidden table
+
+In addition to those, you can use these special command
+options with @code{checkout}:
+
address@hidden @code
address@hidden -A
+Reset any sticky tags, dates, or @samp{-k} options.
+See @ref{Sticky tags}, for more information on sticky tags/dates.
+
address@hidden -c
+Copy the module file, sorted, to the standard output,
+instead of creating or modifying any files or
+directories in your working directory.
+
address@hidden -d @var{dir}
+Create a directory called @var{dir} for the working
+files, instead of using the module name. In general,
+using this flag is equivalent to using @samp{mkdir
address@hidden; cd @var{dir}} followed by the checkout
+command without the @samp{-d} flag.
+
+There is an important exception, however. It is very
+convenient when checking out a single item to have the
+output appear in a directory that doesn't contain empty
+intermediate directories. In this case @emph{only},
address@hidden tries to ``shorten'' pathnames to avoid those empty
+directories.
+
+For example, given a module @samp{foo} that contains
+the file @samp{bar.c}, the command @samp{cvs co -d dir
+foo} will create directory @samp{dir} and place
address@hidden inside. Similarly, given a module
address@hidden which has subdirectory @samp{baz} wherein
+there is a file @samp{quux.c}, the command @samp{cvs co
+-d dir bar/baz} will create directory @samp{dir} and
+place @samp{quux.c} inside.
+
+Using the @samp{-N} flag will defeat this behavior.
+Given the same module definitions above, @samp{cvs co
+-N -d dir foo} will create directories @samp{dir/foo}
+and place @samp{bar.c} inside, while @samp{cvs co -N -d
+dir bar/baz} will create directories @samp{dir/bar/baz}
+and place @samp{quux.c} inside.
+
address@hidden -j @var{tag}
+With two @samp{-j} options, merge changes from the
+revision specified with the first @samp{-j} option to
+the revision specified with the second @samp{j} option,
+into the working directory.
+
+With one @samp{-j} option, merge changes from the
+ancestor revision to the revision specified with the
address@hidden option, into the working directory. The
+ancestor revision is the common ancestor of the
+revision which the working directory is based on, and
+the revision specified in the @samp{-j} option.
+
+In addition, each -j option can contain an optional
+date specification which, when used with branches, can
+limit the chosen revision to one within a specific
+date. An optional date is specified by adding a colon
+(:) to the tag:
address@hidden@var{Symbolic_Tag}:@var{Date_Specifier}}.
+
address@hidden and merging}.
+
address@hidden -N
+Only useful together with @samp{-d @var{dir}}. With
+this option, @sc{cvs} will not ``shorten'' module paths
+in your working directory when you check out a single
+module. See the @samp{-d} flag for examples and a
+discussion.
+
address@hidden -s
+Like @samp{-c}, but include the status of all modules,
+and sort it by the status string. @xref{modules}, for
+info about the @samp{-s} option that is used inside the
+modules file to set the module status.
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden checkout examples
address@hidden checkout examples
+
+Get a copy of the module @samp{tc}:
+
address@hidden
+$ cvs checkout tc
address@hidden example
+
+Get a copy of the module @samp{tc} as it looked one day
+ago:
+
address@hidden
+$ cvs checkout -D yesterday tc
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden commit
address@hidden commit---Check files into the repository
address@hidden commit (subcommand)
+
address@hidden @bullet
address@hidden
+Synopsis: commit [-lnRf] [-m 'log_message' |
+-F file] [-r revision] address@hidden
address@hidden
+Requires: working directory, repository.
address@hidden
+Changes: repository.
address@hidden
+Synonym: ci
address@hidden itemize
+
+Use @code{commit} when you want to incorporate changes
+from your working source files into the source
+repository.
+
+If you don't specify particular files to commit, all of
+the files in your working current directory are
+examined. @code{commit} is careful to change in the
+repository only those files that you have really
+changed. By default (or if you explicitly specify the
address@hidden option), files in subdirectories are also
+examined and committed if they have changed; you can
+use the @samp{-l} option to limit @code{commit} to the
+current directory only.
+
address@hidden verifies that the selected files are up
+to date with the current revisions in the source
+repository; it will notify you, and exit without
+committing, if any of the specified files must be made
+current first with @code{update} (@pxref{update}).
address@hidden does not call the @code{update} command
+for you, but rather leaves that for you to do when the
+time is right.
+
+When all is well, an editor is invoked to allow you to
+enter a log message that will be written to one or more
+logging programs (@pxref{modules}, and @pxref{loginfo})
+and placed in the @sc{rcs} file inside the
+repository. This log message can be retrieved with the
address@hidden command; see @ref{log}. You can specify the
+log message on the command line with the @samp{-m
address@hidden option, and thus avoid the editor invocation,
+or use the @samp{-F @var{file}} option to specify
+that the argument file contains the log message.
+
address@hidden
+* commit options:: commit options
+* commit examples:: commit examples
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden commit options
address@hidden commit options
+
+These standard options are supported by @code{commit}
+(@pxref{Common options}, for a complete description of
+them):
+
address@hidden @code
address@hidden -l
+Local; run only in current working directory.
+
address@hidden -R
+Commit directories recursively. This is on by default.
+
address@hidden -r @var{revision}
+Commit to @var{revision}. @var{revision} must be
+either a branch, or a revision on the main trunk that
+is higher than any existing revision number
+(@pxref{Assigning revisions}). You
+cannot commit to a specific revision on a branch.
address@hidden FIXME: Need xref for branch case.
address@hidden table
+
address@hidden also supports these options:
+
address@hidden @code
address@hidden -F @var{file}
+Read the log message from @var{file}, instead
+of invoking an editor.
+
address@hidden -f
+Note that this is not the standard behavior of
+the @samp{-f} option as defined in @ref{Common options}.
+
+Force @sc{cvs} to commit a new revision even if you haven't
+made any changes to the file. If the current revision
+of @var{file} is 1.7, then the following two commands
+are equivalent:
+
address@hidden
+$ cvs commit -f @var{file}
+$ cvs commit -r 1.8 @var{file}
address@hidden example
+
address@hidden This is odd, but it's how CVS has worked for some
address@hidden time.
+The @samp{-f} option disables recursion (i.e., it
+implies @samp{-l}). To force @sc{cvs} to commit a new
+revision for all files in all subdirectories, you must
+use @samp{-f -R}.
+
address@hidden -m @var{message}
+Use @var{message} as the log message, instead of
+invoking an editor.
address@hidden table
+
address@hidden 2000
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden commit examples
address@hidden commit examples
+
address@hidden FIXME: this material wants to be somewhere
address@hidden in "Branching and merging".
+
address@hidden Committing to a branch
+
+You can commit to a branch revision (one that has an
+even number of dots) with the @samp{-r} option. To
+create a branch revision, use the @samp{-b} option
+of the @code{rtag} or @code{tag} commands
+(@pxref{Branching and merging}). Then, either @code{checkout} or
address@hidden can be used to base your sources on the
+newly created branch. From that point on, all
address@hidden changes made within these working sources
+will be automatically added to a branch revision,
+thereby not disturbing main-line development in any
+way. For example, if you had to create a patch to the
+1.2 version of the product, even though the 2.0 version
+is already under development, you might do:
+
address@hidden
+$ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module
+$ cvs checkout -r FCS1_2_Patch product_module
+$ cd product_module
+[[ hack away ]]
+$ cvs commit
address@hidden example
+
address@hidden
+This works automatically since the @samp{-r} option is
+sticky.
+
address@hidden Creating the branch after editing
+
+Say you have been working on some extremely
+experimental software, based on whatever revision you
+happened to checkout last week. If others in your
+group would like to work on this software with you, but
+without disturbing main-line development, you could
+commit your change to a new branch. Others can then
+checkout your experimental stuff and utilize the full
+benefit of @sc{cvs} conflict resolution. The scenario might
+look like:
+
address@hidden FIXME: Should we be recommending tagging the branchpoint?
address@hidden
+[[ hacked sources are present ]]
+$ cvs tag -b EXPR1
+$ cvs update -r EXPR1
+$ cvs commit
address@hidden example
+
+The @code{update} command will make the @samp{-r
+EXPR1} option sticky on all files. Note that your
+changes to the files will never be removed by the
address@hidden command. The @code{commit} will
+automatically commit to the correct branch, because the
address@hidden is sticky. You could also do like this:
+
address@hidden FIXME: Should we be recommending tagging the branchpoint?
address@hidden
+[[ hacked sources are present ]]
+$ cvs tag -b EXPR1
+$ cvs commit -r EXPR1
address@hidden example
+
address@hidden
+but then, only those files that were changed by you
+will have the @samp{-r EXPR1} sticky flag. If you hack
+away, and commit without specifying the @samp{-r EXPR1}
+flag, some files may accidentally end up on the main
+trunk.
+
+To work with you on the experimental change, others
+would simply do
+
address@hidden
+$ cvs checkout -r EXPR1 whatever_module
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden diff
address@hidden diff---Show differences between revisions
address@hidden diff (subcommand)
+
address@hidden @bullet
address@hidden
+Synopsis: diff [-lR] [-k kflag] [format_options] [[-r rev1 | -D date1] [-r
rev2 | -D date2]] address@hidden
address@hidden
+Requires: working directory, repository.
address@hidden
+Changes: nothing.
address@hidden itemize
+
+The @code{diff} command is used to compare different
+revisions of files. The default action is to compare
+your working files with the revisions they were based
+on, and report any differences that are found.
+
+If any file names are given, only those files are
+compared. If any directories are given, all files
+under them will be compared.
+
+The exit status for diff is different than for other
address@hidden commands; for details @ref{Exit status}.
+
address@hidden
+* diff options:: diff options
+* diff examples:: diff examples
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden diff options
address@hidden diff options
+
+These standard options are supported by @code{diff}
+(@pxref{Common options}, for a complete description of
+them):
+
address@hidden @code
address@hidden -D @var{date}
+Use the most recent revision no later than @var{date}.
+See @samp{-r} for how this affects the comparison.
+
address@hidden -k @var{kflag}
+Process keywords according to @var{kflag}. See
address@hidden substitution}.
+
address@hidden -l
+Local; run only in current working directory.
+
address@hidden -R
+Examine directories recursively. This option is on by
+default.
+
address@hidden -r @var{tag}
+Compare with revision @var{tag}. Zero, one or two
address@hidden options can be present. With no @samp{-r}
+option, the working file will be compared with the
+revision it was based on. With one @samp{-r}, that
+revision will be compared to your current working file.
+With two @samp{-r} options those two revisions will be
+compared (and your working file will not affect the
+outcome in any way).
address@hidden We should be a lot more explicit, with examples,
address@hidden about the difference between "cvs diff" and "cvs
address@hidden diff -r HEAD". This often confuses new users.
+
+One or both @samp{-r} options can be replaced by a
address@hidden @var{date}} option, described above.
address@hidden table
+
address@hidden Conceptually, this is a disaster. There are 3
address@hidden zillion diff formats that we support via the diff
address@hidden library. It is not obvious to me that we should
address@hidden document them all. Maybe just the most common ones
address@hidden like -c and -u, and think about phasing out the
address@hidden obscure ones.
address@hidden FIXCVS: also should be a way to specify an external
address@hidden diff program (which can be different for different
address@hidden file types) and pass through
address@hidden arbitrary options, so that the user can do
address@hidden "--pass=-Z --pass=foo" or something even if CVS
address@hidden doesn't know about the "-Z foo" option to diff.
address@hidden This would fit nicely with deprecating/eliminating
address@hidden the obscure options of the diff library, because it
address@hidden would let people specify an external GNU diff if
address@hidden they are into that sort of thing.
+The following options specify the format of the
+output. They have the same meaning as in GNU diff.
+Most options have two equivalent names, one of which is a single letter
+preceded by @samp{-}, and the other of which is a long name preceded by
address@hidden
+
address@hidden @samp
address@hidden address@hidden
+Show @var{lines} (an integer) lines of context. This option does not
+specify an output format by itself; it has no effect unless it is
+combined with @samp{-c} or @samp{-u}. This option is obsolete. For proper
+operation, @code{patch} typically needs at least two lines of context.
+
address@hidden -a
+Treat all files as text and compare them line-by-line, even if they
+do not seem to be text.
+
address@hidden -b
+Ignore trailing white space and consider all other sequences of one or
+more white space characters to be equivalent.
+
address@hidden -B
+Ignore changes that just insert or delete blank lines.
+
address@hidden --binary
+Read and write data in binary mode.
+
address@hidden --brief
+Report only whether the files differ, not the details of the
+differences.
+
address@hidden -c
+Use the context output format.
+
address@hidden -C @var{lines}
address@hidden address@hidden@address@hidden
+Use the context output format, showing @var{lines} (an integer) lines of
+context, or three if @var{lines} is not given.
+For proper operation, @code{patch} typically needs at least two lines of
+context.
+
address@hidden address@hidden
+Use @var{format} to output a line group containing differing lines from
+both files in if-then-else format. @xref{Line group formats}.
+
address@hidden -d
+Change the algorithm to perhaps find a smaller set of changes. This makes
address@hidden slower (sometimes much slower).
+
address@hidden -e
address@hidden --ed
+Make output that is a valid @code{ed} script.
+
address@hidden --expand-tabs
+Expand tabs to spaces in the output, to preserve the alignment of tabs
+in the input files.
+
address@hidden -f
+Make output that looks vaguely like an @code{ed} script but has changes
+in the order they appear in the file.
+
address@hidden -F @var{regexp}
+In context and unified format, for each hunk of differences, show some
+of the last preceding line that matches @var{regexp}.
+
address@hidden --forward-ed
+Make output that looks vaguely like an @code{ed} script but has changes
+in the order they appear in the file.
+
address@hidden -H
+Use heuristics to speed handling of large files that have numerous
+scattered small changes.
+
address@hidden address@hidden
+Do not discard the last @var{lines} lines of the common prefix
+and the first @var{lines} lines of the common suffix.
+
address@hidden -i
+Ignore changes in case; consider upper- and lower-case letters
+equivalent.
+
address@hidden -I @var{regexp}
+Ignore changes that just insert or delete lines that match @var{regexp}.
+
address@hidden address@hidden
+Make merged if-then-else output using @var{name}.
+
address@hidden --ignore-all-space
+Ignore white space when comparing lines.
+
address@hidden --ignore-blank-lines
+Ignore changes that just insert or delete blank lines.
+
address@hidden --ignore-case
+Ignore changes in case; consider upper- and lower-case to be the same.
+
address@hidden address@hidden
+Ignore changes that just insert or delete lines that match @var{regexp}.
+
address@hidden --ignore-space-change
+Ignore trailing white space and consider all other sequences of one or
+more white space characters to be equivalent.
+
address@hidden --initial-tab
+Output a tab rather than a space before the text of a line in normal or
+context format. This causes the alignment of tabs in the line to look
+normal.
+
address@hidden -L @var{label}
+Use @var{label} instead of the file name in the context format
+and unified format headers.
+
address@hidden address@hidden
+Use @var{label} instead of the file name in the context format
+and unified format headers.
+
address@hidden --left-column
+Print only the left column of two common lines in side by side format.
+
address@hidden address@hidden
+Use @var{format} to output all input lines in if-then-else format.
address@hidden formats}.
+
address@hidden --minimal
+Change the algorithm to perhaps find a smaller set of changes. This
+makes @code{diff} slower (sometimes much slower).
+
address@hidden -n
+Output RCS-format diffs; like @samp{-f} except that each command
+specifies the number of lines affected.
+
address@hidden -N
address@hidden --new-file
+In directory comparison, if a file is found in only one directory,
+treat it as present but empty in the other directory.
+
address@hidden address@hidden
+Use @var{format} to output a group of lines taken from just the second
+file in if-then-else format. @xref{Line group formats}.
+
address@hidden address@hidden
+Use @var{format} to output a line taken from just the second file in
+if-then-else format. @xref{Line formats}.
+
address@hidden address@hidden
+Use @var{format} to output a group of lines taken from just the first
+file in if-then-else format. @xref{Line group formats}.
+
address@hidden address@hidden
+Use @var{format} to output a line taken from just the first file in
+if-then-else format. @xref{Line formats}.
+
address@hidden -p
+Show which C function each change is in.
+
address@hidden --rcs
+Output RCS-format diffs; like @samp{-f} except that each command
+specifies the number of lines affected.
+
address@hidden --report-identical-files
address@hidden -s
+Report when two files are the same.
+
address@hidden --show-c-function
+Show which C function each change is in.
+
address@hidden address@hidden
+In context and unified format, for each hunk of differences, show some
+of the last preceding line that matches @var{regexp}.
+
address@hidden --side-by-side
+Use the side by side output format.
+
address@hidden --speed-large-files
+Use heuristics to speed handling of large files that have numerous
+scattered small changes.
+
address@hidden --suppress-common-lines
+Do not print common lines in side by side format.
+
address@hidden -t
+Expand tabs to spaces in the output, to preserve the alignment of tabs
+in the input files.
+
address@hidden -T
+Output a tab rather than a space before the text of a line in normal or
+context format. This causes the alignment of tabs in the line to look
+normal.
+
address@hidden --text
+Treat all files as text and compare them line-by-line, even if they
+do not appear to be text.
+
address@hidden -u
+Use the unified output format.
+
address@hidden address@hidden
+Use @var{format} to output a group of common lines taken from both files
+in if-then-else format. @xref{Line group formats}.
+
address@hidden address@hidden
+Use @var{format} to output a line common to both files in if-then-else
+format. @xref{Line formats}.
+
address@hidden -U @var{lines}
address@hidden address@hidden@address@hidden
+Use the unified output format, showing @var{lines} (an integer) lines of
+context, or three if @var{lines} is not given.
+For proper operation, @code{patch} typically needs at least two lines of
+context.
+
address@hidden -w
+Ignore white space when comparing lines.
+
address@hidden -W @var{columns}
address@hidden address@hidden
+Use an output width of @var{columns} in side by side format.
+
address@hidden -y
+Use the side by side output format.
address@hidden table
+
address@hidden
+* Line group formats:: Line group formats
+* Line formats:: Line formats
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden Line group formats
address@hidden Line group formats
+
+Line group formats let you specify formats suitable for many
+applications that allow if-then-else input, including programming
+languages and text formatting languages. A line group format specifies
+the output format for a contiguous group of similar lines.
+
+For example, the following command compares the TeX file @file{myfile}
+with the original version from the repository,
+and outputs a merged file in which old regions are
+surrounded by @address@hidden@address@hidden@address@hidden lines, and new
+regions are surrounded by @address@hidden@address@hidden@address@hidden lines.
+
address@hidden
+cvs diff \
+ --old-group-format='address@hidden@}
+%<address@hidden@}
+' \
+ --new-group-format='address@hidden@}
+%>address@hidden@}
+' \
+ myfile
address@hidden example
+
+The following command is equivalent to the above example, but it is a
+little more verbose, because it spells out the default line group formats.
+
address@hidden
+cvs diff \
+ --old-group-format='address@hidden@}
+%<address@hidden@}
+' \
+ --new-group-format='address@hidden@}
+%>address@hidden@}
+' \
+ --unchanged-group-format='%=' \
+ --changed-group-format='address@hidden@}
+%<address@hidden@}
address@hidden@}
+%>address@hidden@}
+' \
+ myfile
address@hidden example
+
+Here is a more advanced example, which outputs a diff listing with
+headers containing line numbers in a ``plain English'' style.
+
address@hidden
+cvs diff \
+ --unchanged-group-format='' \
+ --old-group-format='-------- %dn line%(n=1?:s) deleted at %df:
+%<' \
+ --new-group-format='-------- %dN line%(N=1?:s) added after %de:
+%>' \
+ --changed-group-format='-------- %dn line%(n=1?:s) changed at %df:
+%<-------- to:
+%>' \
+ myfile
address@hidden example
+
+To specify a line group format, use one of the options
+listed below. You can specify up to four line group formats, one for
+each kind of line group. You should quote @var{format}, because it
+typically contains shell metacharacters.
+
address@hidden @samp
address@hidden address@hidden
+These line groups are hunks containing only lines from the first file.
+The default old group format is the same as the changed group format if
+it is specified; otherwise it is a format that outputs the line group as-is.
+
address@hidden address@hidden
+These line groups are hunks containing only lines from the second
+file. The default new group format is same as the changed group
+format if it is specified; otherwise it is a format that outputs the
+line group as-is.
+
address@hidden address@hidden
+These line groups are hunks containing lines from both files. The
+default changed group format is the concatenation of the old and new
+group formats.
+
address@hidden address@hidden
+These line groups contain lines common to both files. The default
+unchanged group format is a format that outputs the line group as-is.
address@hidden table
+
+In a line group format, ordinary characters represent themselves;
+conversion specifications start with @samp{%} and have one of the
+following forms.
+
address@hidden @samp
address@hidden %<
+stands for the lines from the first file, including the trailing newline.
+Each line is formatted according to the old line format (@pxref{Line formats}).
+
address@hidden %>
+stands for the lines from the second file, including the trailing newline.
+Each line is formatted according to the new line format.
+
address@hidden %=
+stands for the lines common to both files, including the trailing newline.
+Each line is formatted according to the unchanged line format.
+
address@hidden %%
+stands for @samp{%}.
+
address@hidden %c'@var{C}'
+where @var{C} is a single character, stands for @var{C}.
address@hidden may not be a backslash or an apostrophe.
+For example, @samp{%c':'} stands for a colon, even inside
+the then-part of an if-then-else format, which a colon would
+normally terminate.
+
address@hidden %c'address@hidden'
+where @var{O} is a string of 1, 2, or 3 octal digits,
+stands for the character with octal code @var{O}.
+For example, @samp{%c'\0'} stands for a null character.
+
address@hidden @address@hidden
+where @var{F} is a @code{printf} conversion specification and @var{n} is one
+of the following letters, stands for @var{n}'s value formatted with @var{F}.
+
address@hidden @samp
address@hidden e
+The line number of the line just before the group in the old file.
+
address@hidden f
+The line number of the first line in the group in the old file;
+equals @var{e} + 1.
+
address@hidden l
+The line number of the last line in the group in the old file.
+
address@hidden m
+The line number of the line just after the group in the old file;
+equals @var{l} + 1.
+
address@hidden n
+The number of lines in the group in the old file; equals @var{l} - @var{f} + 1.
+
address@hidden E, F, L, M, N
+Likewise, for lines in the new file.
+
address@hidden table
+
+The @code{printf} conversion specification can be @samp{%d},
address@hidden, @samp{%x}, or @samp{%X}, specifying decimal, octal,
+lower case hexadecimal, or upper case hexadecimal output
+respectively. After the @samp{%} the following options can appear in
+sequence: a @samp{-} specifying left-justification; an integer
+specifying the minimum field width; and a period followed by an
+optional integer specifying the minimum number of digits.
+For example, @samp{%5dN} prints the number of new lines in the group
+in a field of width 5 characters, using the @code{printf} format @code{"%5d"}.
+
address@hidden (@address@hidden@var{T}:@var{E})
+If @var{A} equals @var{B} then @var{T} else @var{E}.
address@hidden and @var{B} are each either a decimal constant
+or a single letter interpreted as above.
+This format spec is equivalent to @var{T} if
address@hidden's value equals @var{B}'s; otherwise it is equivalent to @var{E}.
+
+For example, @samp{%(N=0?no:%dN) line%(N=1?:s)} is equivalent to
address@hidden lines} if @var{N} (the number of lines in the group in the
+new file) is 0, to @samp{1 line} if @var{N} is 1, and to @samp{%dN lines}
+otherwise.
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden Line formats
address@hidden Line formats
+
+Line formats control how each line taken from an input file is
+output as part of a line group in if-then-else format.
+
+For example, the following command outputs text with a one-column
+change indicator to the left of the text. The first column of output
+is @samp{-} for deleted lines, @samp{|} for added lines, and a space
+for unchanged lines. The formats contain newline characters where
+newlines are desired on output.
+
address@hidden
+cvs diff \
+ --old-line-format='-%l
+' \
+ --new-line-format='|%l
+' \
+ --unchanged-line-format=' %l
+' \
+ myfile
address@hidden example
+
+To specify a line format, use one of the following options. You should
+quote @var{format}, since it often contains shell metacharacters.
+
address@hidden @samp
address@hidden address@hidden
+formats lines just from the first file.
+
address@hidden address@hidden
+formats lines just from the second file.
+
address@hidden address@hidden
+formats lines common to both files.
+
address@hidden address@hidden
+formats all lines; in effect, it sets all three above options simultaneously.
address@hidden table
+
+In a line format, ordinary characters represent themselves;
+conversion specifications start with @samp{%} and have one of the
+following forms.
+
address@hidden @samp
address@hidden %l
+stands for the contents of the line, not counting its trailing
+newline (if any). This format ignores whether the line is incomplete.
+
address@hidden %L
+stands for the contents of the line, including its trailing newline
+(if any). If a line is incomplete, this format preserves its
+incompleteness.
+
address@hidden %%
+stands for @samp{%}.
+
address@hidden %c'@var{C}'
+where @var{C} is a single character, stands for @var{C}.
address@hidden may not be a backslash or an apostrophe.
+For example, @samp{%c':'} stands for a colon.
+
address@hidden %c'address@hidden'
+where @var{O} is a string of 1, 2, or 3 octal digits,
+stands for the character with octal code @var{O}.
+For example, @samp{%c'\0'} stands for a null character.
+
address@hidden @var{F}n
+where @var{F} is a @code{printf} conversion specification,
+stands for the line number formatted with @var{F}.
+For example, @samp{%.5dn} prints the line number using the
address@hidden format @code{"%.5d"}. @xref{Line group formats}, for
+more about printf conversion specifications.
+
address@hidden table
+
+The default line format is @samp{%l} followed by a newline character.
+
+If the input contains tab characters and it is important that they line
+up on output, you should ensure that @samp{%l} or @samp{%L} in a line
+format is just after a tab stop (e.g.@: by preceding @samp{%l} or
address@hidden with a tab character), or you should use the @samp{-t} or
address@hidden option.
+
+Taken together, the line and line group formats let you specify many
+different formats. For example, the following command uses a format
+similar to @code{diff}'s normal format. You can tailor this command
+to get fine control over @code{diff}'s output.
+
address@hidden
+cvs diff \
+ --old-line-format='< %l
+' \
+ --new-line-format='> %l
+' \
+ --old-group-format='%df%(f=l?:,%dl)d%dE
+%<' \
+ --new-group-format='%dea%dF%(F=L?:,%dL)
+%>' \
+ --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL)
+%<---
+%>' \
+ --unchanged-group-format='' \
+ myfile
address@hidden example
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden diff examples
address@hidden diff examples
+
+The following line produces a Unidiff (@samp{-u} flag)
+between revision 1.14 and 1.19 of
address@hidden Due to the @samp{-kk} flag no
+keywords are substituted, so differences that only depend
+on keyword substitution are ignored.
+
address@hidden
+$ cvs diff -kk -u -r 1.14 -r 1.19 backend.c
address@hidden example
+
+Suppose the experimental branch EXPR1 was based on a
+set of files tagged RELEASE_1_0. To see what has
+happened on that branch, the following can be used:
+
address@hidden
+$ cvs diff -r RELEASE_1_0 -r EXPR1
address@hidden example
+
+A command like this can be used to produce a context
+diff between two releases:
+
address@hidden
+$ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs
address@hidden example
+
+If you are maintaining ChangeLogs, a command like the following
+just before you commit your changes may help you write
+the ChangeLog entry. All local modifications that have
+not yet been committed will be printed.
+
address@hidden
+$ cvs diff -u | less
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden export
address@hidden export---Export sources from CVS, similar to checkout
address@hidden export (subcommand)
+
address@hidden @bullet
address@hidden
+Synopsis: export [-flNnR] [-r rev|-D date] [-k subst] [-d dir] address@hidden
address@hidden
+Requires: repository.
address@hidden
+Changes: current directory.
address@hidden itemize
+
+This command is a variant of @code{checkout}; use it
+when you want a copy of the source for module without
+the @sc{cvs} administrative directories. For example, you
+might use @code{export} to prepare source for shipment
+off-site. This command requires that you specify a
+date or tag (with @samp{-D} or @samp{-r}), so that you
+can count on reproducing the source you ship to others
+(and thus it always prunes empty directories).
+
+One often would like to use @samp{-kv} with @code{cvs
+export}. This causes any keywords to be
+expanded such that an import done at some other site
+will not lose the keyword revision information. But be
+aware that doesn't handle an export containing binary
+files correctly. Also be aware that after having used
address@hidden, one can no longer use the @code{ident}
+command (which is part of the @sc{rcs} suite---see
+ident(1)) which looks for keyword strings. If
+you want to be able to use @code{ident} you must not
+use @samp{-kv}.
+
address@hidden
+* export options:: export options
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden export options
address@hidden export options
+
+These standard options are supported by @code{export}
+(@pxref{Common options}, for a complete description of
+them):
+
address@hidden @code
address@hidden -D @var{date}
+Use the most recent revision no later than @var{date}.
+
address@hidden -f
+If no matching revision is found, retrieve the most
+recent revision (instead of ignoring the file).
+
address@hidden -l
+Local; run only in current working directory.
+
address@hidden -n
+Do not run any checkout program.
+
address@hidden -R
+Export directories recursively. This is on by default.
+
address@hidden -r @var{tag}
+Use revision @var{tag}.
address@hidden table
+
+In addition, these options (that are common to
address@hidden and @code{export}) are also supported:
+
address@hidden @code
address@hidden -d @var{dir}
+Create a directory called @var{dir} for the working
+files, instead of using the module name.
address@hidden options}, for complete details on how
address@hidden handles this flag.
+
address@hidden -k @var{subst}
+Set keyword expansion mode (@pxref{Substitution modes}).
+
address@hidden -N
+Only useful together with @samp{-d @var{dir}}.
address@hidden options}, for complete details on how
address@hidden handles this flag.
address@hidden table
+
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden history
address@hidden history---Show status of files and users
address@hidden history (subcommand)
+
address@hidden @bullet
address@hidden
+Synopsis: history [-report] [-flags] [-options args] address@hidden
address@hidden
+Requires: the file @file{$CVSROOT/CVSROOT/history}
address@hidden
+Changes: nothing.
address@hidden itemize
+
address@hidden can keep a history file that tracks each use of the
address@hidden, @code{commit}, @code{rtag},
address@hidden, and @code{release} commands. You can
+use @code{history} to display this information in
+various formats.
+
+Logging must be enabled by creating the file
address@hidden/CVSROOT/history}.
+
address@hidden: @code{history} uses @samp{-f}, @samp{-l},
address@hidden, and @samp{-p} in ways that conflict with the
+normal use inside @sc{cvs} (@pxref{Common options}).}
+
address@hidden
+* history options:: history options
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden history options
address@hidden history options
+
+Several options (shown above as @samp{-report}) control what
+kind of report is generated:
+
address@hidden @code
address@hidden -c
+Report on each time commit was used (i.e., each time
+the repository was modified).
+
address@hidden -e
+Everything (all record types). Equivalent to
+specifying @samp{-x} with all record types. Of course,
address@hidden will also include record types which are
+added in a future version of @sc{cvs}; if you are
+writing a script which can only handle certain record
+types, you'll want to specify @samp{-x}.
+
address@hidden -m @var{module}
+Report on a particular module. (You can meaningfully
+use @samp{-m} more than once on the command line.)
+
address@hidden -o
+Report on checked-out modules. This is the default report type.
+
address@hidden -T
+Report on all tags.
+
address@hidden -x @var{type}
+Extract a particular set of record types @var{type} from the @sc{cvs}
+history. The types are indicated by single letters,
+which you may specify in combination.
+
+Certain commands have a single record type:
+
address@hidden @code
address@hidden F
+release
address@hidden O
+checkout
address@hidden E
+export
address@hidden T
+rtag
address@hidden table
+
address@hidden
+One of four record types may result from an update:
+
address@hidden @code
address@hidden C
+A merge was necessary but collisions were
+detected (requiring manual merging).
address@hidden G
+A merge was necessary and it succeeded.
address@hidden U
+A working file was copied from the repository.
address@hidden W
+The working copy of a file was deleted during
+update (because it was gone from the repository).
address@hidden table
+
address@hidden
+One of three record types results from commit:
+
address@hidden @code
address@hidden A
+A file was added for the first time.
address@hidden M
+A file was modified.
address@hidden R
+A file was removed.
address@hidden table
address@hidden table
+
+The options shown as @samp{-flags} constrain or expand
+the report without requiring option arguments:
+
address@hidden @code
address@hidden -a
+Show data for all users (the default is to show data
+only for the user executing @code{history}).
+
address@hidden -l
+Show last modification only.
+
address@hidden -w
+Show only the records for modifications done from the
+same working directory where @code{history} is
+executing.
address@hidden table
+
+The options shown as @samp{-options @var{args}} constrain the report
+based on an argument:
+
address@hidden @code
address@hidden -b @var{str}
+Show data back to a record containing the string
address@hidden in either the module name, the file name, or
+the repository path.
+
address@hidden -D @var{date}
+Show data since @var{date}. This is slightly different
+from the normal use of @samp{-D @var{date}}, which
+selects the newest revision older than @var{date}.
+
address@hidden -f @var{file}
+Show data for a particular file
+(you can specify several @samp{-f} options on the same command line).
+This is equivalent to specifying the file on the command line.
+
address@hidden -n @var{module}
+Show data for a particular module
+(you can specify several @samp{-n} options on the same command line).
+
address@hidden -p @var{repository}
+Show data for a particular source repository (you
+can specify several @samp{-p} options on the same command
+line).
+
address@hidden -r @var{rev}
+Show records referring to revisions since the revision
+or tag named @var{rev} appears in individual @sc{rcs}
+files. Each @sc{rcs} file is searched for the revision or
+tag.
+
address@hidden -t @var{tag}
+Show records since tag @var{tag} was last added to the
+history file. This differs from the @samp{-r} flag
+above in that it reads only the history file, not the
address@hidden files, and is much faster.
+
address@hidden -u @var{name}
+Show records for user @var{name}.
+
address@hidden -z @var{timezone}
+Show times in the selected records using the specified
+time zone instead of UTC.
address@hidden table
+
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden import
address@hidden import---Import sources into CVS, using vendor branches
address@hidden import (subcommand)
+
address@hidden FIXME: This node is way too long for one which has subnodes.
+
address@hidden @bullet
address@hidden
+Synopsis: import [-options] repository vendortag address@hidden
address@hidden
+Requires: Repository, source distribution directory.
address@hidden
+Changes: repository.
address@hidden itemize
+
+Use @code{import} to incorporate an entire source
+distribution from an outside source (e.g., a source
+vendor) into your source repository directory. You can
+use this command both for initial creation of a
+repository, and for wholesale updates to the module
+from the outside source. @xref{Tracking sources}, for
+a discussion on this subject.
+
+The @var{repository} argument gives a directory name
+(or a path to a directory) under the @sc{cvs} root directory
+for repositories; if the directory did not exist,
+import creates it.
+
+When you use import for updates to source that has been
+modified in your source repository (since a prior
+import), it will notify you of any files that conflict
+in the two branches of development; use @samp{checkout
+-j} to reconcile the differences, as import instructs
+you to do.
+
+If @sc{cvs} decides a file should be ignored
+(@pxref{cvsignore}), it does not import it and prints
address@hidden } followed by the filename (@pxref{import output}, for a
+complete description of the output).
+
+If the file @file{$CVSROOT/CVSROOT/cvswrappers} exists,
+any file whose names match the specifications in that
+file will be treated as packages and the appropriate
+filtering will be performed on the file/directory
+before being imported. @xref{Wrappers}.
+
+The outside source is saved in a first-level
+branch, by default 1.1.1. Updates are leaves of this
+branch; for example, files from the first imported
+collection of source will be revision 1.1.1.1, then
+files from the first imported update will be revision
+1.1.1.2, and so on.
+
+At least three arguments are required.
address@hidden is needed to identify the collection
+of source. @var{vendortag} is a tag for the entire
+branch (e.g., for 1.1.1). You must also specify at
+least one @var{releasetag} to identify the files at
+the leaves created each time you execute @code{import}.
+
address@hidden I'm not completely sure this belongs here. But
address@hidden we need to say it _somewhere_ reasonably obvious; it
address@hidden is a common misconception among people first learning CVS
+Note that @code{import} does @emph{not} change the
+directory in which you invoke it. In particular, it
+does not set up that directory as a @sc{cvs} working
+directory; if you want to work with the sources import
+them first and then check them out into a different
+directory (@pxref{Getting the source}).
+
address@hidden
+* import options:: import options
+* import output:: import output
+* import examples:: import examples
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden import options
address@hidden import options
+
+This standard option is supported by @code{import}
+(@pxref{Common options}, for a complete description):
+
address@hidden @code
address@hidden -m @var{message}
+Use @var{message} as log information, instead of
+invoking an editor.
address@hidden table
+
+There are the following additional special options.
+
address@hidden @code
address@hidden -b @var{branch}
+See @ref{Multiple vendor branches}.
+
address@hidden -k @var{subst}
+Indicate the keyword expansion mode desired. This
+setting will apply to all files created during the
+import, but not to any files that previously existed in
+the repository. See @ref{Substitution modes}, for a
+list of valid @samp{-k} settings.
+
address@hidden -I @var{name}
+Specify file names that should be ignored during
+import. You can use this option repeatedly. To avoid
+ignoring any files at all (even those ignored by
+default), specify `-I !'.
+
address@hidden can be a file name pattern of the same type
+that you can specify in the @file{.cvsignore} file.
address@hidden
address@hidden -- Is this really true?
+
address@hidden -W @var{spec}
+Specify file names that should be filtered during
+import. You can use this option repeatedly.
+
address@hidden can be a file name pattern of the same type
+that you can specify in the @file{.cvswrappers}
+file. @xref{Wrappers}.
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden import output
address@hidden import output
+
address@hidden keeps you informed of its progress by printing a line
+for each file, preceded by one character indicating the status of the file:
+
address@hidden @code
address@hidden U @var{file}
+The file already exists in the repository and has not been locally
+modified; a new revision has been created (if necessary).
+
address@hidden N @var{file}
+The file is a new file which has been added to the repository.
+
address@hidden C @var{file}
+The file already exists in the repository but has been locally modified;
+you will have to merge the changes.
+
address@hidden I @var{file}
+The file is being ignored (@pxref{cvsignore}).
+
address@hidden Symbolic link, importing
address@hidden Link, symbolic, importing
address@hidden FIXME: also (somewhere else) probably
address@hidden should be documenting what happens if you "cvs add"
address@hidden a symbolic link. Also maybe what happens if
address@hidden you manually create symbolic links within the
address@hidden repository (? - not sure why we'd want to suggest
address@hidden doing that).
address@hidden L @var{file}
+The file is a symbolic link; @code{cvs import} ignores symbolic links.
+People periodically suggest that this behavior should
+be changed, but if there is a consensus on what it
+should be changed to, it is not apparent.
+(Various options in the @file{modules} file can be used
+to recreate symbolic links on checkout, update, etc.;
address@hidden)
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden import examples
address@hidden import examples
+
+See @ref{Tracking sources}, and @ref{From files}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden log
address@hidden log---Print out log information for files
address@hidden log (subcommand)
+
address@hidden @bullet
address@hidden
+Synopsis: log [options] address@hidden
address@hidden
+Requires: repository, working directory.
address@hidden
+Changes: nothing.
address@hidden itemize
+
+Display log information for files. @code{log} used to
+call the @sc{rcs} utility @code{rlog}. Although this
+is no longer true in the current sources, this history
+determines the format of the output and the options,
+which are not quite in the style of the other @sc{cvs}
+commands.
+
address@hidden Timezone, in output
address@hidden Zone, time, in output
address@hidden Kind of a funny place to document the timezone used
address@hidden in output from commands other than @code{log}.
address@hidden There is also more we need to say about this,
address@hidden including what happens in a client/server environment.
+The output includes the location of the @sc{rcs} file,
+the @dfn{head} revision (the latest revision on the
+trunk), all symbolic names (tags) and some other
+things. For each revision, the revision number, the
+author, the number of lines added/deleted and the log
+message are printed. All times are displayed in
+Coordinated Universal Time (UTC). (Other parts of
address@hidden print times in the local timezone).
address@hidden FIXCVS: need a better way to control the timezone
address@hidden used in output. Previous/current versions of CVS did/do
address@hidden sometimes support -z in RCSINIT, and/or an
address@hidden undocumented (except by reference to 'rlog') -z option
address@hidden to cvs log, but this has not been a consistent,
address@hidden documented feature. Perhaps a new global option,
address@hidden where LT means the client's timezone, which the
address@hidden client then communicates to the server, is the
address@hidden right solution.
+
address@hidden: @code{log} uses @samp{-R} in a way that conflicts
+with the normal use inside @sc{cvs} (@pxref{Common options}).}
+
address@hidden
+* log options:: log options
+* log examples:: log examples
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden log options
address@hidden log options
+
+By default, @code{log} prints all information that is
+available. All other options restrict the output.
+
address@hidden @code
address@hidden -b
+Print information about the revisions on the default
+branch, normally the highest branch on the trunk.
+
address@hidden -d @var{dates}
+Print information about revisions with a checkin
+date/time in the range given by the
+semicolon-separated list of dates. The date formats
+accepted are those accepted by the @samp{-D} option to
+many other @sc{cvs} commands (@pxref{Common options}).
+Dates can be combined into ranges as follows:
+
address@hidden Should we be thinking about accepting ISO8601
address@hidden ranges? For example "1972-09-10/1972-09-12".
address@hidden @code
address@hidden @var{d1}<@var{d2}
address@hidden @var{d2}>@var{d1}
+Select the revisions that were deposited between
address@hidden and @var{d2}.
+
address@hidden <@var{d}
address@hidden @var{d}>
+Select all revisions dated @var{d} or earlier.
+
address@hidden @var{d}<
address@hidden >@var{d}
+Select all revisions dated @var{d} or later.
+
address@hidden @var{d}
+Select the single, latest revision dated @var{d} or
+earlier.
address@hidden table
+
+The @samp{>} or @samp{<} characters may be followed by
address@hidden to indicate an inclusive range rather than an
+exclusive one.
+
+Note that the separator is a semicolon (;).
+
address@hidden -h
+Print only the name of the @sc{rcs} file, name
+of the file in the working directory, head,
+default branch, access list, locks, symbolic names, and
+suffix.
+
address@hidden -l
+Local; run only in current working directory. (Default
+is to run recursively).
+
address@hidden -N
+Do not print the list of tags for this file. This
+option can be very useful when your site uses a lot of
+tags, so rather than "more"'ing over 3 pages of tag
+information, the log information is presented without
+tags at all.
+
address@hidden -R
+Print only the name of the @sc{rcs} file.
+
address@hidden Note that using a bare revision (in addition to not
address@hidden being explicitly documented here) is potentially
address@hidden confusing; it shows the log message to get from the
address@hidden previous revision to that revision. "-r1.3 -r1.6"
address@hidden (equivalent to "-r1.3,1.6") is even worse; it
address@hidden prints the messages to get from 1.2 to 1.3 and 1.5
address@hidden to 1.6. By analogy with "cvs diff", users might
address@hidden expect that it is more like specifying a range.
address@hidden It is not 100% clear to me how much of this should
address@hidden be documented (for example, multiple -r options
address@hidden perhaps could/should be deprecated given the false
address@hidden analogy with "cvs diff").
address@hidden In general, this section should be rewritten to talk
address@hidden about messages to get from revision rev1 to rev2,
address@hidden rather than messages for revision rev2 (that is, the
address@hidden messages are associated with a change not a static
address@hidden revision and failing to make this distinction causes
address@hidden much confusion).
address@hidden address@hidden
+Print information about revisions given in the
+comma-separated list @var{revisions} of revisions and
+ranges. The following table explains the available
+range formats:
+
address@hidden @code
address@hidden @var{rev1}:@var{rev2}
+Revisions @var{rev1} to @var{rev2} (which must be on
+the same branch).
+
address@hidden @var{rev1}::@var{rev2}
+The same, but excluding @var{rev1}.
+
address@hidden :@var{rev}
address@hidden ::@var{rev}
+Revisions from the beginning of the branch up to
+and including @var{rev}.
+
address@hidden @var{rev}:
+Revisions starting with @var{rev} to the end of the
+branch containing @var{rev}.
+
address@hidden @var{rev}::
+Revisions starting just after @var{rev} to the end of the
+branch containing @var{rev}.
+
address@hidden @var{branch}
+An argument that is a branch means all revisions on
+that branch.
+
address@hidden @var{branch1}:@var{branch2}
address@hidden @var{branch1}::@var{branch2}
+A range of branches means all revisions
+on the branches in that range.
+
address@hidden @var{branch}.
+The latest revision in @var{branch}.
address@hidden table
+
+A bare @samp{-r} with no revisions means the latest
+revision on the default branch, normally the trunk.
+There can be no space between the @samp{-r} option and
+its argument.
+
address@hidden -S
+Suppress the header if no revisions are selected.
+
address@hidden -s @var{states}
+Print information about revisions whose state
+attributes match one of the states given in the
+comma-separated list @var{states}.
+
address@hidden -t
+Print the same as @samp{-h}, plus the descriptive text.
+
address@hidden address@hidden
+Print information about revisions checked in by users
+with login names appearing in the comma-separated list
address@hidden If @var{logins} is omitted, the user's
+login is assumed. There can be no space between the
address@hidden option and its argument.
address@hidden table
+
address@hidden prints the intersection of the revisions
+selected with the options @samp{-d}, @samp{-s}, and
address@hidden, intersected with the union of the revisions
+selected by @samp{-b} and @samp{-r}.
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden log examples
address@hidden log examples
+
+Contributed examples are gratefully accepted.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden rdiff
address@hidden rdiff---'patch' format diffs between releases
address@hidden rdiff (subcommand)
+
address@hidden @bullet
address@hidden
+rdiff [-flags] [-V vn] [-r t|-D d [-r t2|-D d2]] address@hidden
address@hidden
+Requires: repository.
address@hidden
+Changes: nothing.
address@hidden
+Synonym: patch
address@hidden itemize
+
+Builds a Larry Wall format patch(1) file between two
+releases, that can be fed directly into the @code{patch}
+program to bring an old release up-to-date with the new
+release. (This is one of the few @sc{cvs} commands that
+operates directly from the repository, and doesn't
+require a prior checkout.) The diff output is sent to
+the standard output device.
+
+You can specify (using the standard @samp{-r} and
address@hidden options) any combination of one or two
+revisions or dates. If only one revision or date is
+specified, the patch file reflects differences between
+that revision or date and the current head revisions in
+the @sc{rcs} file.
+
+Note that if the software release affected is contained
+in more than one directory, then it may be necessary to
+specify the @samp{-p} option to the @code{patch} command when
+patching the old sources, so that @code{patch} is able to find
+the files that are located in other directories.
+
address@hidden
+* rdiff options:: rdiff options
+* rdiff examples:: rdiff examples
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden rdiff options
address@hidden rdiff options
+
+These standard options are supported by @code{rdiff}
+(@pxref{Common options}, for a complete description of
+them):
+
address@hidden @code
address@hidden -D @var{date}
+Use the most recent revision no later than @var{date}.
+
address@hidden -f
+If no matching revision is found, retrieve the most
+recent revision (instead of ignoring the file).
+
address@hidden -l
+Local; don't descend subdirectories.
+
address@hidden -R
+Examine directories recursively. This option is on by default.
+
address@hidden -r @var{tag}
+Use revision @var{tag}.
address@hidden table
+
+In addition to the above, these options are available:
+
address@hidden @code
address@hidden -c
+Use the context diff format. This is the default format.
+
address@hidden -s
+Create a summary change report instead of a patch. The
+summary includes information about files that were
+changed or added between the releases. It is sent to
+the standard output device. This is useful for finding
+out, for example, which files have changed between two
+dates or revisions.
+
address@hidden -t
+A diff of the top two revisions is sent to the standard
+output device. This is most useful for seeing what the
+last change to a file was.
+
address@hidden -u
+Use the unidiff format for the context diffs.
+Remember that old versions
+of the @code{patch} program can't handle the unidiff
+format, so if you plan to post this patch to the net
+you should probably not use @samp{-u}.
+
address@hidden -V @var{vn}
+Expand keywords according to the rules current in
address@hidden version @var{vn} (the expansion format changed with
address@hidden version 5). Note that this option is no
+longer accepted. @sc{cvs} will always expand keywords the
+way that @sc{rcs} version 5 does.
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden rdiff examples
address@hidden rdiff examples
+
+Suppose you receive mail from @t{foo@@example.net} asking for an
+update from release 1.2 to 1.4 of the tc compiler. You
+have no such patches on hand, but with @sc{cvs} that can
+easily be fixed with a command such as this:
+
address@hidden
+$ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \
+$$ Mail -s 'The patches you asked for' foo@@example.net
address@hidden example
+
+Suppose you have made release 1.3, and forked a branch
+called @samp{R_1_3fix} for bugfixes. @samp{R_1_3_1}
+corresponds to release 1.3.1, which was made some time
+ago. Now, you want to see how much development has been
+done on the branch. This command can be used:
+
address@hidden
+$ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name
+cvs rdiff: Diffing module-name
+File ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6
+File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4
+File bar.h,v changed from revision 1.29.2.1 to 1.2
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden release
address@hidden release---Indicate that a Module is no longer in use
address@hidden release (subcommand)
+
address@hidden @bullet
address@hidden
+release [-d] address@hidden
address@hidden
+Requires: Working directory.
address@hidden
+Changes: Working directory, history log.
address@hidden itemize
+
+This command is meant to safely cancel the effect of
address@hidden checkout}. Since @sc{cvs} doesn't lock files, it
+isn't strictly necessary to use this command. You can
+always simply delete your working directory, if you
+like; but you risk losing changes you may have
+forgotten, and you leave no trace in the @sc{cvs} history
+file (@pxref{history file}) that you've abandoned your
+checkout.
+
+Use @samp{cvs release} to avoid these problems. This
+command checks that no uncommitted changes are
+present; that you are executing it from immediately
+above a @sc{cvs} working directory; and that the repository
+recorded for your files is the same as the repository
+defined in the module database.
+
+If all these conditions are true, @samp{cvs release}
+leaves a record of its execution (attesting to your
+intentionally abandoning your checkout) in the @sc{cvs}
+history log.
+
address@hidden
+* release options:: release options
+* release output:: release output
+* release examples:: release examples
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden release options
address@hidden release options
+
+The @code{release} command supports one command option:
+
address@hidden @code
address@hidden -d
+Delete your working copy of the file if the release
+succeeds. If this flag is not given your files will
+remain in your working directory.
+
address@hidden: The @code{release} command deletes
+all directories and files recursively. This
+has the very serious side-effect that any directory
+that you have created inside your checked-out sources,
+and not added to the repository (using the @code{add}
+command; @pxref{Adding files}) will be silently deleted---even
+if it is non-empty!}
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden release output
address@hidden release output
+
+Before @code{release} releases your sources it will
+print a one-line message for any file that is not
+up-to-date.
+
address@hidden @code
address@hidden U @var{file}
address@hidden P @var{file}
+There exists a newer revision of this file in the
+repository, and you have not modified your local copy
+of the file (@samp{U} and @samp{P} mean the same thing).
+
address@hidden A @var{file}
+The file has been added to your private copy of the
+sources, but has not yet been committed to the
+repository. If you delete your copy of the sources
+this file will be lost.
+
address@hidden R @var{file}
+The file has been removed from your private copy of the
+sources, but has not yet been removed from the
+repository, since you have not yet committed the
+removal. @xref{commit}.
+
address@hidden M @var{file}
+The file is modified in your working directory. There
+might also be a newer revision inside the repository.
+
address@hidden ? @var{file}
address@hidden is in your working directory, but does not
+correspond to anything in the source repository, and is
+not in the list of files for @sc{cvs} to ignore (see the
+description of the @samp{-I} option, and
address@hidden). If you remove your working
+sources, this file will be lost.
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden release examples
address@hidden release examples
+
+Release the @file{tc} directory, and delete your local working copy
+of the files.
+
address@hidden
+$ cd .. # @r{You must stand immediately above the}
+ # @r{sources when you issue @samp{cvs release}.}
+$ cvs release -d tc
+You have [0] altered files in this repository.
+Are you sure you want to release (and delete) directory `tc': y
+$
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden update
address@hidden update---Bring work tree in sync with repository
address@hidden update (subcommand)
+
address@hidden @bullet
address@hidden
+update [-ACdflPpR] [-I name] [-j rev [-j rev]] [-k kflag] [-r tag|-D date] [-W
spec] address@hidden
address@hidden
+Requires: repository, working directory.
address@hidden
+Changes: working directory.
address@hidden itemize
+
+After you've run checkout to create your private copy
+of source from the common repository, other developers
+will continue changing the central source. From time
+to time, when it is convenient in your development
+process, you can use the @code{update} command from
+within your working directory to reconcile your work
+with any revisions applied to the source repository
+since your last checkout or update. Without the @code{-C}
+option, @code{update} will also merge any differences
+between the local copy of files and their base revisions
+into any destination revisions specified with @code{-r},
address@hidden, or @code{-A}.
+
address@hidden
+* update options:: update options
+* update output:: update output
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden update options
address@hidden update options
+
+These standard options are available with @code{update}
+(@pxref{Common options}, for a complete description of
+them):
+
address@hidden @code
address@hidden -D date
+Use the most recent revision no later than @var{date}.
+This option is sticky, and implies @samp{-P}.
+See @ref{Sticky tags}, for more information on sticky tags/dates.
+
address@hidden -f
+Only useful with the @samp{-D @var{date}} or @samp{-r
address@hidden flags. If no matching revision is found,
+retrieve the most recent revision (instead of ignoring
+the file).
+
address@hidden -k @var{kflag}
+Process keywords according to @var{kflag}. See
address@hidden substitution}.
+This option is sticky; future updates of
+this file in this working directory will use the same
address@hidden The @code{status} command can be viewed
+to see the sticky options. See @ref{Invoking CVS}, for
+more information on the @code{status} command.
+
address@hidden -l
+Local; run only in current working directory. @xref{Recursive behavior}.
+
address@hidden -P
+Prune empty directories. See @ref{Moving directories}.
+
address@hidden -p
+Pipe files to the standard output.
+
address@hidden -R
+Update directories recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r rev
+Retrieve revision/tag @var{rev}. This option is sticky,
+and implies @samp{-P}.
+See @ref{Sticky tags}, for more information on sticky tags/dates.
address@hidden table
+
address@hidden 800
+These special options are also available with
address@hidden
+
address@hidden @code
address@hidden -A
+Reset any sticky tags, dates, or @samp{-k} options.
+See @ref{Sticky tags}, for more information on sticky tags/dates.
+
address@hidden -C
+Overwrite locally modified files with clean copies from
+the repository (the modified file is saved in
address@hidden@address@hidden, however).
+
address@hidden -d
+Create any directories that exist in the repository if
+they're missing from the working directory. Normally,
address@hidden acts only on directories and files that
+were already enrolled in your working directory.
+
+This is useful for updating directories that were
+created in the repository since the initial checkout;
+but it has an unfortunate side effect. If you
+deliberately avoided certain directories in the
+repository when you created your working directory
+(either through use of a module name or by listing
+explicitly the files and directories you wanted on the
+command line), then updating with @samp{-d} will create
+those directories, which may not be what you want.
+
address@hidden -I @var{name}
+Ignore files whose names match @var{name} (in your
+working directory) during the update. You can specify
address@hidden more than once on the command line to specify
+several files to ignore. Use @samp{-I !} to avoid
+ignoring any files at all. @xref{cvsignore}, for other
+ways to make @sc{cvs} ignore some files.
+
address@hidden address@hidden
+Specify file names that should be filtered during
+update. You can use this option repeatedly.
+
address@hidden can be a file name pattern of the same type
+that you can specify in the @file{.cvswrappers}
+file. @xref{Wrappers}.
+
address@hidden address@hidden
+With two @samp{-j} options, merge changes from the
+revision specified with the first @samp{-j} option to
+the revision specified with the second @samp{j} option,
+into the working directory.
+
+With one @samp{-j} option, merge changes from the
+ancestor revision to the revision specified with the
address@hidden option, into the working directory. The
+ancestor revision is the common ancestor of the
+revision which the working directory is based on, and
+the revision specified in the @samp{-j} option.
+
+Note that using a single @samp{-j @var{tagname}} option rather than
address@hidden @var{branchname}} to merge changes from a branch will
+often not remove files which were removed on the branch.
address@hidden adds and removals}, for more.
+
+In addition, each @samp{-j} option can contain an optional
+date specification which, when used with branches, can
+limit the chosen revision to one within a specific
+date. An optional date is specified by adding a colon
+(:) to the tag:
address@hidden@var{Symbolic_Tag}:@var{Date_Specifier}}.
+
address@hidden and merging}.
+
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden update output
address@hidden update output
+
address@hidden and @code{checkout} keep you informed of
+their progress by printing a line for each file, preceded
+by one character indicating the status of the file:
+
address@hidden @code
address@hidden U @var{file}
+The file was brought up to date with respect to the
+repository. This is done for any file that exists in
+the repository but not in your source, and for files
+that you haven't changed but are not the most recent
+versions available in the repository.
+
address@hidden P @var{file}
+Like @samp{U}, but the @sc{cvs} server sends a patch instead of an entire
+file. This accomplishes the same thing as @samp{U} using less bandwidth.
+
address@hidden A @var{file}
+The file has been added to your private copy of the
+sources, and will be added to the source repository
+when you run @code{commit} on the file. This is a
+reminder to you that the file needs to be committed.
+
address@hidden R @var{file}
+The file has been removed from your private copy of the
+sources, and will be removed from the source repository
+when you run @code{commit} on the file. This is a
+reminder to you that the file needs to be committed.
+
address@hidden M @var{file}
+The file is modified in your working directory.
+
address@hidden can indicate one of two states for a file
+you're working on: either there were no modifications
+to the same file in the repository, so that your file
+remains as you last saw it; or there were modifications
+in the repository as well as in your copy, but they
+were merged successfully, without conflict, in your
+working directory.
+
address@hidden will print some messages if it merges your work,
+and a backup copy of your working file (as it looked
+before you ran @code{update}) will be made. The exact
+name of that file is printed while @code{update} runs.
+
address@hidden C @var{file}
address@hidden .# files
address@hidden __ files (VMS)
+A conflict was detected while trying to merge your
+changes to @var{file} with changes from the source
+repository. @var{file} (the copy in your working
+directory) is now the result of attempting to merge
+the two revisions; an unmodified copy of your file
+is also in your working directory, with the name
address@hidden@address@hidden where @var{revision}
+is the revision that your modified file started
+from. Resolve the conflict as described in
address@hidden example}.
address@hidden "some systems" as in out-of-the-box OSes? Not as
address@hidden far as I know. We need to advise sysadmins as well
address@hidden as users how to set up this kind of purge, if that is
address@hidden what they want.
address@hidden We also might want to think about cleaner solutions,
address@hidden like having CVS remove the .# file once the conflict
address@hidden has been resolved or something like that.
+(Note that some systems automatically purge
+files that begin with @file{.#} if they have not been
+accessed for a few days. If you intend to keep a copy
+of your original file, it is a very good idea to rename
+it.) Under @sc{vms}, the file name starts with
address@hidden rather than @file{.#}.
+
address@hidden ? @var{file}
address@hidden is in your working directory, but does not
+correspond to anything in the source repository, and is
+not in the list of files for @sc{cvs} to ignore (see the
+description of the @samp{-I} option, and
address@hidden).
address@hidden table
+
address@hidden Invoking CVS
address@hidden Quick reference to CVS commands
address@hidden Command reference
address@hidden Reference, commands
address@hidden Invoking CVS
+
+This appendix describes how to invoke @sc{cvs}, with
+references to where each command or feature is
+described in detail. For other references run the
address@hidden --help} command, or see @ref{Index}.
+
+A @sc{cvs} command looks like:
+
address@hidden
+cvs [ @var{global_options} ] @var{command} [ @var{command_options} ] [
@var{command_args} ]
address@hidden example
+
+Global options:
+
address@hidden @code
address@hidden address@hidden
+Specify legal @sc{cvsroot} directory (server only) (not
+in @sc{cvs} 1.9 and older). See @ref{Password
+authentication server}.
+
address@hidden -a
+Authenticate all communication (client only) (not in @sc{cvs}
+1.9 and older). See @ref{Global options}.
+
address@hidden -b
+Specify RCS location (@sc{cvs} 1.9 and older). See
address@hidden options}.
+
address@hidden -d @var{root}
+Specify the @sc{cvsroot}. See @ref{Repository}.
+
address@hidden -e @var{editor}
+Edit messages with @var{editor}. See @ref{Committing
+your changes}.
+
address@hidden -f
+Do not read the @file{~/.cvsrc} file. See @ref{Global
+options}.
+
address@hidden -H
address@hidden --help
+Print a help message. See @ref{Global options}.
+
address@hidden -l
+Do not log in @file{$CVSROOT/CVSROOT/history} file. See @ref{Global
+options}.
+
address@hidden -n
+Do not change any files. See @ref{Global options}.
+
address@hidden -Q
+Be really quiet. See @ref{Global options}.
+
address@hidden -q
+Be somewhat quiet. See @ref{Global options}.
+
address@hidden -r
+Make new working files read-only. See @ref{Global options}.
+
address@hidden -s @address@hidden
+Set a user variable. See @ref{Variables}.
+
address@hidden -T @var{tempdir}
+Put temporary files in @var{tempdir}. See @ref{Global
+options}.
+
address@hidden -t
+Trace @sc{cvs} execution. See @ref{Global options}.
+
address@hidden -v
address@hidden --version
+Display version and copyright information for @sc{cvs}.
+
address@hidden -w
+Make new working files read-write. See @ref{Global
+options}.
+
address@hidden -x
+Encrypt all communication (client only).
+See @ref{Global options}.
+
address@hidden -z @var{gzip-level}
address@hidden Compression
address@hidden Gzip
+Set the compression level (client only).
+See @ref{Global options}.
address@hidden table
+
+Keyword expansion modes (@pxref{Substitution modes}):
+
address@hidden
+-kkv address@hidden: file1,v 1.1 1993/12/09 03:21:13 joe Exp $
+-kkvl address@hidden: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
+-kk address@hidden
+-kv file1,v 1.1 1993/12/09 03:21:13 joe Exp
+-ko @i{no expansion}
+-kb @i{no expansion, file is binary}
address@hidden example
+
+Keywords (@pxref{Keyword list}):
+
address@hidden
address@hidden: joe $
address@hidden: 1993/12/09 03:21:13 $
address@hidden: files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
address@hidden: /home/files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
address@hidden: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
address@hidden: harry $
address@hidden: snapshot_1_14 $
address@hidden: file1,v $
address@hidden: 1.1 $
address@hidden: /home/files/file1,v $
address@hidden: Exp $
address@hidden: file1,v $
+Revision 1.1 1993/12/09 03:30:17 joe
+Initial revision
+
address@hidden example
+
address@hidden The idea behind this table is that we want each item
address@hidden to be a sentence or two at most. Preferably a
address@hidden single line.
address@hidden
address@hidden In some cases refs to "foo options" are just to get
address@hidden this thing written quickly, not because the "foo
address@hidden options" node is really the best place to point.
+Commands, command options, and command arguments:
+
address@hidden @code
address@hidden ------------------------------------------------------------
address@hidden add address@hidden address@hidden@dots{}]
+Add a new file/directory. See @ref{Adding files}.
+
address@hidden @code
address@hidden -k @var{kflag}
+Set keyword expansion.
+
address@hidden -m @var{msg}
+Set file description.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden admin address@hidden address@hidden@dots{}]
+Administration of history files in the repository. See
address@hidden
address@hidden This list omits those options which are not
address@hidden documented as being useful with CVS. That might be
address@hidden a mistake...
+
address@hidden @code
address@hidden address@hidden
+Set default branch. See @ref{Reverting local changes}.
+
address@hidden address@hidden
+Set comment leader.
+
address@hidden address@hidden
+Set keyword substitution. See @ref{Keyword
+substitution}.
+
address@hidden address@hidden
+Lock revision @var{rev}, or latest revision.
+
address@hidden address@hidden:@var{msg}
+Replace the log message of revision @var{rev} with
address@hidden
+
address@hidden address@hidden
+Delete revisions from the repository. See
address@hidden options}.
+
address@hidden -q
+Run quietly; do not print diagnostics.
+
address@hidden address@hidden:@var{rev}]
+Set the state.
+
address@hidden Does not work for client/server CVS
address@hidden -t
+Set file description from standard input.
+
address@hidden address@hidden
+Set file description from @var{file}.
+
address@hidden address@hidden
+Set file description to @var{string}.
+
address@hidden address@hidden
+Unlock revision @var{rev}, or latest revision.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden annotate address@hidden address@hidden@dots{}]
+Show last revision where each line was modified. See
address@hidden
+
address@hidden @code
address@hidden -D @var{date}
+Annotate the most recent revision no later than
address@hidden See @ref{Common options}.
+
address@hidden -F
+Force annotation of binary files. (Without this option,
+binary files are skipped with a message.)
+
address@hidden -f
+Use head revision if tag/date not found. See
address@hidden options}.
+
address@hidden -l
+Local; run only in current working directory. @xref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{tag}
+Annotate revision @var{tag}. See @ref{Common options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden checkout address@hidden @address@hidden
+Get a copy of the sources. See @ref{checkout}.
+
address@hidden @code
address@hidden -A
+Reset any sticky tags/date/options. See @ref{Sticky
+tags} and @ref{Keyword substitution}.
+
address@hidden -c
+Output the module database. See @ref{checkout options}.
+
address@hidden -D @var{date}
+Check out revisions as of @var{date} (is sticky). See
address@hidden options}.
+
address@hidden -d @var{dir}
+Check out into @var{dir}. See @ref{checkout options}.
+
address@hidden -f
+Use head revision if tag/date not found. See
address@hidden options}.
+
address@hidden Probably want to use rev1/rev2 style like for diff
address@hidden -r. Here and in on-line help.
address@hidden -j @var{rev}
+Merge in changes. See @ref{checkout options}.
+
address@hidden -k @var{kflag}
+Use @var{kflag} keyword expansion. See
address@hidden modes}.
+
address@hidden -l
+Local; run only in current working directory. @xref{Recursive behavior}.
+
address@hidden -N
+Don't ``shorten'' module paths if -d specified. See
address@hidden options}.
+
address@hidden -n
+Do not run module program (if any). See @ref{checkout options}.
+
address@hidden -P
+Prune empty directories. See @ref{Moving directories}.
+
address@hidden -p
+Check out files to standard output (avoids
+stickiness). See @ref{checkout options}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{tag}
+Checkout revision @var{tag} (is sticky). See @ref{Common options}.
+
address@hidden -s
+Like -c, but include module status. See @ref{checkout options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden commit address@hidden address@hidden@dots{}]
+Check changes into the repository. See @ref{commit}.
+
address@hidden @code
address@hidden -F @var{file}
+Read log message from @var{file}. See @ref{commit options}.
+
address@hidden -f
address@hidden What is this "disables recursion"? It is from the
address@hidden on-line help; is it documented in this manual?
+Force the file to be committed; disables recursion.
+See @ref{commit options}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -m @var{msg}
+Use @var{msg} as log message. See @ref{commit options}.
+
address@hidden -n
+Do not run module program (if any). See @ref{commit options}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{rev}
+Commit to @var{rev}. See @ref{commit options}.
address@hidden FIXME: should be dragging over text from
address@hidden commit options, especially if it can be cleaned up
address@hidden and made concise enough.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden diff address@hidden address@hidden@dots{}]
+Show differences between revisions. See @ref{diff}.
+In addition to the options shown below, accepts a wide
+variety of options to control output style, for example
address@hidden for context diffs.
+
address@hidden @code
address@hidden -D @var{date1}
+Diff revision for date against working file. See
address@hidden options}.
+
address@hidden -D @var{date2}
+Diff @var{rev1}/@var{date1} against @var{date2}. See
address@hidden options}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -N
+Include diffs for added and removed files. See
address@hidden options}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{rev1}
+Diff revision for @var{rev1} against working file. See
address@hidden options}.
+
address@hidden -r @var{rev2}
+Diff @var{rev1}/@var{date1} against @var{rev2}. See @ref{diff options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden edit address@hidden address@hidden@dots{}]
+Get ready to edit a watched file. See @ref{Editing files}.
+
address@hidden @code
address@hidden -a @var{actions}
+Specify actions for temporary watch, where
address@hidden is @code{edit}, @code{unedit},
address@hidden, @code{all}, or @code{none}. See
address@hidden files}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden editors address@hidden address@hidden@dots{}]
+See who is editing a watched file. See @ref{Watch information}.
+
address@hidden @code
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden export address@hidden @address@hidden
+Export files from @sc{cvs}. See @ref{export}.
+
address@hidden @code
address@hidden -D @var{date}
+Check out revisions as of @var{date}. See
address@hidden options}.
+
address@hidden -d @var{dir}
+Check out into @var{dir}. See @ref{export options}.
+
address@hidden -f
+Use head revision if tag/date not found. See
address@hidden options}.
+
address@hidden -k @var{kflag}
+Use @var{kflag} keyword expansion. See
address@hidden modes}.
+
address@hidden -l
+Local; run only in current working directory. @xref{Recursive behavior}.
+
address@hidden -N
+Don't ``shorten'' module paths if -d specified. See
address@hidden options}.
+
address@hidden -n
+Do not run module program (if any). See @ref{export options}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{tag}
+Checkout revision @var{tag}. See @ref{Common options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden history address@hidden address@hidden@dots{}]
+Show repository access history. See @ref{history}.
+
address@hidden @code
address@hidden -a
+All users (default is self). See @ref{history options}.
+
address@hidden -b @var{str}
+Back to record with @var{str} in module/file/repos
+field. See @ref{history options}.
+
address@hidden -c
+Report on committed (modified) files. See @ref{history options}.
+
address@hidden -D @var{date}
+Since @var{date}. See @ref{history options}.
+
address@hidden -e
+Report on all record types. See @ref{history options}.
+
address@hidden -l
+Last modified (committed or modified report). See @ref{history options}.
+
address@hidden -m @var{module}
+Report on @var{module} (repeatable). See @ref{history options}.
+
address@hidden -n @var{module}
+In @var{module}. See @ref{history options}.
+
address@hidden -o
+Report on checked out modules. See @ref{history options}.
+
address@hidden -p @var{repository}
+In @var{repository}. See @ref{history options}.
+
address@hidden -r @var{rev}
+Since revision @var{rev}. See @ref{history options}.
+
address@hidden -T
address@hidden What the @address@hidden is a TAG? Same as a tag? This
address@hidden wording is also in the online-line help.
+Produce report on all TAGs. See @ref{history options}.
+
address@hidden -t @var{tag}
+Since tag record placed in history file (by anyone).
+See @ref{history options}.
+
address@hidden -u @var{user}
+For user @var{user} (repeatable). See @ref{history options}.
+
address@hidden -w
+Working directory must match. See @ref{history options}.
+
address@hidden -x @var{types}
+Report on @var{types}, one or more of
address@hidden See @ref{history options}.
+
address@hidden -z @var{zone}
+Output for time zone @var{zone}. See @ref{history options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden import address@hidden @var{repository} @var{vendor-tag}
@address@hidden
+Import files into @sc{cvs}, using vendor branches. See
address@hidden
+
address@hidden @code
address@hidden -b @var{bra}
+Import to vendor branch @var{bra}. See
address@hidden vendor branches}.
+
address@hidden -d
+Use the file's modification time as the time of
+import. See @ref{import options}.
+
address@hidden -k @var{kflag}
+Set default keyword substitution mode. See
address@hidden options}.
+
address@hidden -m @var{msg}
+Use @var{msg} for log message. See
address@hidden options}.
+
address@hidden -I @var{ign}
+More files to ignore (! to reset). See
address@hidden options}.
+
address@hidden -W @var{spec}
+More wrappers. See @ref{import options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden init
+Create a @sc{cvs} repository if it doesn't exist. See
address@hidden a repository}.
+
address@hidden ------------------------------------------------------------
address@hidden kserver
+Kerberos authenticated server.
+See @ref{Kerberos authenticated}.
+
address@hidden ------------------------------------------------------------
address@hidden log address@hidden address@hidden@dots{}]
+Print out history information for files. See @ref{log}.
+
address@hidden @code
address@hidden -b
+Only list revisions on the default branch. See @ref{log options}.
+
address@hidden -d @var{dates}
+Specify dates (@var{d1}<@var{d2} for range, @var{d} for
+latest before). See @ref{log options}.
+
address@hidden -h
+Only print header. See @ref{log options}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -N
+Do not list tags. See @ref{log options}.
+
address@hidden -R
+Only print name of RCS file. See @ref{log options}.
+
address@hidden address@hidden
+Only list revisions @var{revs}. See @ref{log options}.
+
address@hidden -s @var{states}
+Only list revisions with specified states. See @ref{log options}.
+
address@hidden -t
+Only print header and descriptive text. See @ref{log
+options}.
+
address@hidden address@hidden
+Only list revisions checked in by specified logins. See @ref{log options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden login
+Prompt for password for authenticating server. See
address@hidden authentication client}.
+
address@hidden ------------------------------------------------------------
address@hidden logout
+Remove stored password for authenticating server. See
address@hidden authentication client}.
+
address@hidden ------------------------------------------------------------
address@hidden pserver
+Password authenticated server.
+See @ref{Password authentication server}.
+
address@hidden ------------------------------------------------------------
address@hidden rannotate address@hidden address@hidden@dots{}]
+Show last revision where each line was modified. See
address@hidden
+
address@hidden @code
address@hidden -D @var{date}
+Annotate the most recent revision no later than
address@hidden See @ref{Common options}.
+
address@hidden -F
+Force annotation of binary files. (Without this option,
+binary files are skipped with a message.)
+
address@hidden -f
+Use head revision if tag/date not found. See
address@hidden options}.
+
address@hidden -l
+Local; run only in current working directory. @xref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive behavior}.
+
address@hidden -r @var{tag}
+Annotate revision @var{tag}. See @ref{Common options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden rdiff address@hidden @address@hidden
+Show differences between releases. See @ref{rdiff}.
+
address@hidden @code
address@hidden -c
+Context diff output format (default). See @ref{rdiff options}.
+
address@hidden -D @var{date}
+Select revisions based on @var{date}. See @ref{Common options}.
+
address@hidden -f
+Use head revision if tag/date not found. See
address@hidden options}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{rev}
+Select revisions based on @var{rev}. See @ref{Common options}.
+
address@hidden -s
+Short patch - one liner per file. See @ref{rdiff options}.
+
address@hidden -t
+Top two diffs - last change made to the file. See
address@hidden options}.
+
address@hidden -u
+Unidiff output format. See @ref{rdiff options}.
+
address@hidden -V @var{vers}
+Use RCS Version @var{vers} for keyword expansion (obsolete). See
address@hidden options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden release address@hidden @var{directory}
+Indicate that a directory is no longer in use. See
address@hidden
+
address@hidden @code
address@hidden -d
+Delete the given directory. See @ref{release options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden remove address@hidden address@hidden@dots{}]
+Remove an entry from the repository. See @ref{Removing files}.
+
address@hidden @code
address@hidden -f
+Delete the file before removing it. See @ref{Removing files}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden rlog address@hidden address@hidden@dots{}]
+Print out history information for modules. See @ref{log}.
+
address@hidden @code
address@hidden -b
+Only list revisions on the default branch. See @ref{log options}.
+
address@hidden -d @var{dates}
+Specify dates (@var{d1}<@var{d2} for range, @var{d} for
+latest before). See @ref{log options}.
+
address@hidden -h
+Only print header. See @ref{log options}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -N
+Do not list tags. See @ref{log options}.
+
address@hidden -R
+Only print name of RCS file. See @ref{log options}.
+
address@hidden address@hidden
+Only list revisions @var{revs}. See @ref{log options}.
+
address@hidden -s @var{states}
+Only list revisions with specified states. See @ref{log options}.
+
address@hidden -t
+Only print header and descriptive text. See @ref{log options}.
+
address@hidden address@hidden
+Only list revisions checked in by specified logins. See @ref{log options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden rtag address@hidden @var{tag} @address@hidden
+Add a symbolic tag to a module.
+See @ref{Revisions} and @ref{Branching and merging}.
+
address@hidden @code
address@hidden -a
+Clear tag from removed files that would not otherwise
+be tagged. See @ref{Tagging add/remove}.
+
address@hidden -b
+Create a branch named @var{tag}. See @ref{Branching and merging}.
+
address@hidden -B
+Used in conjunction with -F or -d, enables movement and deletion of
+branch tags. Use with extreme caution.
+
address@hidden -D @var{date}
+Tag revisions as of @var{date}. See @ref{Tagging by date/tag}.
+
address@hidden -d
+Delete @var{tag}. See @ref{Modifying tags}.
+
address@hidden -F
+Move @var{tag} if it already exists. See @ref{Modifying tags}.
+
address@hidden -f
+Force a head revision match if tag/date not found.
+See @ref{Tagging by date/tag}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -n
+No execution of tag program. See @ref{Common options}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{rev}
+Tag existing tag @var{rev}. See @ref{Tagging by date/tag}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden server
+Rsh server. See @ref{Connecting via rsh}.
+
address@hidden ------------------------------------------------------------
address@hidden status address@hidden @address@hidden
+Display status information in a working directory. See
address@hidden status}.
+
address@hidden @code
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -v
+Include tag information for file. See @ref{Tags}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden tag address@hidden @var{tag} address@hidden@dots{}]
+Add a symbolic tag to checked out version of files.
+See @ref{Revisions} and @ref{Branching and merging}.
+
address@hidden @code
address@hidden -b
+Create a branch named @var{tag}. See @ref{Branching and merging}.
+
address@hidden -c
+Check that working files are unmodified. See
address@hidden the working directory}.
+
address@hidden -D @var{date}
+Tag revisions as of @var{date}. See @ref{Tagging by date/tag}.
+
address@hidden -d
+Delete @var{tag}. See @ref{Modifying tags}.
+
address@hidden -F
+Move @var{tag} if it already exists. See @ref{Modifying tags}.
+
address@hidden -f
+Force a head revision match if tag/date not found.
+See @ref{Tagging by date/tag}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{rev}
+Tag existing tag @var{rev}. See @ref{Tagging by date/tag}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden unedit address@hidden address@hidden@dots{}]
+Undo an edit command. See @ref{Editing files}.
+
address@hidden @code
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive behavior}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden update address@hidden address@hidden@dots{}]
+Bring work tree in sync with repository. See
address@hidden
+
address@hidden @code
address@hidden -A
+Reset any sticky tags/date/options. See @ref{Sticky
+tags} and @ref{Keyword substitution}.
+
address@hidden -C
+Overwrite locally modified files with clean copies from
+the repository (the modified file is saved in
address@hidden@address@hidden, however).
+
address@hidden -D @var{date}
+Check out revisions as of @var{date} (is sticky). See
address@hidden options}.
+
address@hidden -d
+Create directories. See @ref{update options}.
+
address@hidden -f
+Use head revision if tag/date not found. See
address@hidden options}.
+
address@hidden -I @var{ign}
+More files to ignore (! to reset). See
address@hidden options}.
+
address@hidden Probably want to use rev1/rev2 style like for diff
address@hidden -r. Here and in on-line help.
address@hidden -j @var{rev}
+Merge in changes. See @ref{update options}.
+
address@hidden -k @var{kflag}
+Use @var{kflag} keyword expansion. See
address@hidden modes}.
+
address@hidden -l
+Local; run only in current working directory. @xref{Recursive behavior}.
+
address@hidden -P
+Prune empty directories. See @ref{Moving directories}.
+
address@hidden -p
+Check out files to standard output (avoids
+stickiness). See @ref{update options}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{tag}
+Checkout revision @var{tag} (is sticky). See @ref{Common options}.
+
address@hidden -W @var{spec}
+More wrappers. See @ref{import options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden version
address@hidden version (subcommand)
+
+Display the version of @sc{cvs} being used. If the repository
+is remote, display both the client and server versions.
+
address@hidden ------------------------------------------------------------
address@hidden watch [on|off|add|remove] address@hidden address@hidden@dots{}]
+
+on/off: turn on/off read-only checkouts of files. See
address@hidden a watch}.
+
+add/remove: add or remove notification on actions. See
address@hidden Notified}.
+
address@hidden @code
address@hidden -a @var{actions}
+Specify actions for temporary watch, where
address@hidden is @code{edit}, @code{unedit},
address@hidden, @code{all}, or @code{none}. See
address@hidden files}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden watchers address@hidden address@hidden@dots{}]
+See who is watching a file. See @ref{Watch information}.
+
address@hidden @code
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
address@hidden table
+
address@hidden table
+
address@hidden
---------------------------------------------------------------------
address@hidden Administrative files
address@hidden Reference manual for Administrative files
address@hidden Administrative files (reference)
address@hidden Files, reference manual
address@hidden Reference manual (files)
address@hidden CVSROOT (file)
+
address@hidden FIXME? Somewhere there needs to be a more "how-to"
address@hidden guide to writing these. I think the triggers
address@hidden (commitinfo, loginfo, taginfo, &c) are perhaps a
address@hidden different case than files like modules. One
address@hidden particular issue that people sometimes are
address@hidden (unnecessarily?) worried about is performance, and
address@hidden the impact of writing in perl or sh or ____.
+Inside the repository, in the directory
address@hidden/CVSROOT}, there are a number of
+supportive files for @sc{cvs}. You can use @sc{cvs} in a limited
+fashion without any of them, but if they are set up
+properly they can help make life easier. For a
+discussion of how to edit them, see @ref{Intro
+administrative files}.
+
+The most important of these files is the @file{modules}
+file, which defines the modules inside the repository.
+
address@hidden
+* modules:: Defining modules
+* Wrappers:: Specify binary-ness based on file name
+* commit files:: The commit support files (commitinfo,
+ verifymsg, editinfo, loginfo)
+* rcsinfo:: Templates for the log messages
+* cvsignore:: Ignoring files via cvsignore
+* checkoutlist:: Adding your own administrative files
+* history file:: History information
+* Variables:: Various variables are expanded
+* config:: Miscellaneous CVS configuration
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden modules
address@hidden The modules file
address@hidden Modules (admin file)
address@hidden Defining modules (reference manual)
+
+The @file{modules} file records your definitions of
+names for collections of source code. @sc{cvs} will
+use these definitions if you use @sc{cvs} to update the
+modules file (use normal commands like @code{add},
address@hidden, etc).
+
+The @file{modules} file may contain blank lines and
+comments (lines beginning with @samp{#}) as well as
+module definitions. Long lines can be continued on the
+next line by specifying a backslash (@samp{\}) as the
+last character on the line.
+
+There are three basic types of modules: alias modules,
+regular modules, and ampersand modules. The difference
+between them is the way that they map files in the
+repository to files in the working directory. In all
+of the following examples, the top-level repository
+contains a directory called @file{first-dir}, which
+contains two files, @file{file1} and @file{file2}, and a
+directory @file{sdir}. @file{first-dir/sdir} contains
+a file @file{sfile}.
+
address@hidden FIXME: should test all the examples in this section.
+
address@hidden
+* Alias modules:: The simplest kind of module
+* Regular modules::
+* Ampersand modules::
+* Excluding directories:: Excluding directories from a module
+* Module options:: Regular and ampersand modules can take options
+* Module program options:: How the modules ``program options'' programs
+ are run.
address@hidden menu
+
address@hidden Alias modules
address@hidden Alias modules
address@hidden Alias modules
address@hidden -a, in modules file
+
+Alias modules are the simplest kind of module:
+
address@hidden @code
address@hidden @var{mname} -a @address@hidden
+This represents the simplest way of defining a module
address@hidden The @samp{-a} flags the definition as a
+simple alias: @sc{cvs} will treat any use of @var{mname} (as
+a command argument) as if the list of names
address@hidden had been specified instead.
address@hidden may contain either other module names or
+paths. When you use paths in aliases, @code{checkout}
+creates all intermediate directories in the working
+directory, just as if the path had been specified
+explicitly in the @sc{cvs} arguments.
address@hidden table
+
+For example, if the modules file contains:
+
address@hidden
+amodule -a first-dir
address@hidden example
+
address@hidden
+then the following two commands are equivalent:
+
address@hidden
+$ cvs co amodule
+$ cvs co first-dir
address@hidden example
+
address@hidden
+and they each would provide output such as:
+
address@hidden
+cvs checkout: Updating first-dir
+U first-dir/file1
+U first-dir/file2
+cvs checkout: Updating first-dir/sdir
+U first-dir/sdir/sfile
address@hidden example
+
address@hidden Regular modules
address@hidden Regular modules
address@hidden Regular modules
+
address@hidden @code
address@hidden @var{mname} [ options ] @var{dir} [ @address@hidden ]
+In the simplest case, this form of module definition
+reduces to @address@hidden @var{dir}}. This defines
+all the files in directory @var{dir} as module mname.
address@hidden is a relative path (from @code{$CVSROOT}) to a
+directory of source in the source repository. In this
+case, on checkout, a single directory called
address@hidden is created as a working directory; no
+intermediate directory levels are used by default, even
+if @var{dir} was a path involving several directory
+levels.
address@hidden table
+
+For example, if a module is defined by:
+
address@hidden
+regmodule first-dir
address@hidden example
+
address@hidden
+then regmodule will contain the files from first-dir:
+
address@hidden
+$ cvs co regmodule
+cvs checkout: Updating regmodule
+U regmodule/file1
+U regmodule/file2
+cvs checkout: Updating regmodule/sdir
+U regmodule/sdir/sfile
+$
address@hidden example
+
+By explicitly specifying files in the module definition
+after @var{dir}, you can select particular files from
+directory @var{dir}. Here is
+an example:
+
address@hidden
+regfiles first-dir/sdir sfile
address@hidden example
+
address@hidden
+With this definition, getting the regfiles module
+will create a single working directory
address@hidden containing the file listed, which
+comes from a directory deeper
+in the @sc{cvs} source repository:
+
address@hidden
+$ cvs co regfiles
+U regfiles/sfile
+$
address@hidden example
+
address@hidden Ampersand modules
address@hidden Ampersand modules
address@hidden Ampersand modules
address@hidden &, in modules file
+
+A module definition can refer to other modules by
+including @samp{&@var{module}} in its definition.
address@hidden
address@hidden [ options ] @var{&address@hidden
address@hidden example
+
+Then getting the module creates a subdirectory for each such
+module, in the directory containing the module. For
+example, if modules contains
+
address@hidden
+ampermod &first-dir
address@hidden example
+
address@hidden
+then a checkout will create an @code{ampermod} directory
+which contains a directory called @code{first-dir},
+which in turns contains all the directories and files
+which live there. For example, the command
+
address@hidden
+$ cvs co ampermod
address@hidden example
+
address@hidden
+will create the following files:
+
address@hidden
+ampermod/first-dir/file1
+ampermod/first-dir/file2
+ampermod/first-dir/sdir/sfile
address@hidden example
+
+There is one quirk/bug: the messages that @sc{cvs}
+prints omit the @file{ampermod}, and thus do not
+correctly display the location to which it is checking
+out the files:
+
address@hidden
+$ cvs co ampermod
+cvs checkout: Updating first-dir
+U first-dir/file1
+U first-dir/file2
+cvs checkout: Updating first-dir/sdir
+U first-dir/sdir/sfile
+$
address@hidden example
+
+Do not rely on this buggy behavior; it may get fixed in
+a future release of @sc{cvs}.
+
address@hidden FIXCVS: What happens if regular and & modules are
address@hidden combined, as in "ampermodule first-dir &second-dir"?
address@hidden When I tried it, it seemed to just ignore the
address@hidden "first-dir". I think perhaps it should be an error
address@hidden (but this needs further investigation).
address@hidden In addition to discussing what each one does, we
address@hidden should put in a few words about why you would use one or
address@hidden the other in various situations.
+
address@hidden Excluding directories
address@hidden Excluding directories
address@hidden Excluding directories, in modules file
address@hidden !, in modules file
+
+An alias module may exclude particular directories from
+other modules by using an exclamation mark (@samp{!})
+before the name of each directory to be excluded.
+
+For example, if the modules file contains:
+
address@hidden
+exmodule -a !first-dir/sdir first-dir
address@hidden example
+
address@hidden
+then checking out the module @samp{exmodule} will check
+out everything in @samp{first-dir} except any files in
+the subdirectory @samp{first-dir/sdir}.
address@hidden Note that the "!first-dir/sdir" sometimes must be listed
address@hidden before "first-dir". That seems like a probable bug, in which
address@hidden case perhaps it should be fixed (to allow either
address@hidden order) rather than documented. See modules4 in testsuite.
+
address@hidden Module options
address@hidden Module options
address@hidden Options, in modules file
+
+Either regular modules or ampersand modules can contain
+options, which supply additional information concerning
+the module.
+
address@hidden @code
address@hidden -d, in modules file
address@hidden -d @var{name}
+Name the working directory something other than the
+module name.
address@hidden FIXME: Needs a bunch of examples, analogous to the
address@hidden examples for alias, regular, and ampersand modules
address@hidden which show where the files go without -d.
+
address@hidden Export program
address@hidden -e, in modules file
address@hidden -e @var{prog}
+Specify a program @var{prog} to run whenever files in a
+module are exported. @var{prog} runs with a single
+argument, the module name.
address@hidden FIXME: Is it run on server? client?
+
address@hidden Checkout program
address@hidden -o, in modules file
address@hidden -o @var{prog}
+Specify a program @var{prog} to run whenever files in a
+module are checked out. @var{prog} runs with a single
+argument, the module name. See @ref{Module program options} for
+information on how @var{prog} is called.
address@hidden FIXME: Is it run on server? client?
+
address@hidden Status of a module
address@hidden Module status
address@hidden -s, in modules file
address@hidden -s @var{status}
+Assign a status to the module. When the module file is
+printed with @samp{cvs checkout -s} the modules are
+sorted according to primarily module status, and
+secondarily according to the module name. This option
+has no other meaning. You can use this option for
+several things besides status: for instance, list the
+person that is responsible for this module.
+
address@hidden Tag program
address@hidden -t, in modules file
address@hidden -t @var{prog}
+Specify a program @var{prog} to run whenever files in a
+module are tagged with @code{rtag}. @var{prog} runs
+with two arguments: the module name and the symbolic
+tag specified to @code{rtag}. It is not run
+when @code{tag} is executed. Generally you will find
+that taginfo is a better solution (@pxref{user-defined logging}).
address@hidden FIXME: Is it run on server? client?
address@hidden Problems with -t include:
address@hidden * It is run after the tag not before
address@hidden * It doesn't get passed all the information that
address@hidden taginfo does ("mov", &c).
address@hidden * It only is run for rtag, not tag.
address@hidden table
+
+You should also see @pxref{Module program options} about how the
+``program options'' programs are run.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
+
address@hidden Module program options
address@hidden How the modules file ``program options'' programs are run
address@hidden Modules file program options
address@hidden -t, in modules file
address@hidden -o, in modules file
address@hidden -e, in modules file
+
address@hidden
+For checkout, rtag, and export, the program is server-based, and as such the
+following applies:-
+
+If using remote access methods (pserver, ext, etc.),
address@hidden will execute this program on the server from a temporary
+directory. The path is searched for this program.
+
+If using ``local access'' (on a local or remote NFS file system, i.e.
+repository set just to a path),
+the program will be executed from the newly checked-out tree, if
+found there, or alternatively searched for in the path if not.
+
+The programs are all run after the operation has effectively
+completed.
+
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Wrappers
address@hidden The cvswrappers file
address@hidden cvswrappers (admin file)
address@hidden CVSWRAPPERS, environment variable
address@hidden Wrappers
+
address@hidden FIXME: need some better way of separating this out
address@hidden by functionality. -m is
address@hidden one feature, and -k is a another. And this discussion
address@hidden should be better motivated (e.g. start with the
address@hidden problems, then explain how the feature solves it).
+
+Wrappers refers to a @sc{cvs} feature which lets you
+control certain settings based on the name of the file
+which is being operated on. The settings are @samp{-k}
+for binary files, and @samp{-m} for nonmergeable text
+files.
+
+The @samp{-m} option
+specifies the merge methodology that should be used when
+a non-binary file is updated. @code{MERGE} means the usual
address@hidden behavior: try to merge the files. @code{COPY}
+means that @code{cvs update} will refuse to merge
+files, as it also does for files specified as binary
+with @samp{-kb} (but if the file is specified as
+binary, there is no need to specify @samp{-m 'COPY'}).
address@hidden will provide the user with the
+two versions of the files, and require the user using
+mechanisms outside @sc{cvs}, to insert any necessary
+changes.
+
address@hidden: do not use @code{COPY} with
address@hidden 1.9 or earlier - such versions of @sc{cvs} will
+copy one version of your file over the other, wiping
+out the previous contents.}
address@hidden Ordinarily we don't document the behavior of old
address@hidden versions. But this one is so dangerous, I think we
address@hidden must. I almost renamed it to -m 'NOMERGE' so we
address@hidden could say "never use -m 'COPY'".
+The @samp{-m} wrapper option only affects behavior when
+merging is done on update; it does not affect how files
+are stored. See @ref{Binary files}, for more on
+binary files.
+
+The basic format of the file @file{cvswrappers} is:
+
address@hidden FIXME: @example is all wrong for this. Use @deffn or
address@hidden something more sensible.
address@hidden
+wildcard [option value][option value]...
+
+where option is one of
+-m update methodology value: MERGE or COPY
+-k keyword expansion value: expansion mode
+
+and value is a single-quote delimited value.
address@hidden example
+
+
address@hidden FIXME: We don't document -W or point to where it is
address@hidden documented. Or .cvswrappers.
+For example, the following command imports a
+directory, treating files whose name ends in
address@hidden as binary:
+
address@hidden
+cvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag
address@hidden example
+
address@hidden Another good example, would be storing files
address@hidden (e.g. binary files) compressed in the repository.
address@hidden ::::::::::::::::::
address@hidden cvswrappers
address@hidden ::::::::::::::::::
address@hidden *.t12 -m 'COPY'
address@hidden *.t[0-9][0-9] -f 'gunzipcp %s' -t 'gzipcp %s %s' -m 'COPY'
address@hidden
address@hidden ::::::::::::::::::
address@hidden gunzipcp
address@hidden ::::::::::::::::::
address@hidden :
address@hidden [ -f $1 ] || exit 1
address@hidden zcat $1 > /tmp/.#$1.$$
address@hidden mv /tmp/.#$1.$$ $1
address@hidden
address@hidden ::::::::::::::::::
address@hidden gzipcp
address@hidden ::::::::::::::::::
address@hidden :
address@hidden DIRNAME=`echo $1 | sed -e "s|/.*/||g"`
address@hidden if [ ! -d $DIRNAME ] ; then
address@hidden DIRNAME=`echo $1 | sed -e "s|.*/||g"`
address@hidden fi
address@hidden gzip -c $DIRNAME > $2
address@hidden One catch--"cvs diff" will not invoke the wrappers
address@hidden (probably a CVS bug, although I haven't thought it out).
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden commit files
address@hidden The commit support files
address@hidden Committing, administrative support files
+
+The @samp{-i} flag in the @file{modules} file can be
+used to run a certain program whenever files are
+committed (@pxref{modules}). The files described in
+this section provide other, more flexible, ways to run
+programs whenever something is committed.
+
+There are three kind of programs that can be run on
+commit. They are specified in files in the repository,
+as described below. The following table summarizes the
+file names and the purpose of the corresponding
+programs.
+
address@hidden @file
address@hidden commitinfo
+The program is responsible for checking that the commit
+is allowed. If it exits with a non-zero exit status
+the commit will be aborted.
+
address@hidden verifymsg
+The specified program is used to evaluate the log message,
+and possibly verify that it contains all required
+fields. This is most useful in combination with the
address@hidden file, which can hold a log message
+template (@pxref{rcsinfo}).
+
address@hidden editinfo
+The specified program is used to edit the log message,
+and possibly verify that it contains all required
+fields. This is most useful in combination with the
address@hidden file, which can hold a log message
+template (@pxref{rcsinfo}). (obsolete)
+
address@hidden loginfo
+The specified program is called when the commit is
+complete. It receives the log message and some
+additional information and can store the log message in
+a file, or mail it to appropriate persons, or maybe
+post it to a local newsgroup, address@hidden Your
+imagination is the limit!
address@hidden table
+
address@hidden
+* syntax:: The common syntax
+* commitinfo:: Pre-commit checking
+* verifymsg:: How are log messages evaluated?
+* editinfo:: Specifying how log messages are created
+ (obsolete)
+* loginfo:: Where should log messages be sent?
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden syntax
address@hidden The common syntax
address@hidden Info files (syntax)
address@hidden Syntax of info files
address@hidden Common syntax of info files
+
address@hidden FIXME: having this so totally separate from the
address@hidden Variables node is rather bogus.
+
+The administrative files such as @file{commitinfo},
address@hidden, @file{rcsinfo}, @file{verifymsg}, etc.,
+all have a common format. The purpose of the files are
+described later on. The common syntax is described
+here.
+
address@hidden Regular expression syntax
+Each line contains the following:
address@hidden @bullet
address@hidden
address@hidden Say anything about DEFAULT and ALL? Right now we
address@hidden leave that to the description of each file (and in fact
address@hidden the practice is inconsistent which is really annoying).
+A regular expression. This is a basic regular
+expression in the syntax used by GNU emacs.
address@hidden FIXME: What we probably should be saying is "POSIX Basic
address@hidden Regular Expression with the following extensions (`\('
address@hidden `\|' '+' etc)"
address@hidden rather than define it with reference to emacs.
address@hidden The reference to emacs is not strictly speaking
address@hidden true, as we don't support \=, \s, or \S. Also it isn't
address@hidden clear we should document and/or promise to continue to
address@hidden support all the obscure emacs extensions like \<.
address@hidden Also need to better cite (or include) full
address@hidden documentation for the syntax.
address@hidden Also see comment in configure.in about what happens to the
address@hidden syntax if we pick up a system-supplied regexp matcher.
+
address@hidden
+A whitespace separator---one or more spaces and/or tabs.
+
address@hidden
+A file name or command-line template.
address@hidden itemize
+
address@hidden
+Blank lines are ignored. Lines that start with the
+character @samp{#} are treated as comments. Long lines
+unfortunately can @emph{not} be broken in two parts in
+any way.
+
+The first regular expression that matches the current
+directory name in the repository is used. The rest of the line
+is used as a file name or command-line as appropriate.
+
address@hidden FIXME: need an example. In particular, show what
address@hidden the regular expression is matched against (one
address@hidden ordinarily clueful person got confused about whether it
address@hidden includes the filename--"directory name" above should be
address@hidden unambiguous but there is nothing like an example to
address@hidden confirm people's understanding of this sort of thing).
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden commitinfo
address@hidden Commitinfo
address@hidden @file{commitinfo}
address@hidden Commits, precommit verification of
address@hidden Precommit checking
+
+The @file{commitinfo} file defines programs to execute
+whenever @samp{cvs commit} is about to execute. These
+programs are used for pre-commit checking to verify
+that the modified, added and removed files are really
+ready to be committed. This could be used, for
+instance, to verify that the changed files conform to
+to your site's standards for coding practice.
+
+As mentioned earlier, each line in the
address@hidden file consists of a regular expression
+and a command-line template. The template can include
+a program name and any number of arguments you wish to
+supply to it. The full path to the current source
+repository is appended to the template, followed by the
+file names of any files involved in the commit (added,
+removed, and modified files).
+
address@hidden Exit status, of commitinfo
+The first line with a regular expression matching the
+directory within the repository will be used. If the
+command returns a non-zero exit status the commit will
+be aborted.
address@hidden FIXME: need example(s) of what "directory within the
address@hidden repository" means.
+
address@hidden DEFAULT in commitinfo
+If the repository name does not match any of the
+regular expressions in this file, the @samp{DEFAULT}
+line is used, if it is specified.
+
address@hidden ALL in commitinfo
+All occurrences of the name @samp{ALL} appearing as a
+regular expression are used in addition to the first
+matching regular expression or the name @samp{DEFAULT}.
+
address@hidden @file{commitinfo}, working directory
address@hidden @file{commitinfo}, command environment
+The command will be run in the root of the workspace
+containing the new versions of any files the user would like
+to modify (commit), @emph{or in a copy of the workspace on
+the server (@pxref{Remote repositories})}. If a file is
+being removed, there will be no copy of the file under the
+current directory. If a file is being added, there will be
+no corresponding archive file in the repository unless the
+file is being resurrected.
+
+Note that both the repository directory and the corresponding
+Attic (@pxref{Attic}) directory may need to be checked to
+locate the archive file corresponding to any given file being
+committed. Much of the information about the specific commit
+request being made, including the destination branch, commit
+message, and command line options specified, is not available
+to the command.
+
address@hidden FIXME: should discuss using commitinfo to control
address@hidden who has checkin access to what (e.g. Joe can check into
address@hidden directories a, b, and c, and Mary can check into
address@hidden directories b, c, and d--note this case cannot be
address@hidden conveniently handled with unix groups). Of course,
address@hidden adding a new set of features to CVS might be a more
address@hidden natural way to fix this problem than telling people to
address@hidden use commitinfo.
address@hidden FIXME: Should make some reference, especially in
address@hidden the context of controlling who has access, to the fact
address@hidden that commitinfo can be circumvented. Perhaps
address@hidden mention SETXID (but has it been carefully examined
address@hidden for holes?). This fits in with the discussion of
address@hidden general CVS security in "Password authentication
address@hidden security" (the bit which is not pserver-specific).
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden verifymsg
address@hidden Verifying log messages
address@hidden @file{verifymsg} (admin file)
address@hidden Log message, verifying
+
+Once you have entered a log message, you can evaluate
+that message to check for specific content, such as
+a bug ID. Use the @file{verifymsg} file to
+specify a program that is used to verify the log message.
+This program could be a simple script that checks
+that the entered message contains the required fields.
+
+The @file{verifymsg} file is often most useful together
+with the @file{rcsinfo} file, which can be used to
+specify a log message template.
+
+Each line in the @file{verifymsg} file consists of a
+regular expression and a command-line template. The
+template must include a program name, and can include
+any number of arguments. The full path to the current
+log message template file is appended to the template.
+
+One thing that should be noted is that the @samp{ALL}
+keyword is not supported. If more than one matching
+line is found, the first one is used. This can be
+useful for specifying a default verification script in a
+directory, and then overriding it in a subdirectory.
+
address@hidden DEFAULT in @file{verifymsg}
+If the repository name does not match any of the
+regular expressions in this file, the @samp{DEFAULT}
+line is used, if it is specified.
+
address@hidden Exit status, of @file{verifymsg}
+If the verification script exits with a non-zero exit status,
+the commit is aborted.
+
address@hidden @file{verifymsg}, changing the log message
+In the default configuration, CVS allows the
+verification script to change the log message. This is
+controlled via the RereadLogAfterVerify CVSROOT/config
+option.
+
+When @samp{RereadLogAfterVerify=always} or
address@hidden, the log message will
+either always be reread after the verification script
+is run or reread only if the log message file status
+has changed.
+
address@hidden, for more on CVSROOT/config options.
+
+It is NOT a good idea for a @file{verifymsg} script to
+interact directly with the user in the various
+client/server methods. For the @code{pserver} method,
+there is no protocol support for communicating between
address@hidden and the client on the remote end. For the
address@hidden and @code{server} methods, it is possible
+for CVS to become confused by the characters going
+along the same channel as the CVS protocol
+messages. See @ref{Remote repositories}, for more
+information on client/server setups. In addition, at the time
+the @file{verifymsg} script runs, the CVS
+server has locks in place in the repository. If control is
+returned to the user here then other users may be stuck waiting
+for access to the repository.
+
+This option can be useful if you find yourself using an
+rcstemplate that needs to be modified to remove empty
+elements or to fill in default values. It can also be
+useful if the rcstemplate has changed in the repository
+and the CVS/Template was not updated, but is able to be
+adapted to the new format by the verification script
+that is run by @file{verifymsg}.
+
+An example of an update might be to change all
+occurrences of 'BugId:' to be 'DefectId:' (which can be
+useful if the rcstemplate has recently been changed and
+there are still checked-out user trees with cached
+copies in the CVS/Template file of the older version).
+
+Another example of an update might be to delete a line
+that contains 'BugID: none' from the log message after
+validation of that value as being allowed is made.
+
+The following is a little silly example of a
address@hidden file, together with the corresponding
address@hidden file, the log message template and an
+verification script. We begin with the log message template.
+We want to always record a bug-id number on the first
+line of the log message. The rest of log message is
+free text. The following template is found in the file
address@hidden/usr/cvssupport/tc.template}.
+
address@hidden
+BugId:
address@hidden example
+
+The script @file{/usr/cvssupport/bugid.verify} is used to
+evaluate the log message.
+
address@hidden
+#!/bin/sh
+#
+# bugid.verify filename
+#
+# Verify that the log message contains a valid bugid
+# on the first line.
+#
+if head -1 < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then
+ exit 0
+elif head -1 < $1 | grep '^BugId:[ ]*none$' > /dev/null; then
+ # It is okay to allow commits with 'BugId: none',
+ # but do not put that text into the real log message.
+ grep -v '^BugId:[ ]*none$' > $1.rewrite
+ mv $1.rewrite $1
+ exit 0
+else
+ echo "No BugId found."
+ exit 1
+fi
address@hidden example
+
+The @file{verifymsg} file contains this line:
+
address@hidden
+^tc /usr/cvssupport/bugid.verify
address@hidden example
+
+The @file{rcsinfo} file contains this line:
+
address@hidden
+^tc /usr/cvssupport/tc.template
address@hidden example
+
+The @file{config} file contains this line:
+
address@hidden
+RereadLogAfterVerify=always
address@hidden example
+
+
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden editinfo
address@hidden Editinfo
address@hidden editinfo (admin file)
address@hidden Editor, specifying per module
address@hidden Per-module editor
address@hidden Log messages, editing
+
address@hidden: The @file{editinfo} feature has been
+rendered obsolete. To set a default editor for log
+messages use the @code{CVSEDITOR}, @code{EDITOR} environment variables
+(@pxref{Environment variables}) or the @samp{-e} global
+option (@pxref{Global options}). See @ref{verifymsg},
+for information on the use of the @file{verifymsg}
+feature for evaluating log messages.}
+
+If you want to make sure that all log messages look the
+same way, you can use the @file{editinfo} file to
+specify a program that is used to edit the log message.
+This program could be a custom-made editor that always
+enforces a certain style of the log message, or maybe a
+simple shell script that calls an editor, and checks
+that the entered message contains the required fields.
+
+If no matching line is found in the @file{editinfo}
+file, the editor specified in the environment variable
address@hidden is used instead. If that variable is
+not set, then the environment variable @code{$EDITOR}
+is used instead. If that variable is not
+set a default will be used. See @ref{Committing your changes}.
+
+The @file{editinfo} file is often most useful together
+with the @file{rcsinfo} file, which can be used to
+specify a log message template.
+
+Each line in the @file{editinfo} file consists of a
+regular expression and a command-line template. The
+template must include a program name, and can include
+any number of arguments. The full path to the current
+log message template file is appended to the template.
+
+One thing that should be noted is that the @samp{ALL}
+keyword is not supported. If more than one matching
+line is found, the first one is used. This can be
+useful for specifying a default edit script in a
+module, and then overriding it in a subdirectory.
+
address@hidden DEFAULT in editinfo
+If the repository name does not match any of the
+regular expressions in this file, the @samp{DEFAULT}
+line is used, if it is specified.
+
+If the edit script exits with a non-zero exit status,
+the commit is aborted.
+
+Note: when @sc{cvs} is accessing a remote repository,
+or when the @samp{-m} or @samp{-F} options to @code{cvs
+commit} are used, @file{editinfo} will not be consulted.
+There is no good workaround for this; use
address@hidden instead.
+
address@hidden
+* editinfo example:: Editinfo example
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden editinfo example
address@hidden Editinfo example
+
+The following is a little silly example of a
address@hidden file, together with the corresponding
address@hidden file, the log message template and an
+editor script. We begin with the log message template.
+We want to always record a bug-id number on the first
+line of the log message. The rest of log message is
+free text. The following template is found in the file
address@hidden/usr/cvssupport/tc.template}.
+
address@hidden
+BugId:
address@hidden example
+
+The script @file{/usr/cvssupport/bugid.edit} is used to
+edit the log message.
+
address@hidden
+#!/bin/sh
+#
+# bugid.edit filename
+#
+# Call $EDITOR on FILENAME, and verify that the
+# resulting file contains a valid bugid on the first
+# line.
+if [ "x$EDITOR" = "x" ]; then EDITOR=vi; fi
+if [ "x$CVSEDITOR" = "x" ]; then CVSEDITOR=$EDITOR; fi
+$CVSEDITOR $1
+until head -1|grep '^BugId:[ ]*[0-9][0-9]*$' < $1
+do echo -n "No BugId found. Edit again? ([y]/n)"
+ read ans
+ case address@hidden@} in
+ n*) exit 1;;
+ esac
+ $CVSEDITOR $1
+done
address@hidden example
+
+The @file{editinfo} file contains this line:
+
address@hidden
+^tc /usr/cvssupport/bugid.edit
address@hidden example
+
+The @file{rcsinfo} file contains this line:
+
address@hidden
+^tc /usr/cvssupport/tc.template
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden loginfo
address@hidden Loginfo
address@hidden loginfo (admin file)
address@hidden Storing log messages
address@hidden Mailing log messages
address@hidden Distributing log messages
address@hidden Log messages
+
address@hidden "cvs commit" is not quite right. What we
address@hidden mean is "when the repository gets changed" which
address@hidden also includes "cvs import" and "cvs add" on a directory.
+The @file{loginfo} file is used to control where
address@hidden commit} log information is sent. The first
+entry on a line is a regular expression which is tested
+against the directory that the change is being made to,
+relative to the @code{$CVSROOT}. If a match is found, then
+the remainder of the line is a filter program that
+should expect log information on its standard input.
+
+If the repository name does not match any of the
+regular expressions in this file, the @samp{DEFAULT}
+line is used, if it is specified.
+
+All occurrences of the name @samp{ALL} appearing as a
+regular expression are used in addition to the first
+matching regular expression or @samp{DEFAULT}.
+
+The first matching regular expression is used.
+
address@hidden files}, for a description of the syntax of
+the @file{loginfo} file.
+
+The user may specify a format string as
+part of the filter. The string is composed of a
address@hidden followed by a space, or followed by a single
+format character, or followed by a set of format
+characters surrounded by @address@hidden and @address@hidden as
+separators. The format characters are:
+
address@hidden @t
address@hidden s
+file name
address@hidden V
+old version number (pre-checkin)
address@hidden v
+new version number (post-checkin)
address@hidden table
+
+All other characters that appear in a format string
+expand to an empty field (commas separating fields are
+still provided).
+
+For example, some valid format strings are @samp{%},
address@hidden, @address@hidden@}}, and @address@hidden@}}.
+
+The output will be a space separated string of tokens enclosed in
+quotation marks (@t{"}).
+Any embedded dollar signs (@t{$}), backticks (@t{`}),
+backslashes (@t{\}), or quotation marks will be preceded
+by a backslash (this allows the shell to correctly parse it
+as a single string, regardless of the characters it contains).
+For backwards compatibility, the first
+token will be the repository subdirectory. The rest of the
+tokens will be comma-delimited lists of the information
+requested in the format string. For example, if
address@hidden/u/src/master/yoyodyne/tc} is the repository, @address@hidden@}}
+is the format string, and three files (@t{ChangeLog},
address@hidden, @t{foo.c}) were modified, the output
+might be:
+
address@hidden
+"yoyodyne/tc ChangeLog,1.1,1.2 Makefile,1.3,1.4 foo.c,1.12,1.13"
address@hidden example
+
+As another example, @address@hidden@}} means that only the
+name of the repository will be generated.
+
+Note: when @sc{cvs} is accessing a remote repository,
address@hidden will be run on the @emph{remote}
+(i.e., server) side, not the client side (@pxref{Remote
+repositories}).
+
address@hidden
+* loginfo example:: Loginfo example
+* Keeping a checked out copy:: Updating a tree on every checkin
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden loginfo example
address@hidden Loginfo example
+
+The following @file{loginfo} file, together with the
+tiny shell-script below, appends all log messages
+to the file @file{$CVSROOT/CVSROOT/commitlog},
+and any commits to the administrative files (inside
+the @file{CVSROOT} directory) are also logged in
address@hidden/usr/adm/cvsroot-log}.
+Commits to the @file{prog1} directory are mailed to @t{ceder}.
+
address@hidden FIXME: is it a CVS feature or bug that only the
address@hidden first matching line is used? It is documented
address@hidden above, but is it useful? For example, if we wanted
address@hidden to run both "cvs-log" and "Mail" for the CVSROOT
address@hidden directory, it is kind of awkward if
address@hidden only the first matching line is used.
address@hidden
+ALL /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog $USER
+^CVSROOT /usr/local/bin/cvs-log /usr/adm/cvsroot-log
+^prog1 Mail -s %s ceder
address@hidden example
+
+The shell-script @file{/usr/local/bin/cvs-log} looks
+like this:
+
address@hidden
+#!/bin/sh
+(echo "------------------------------------------------------";
+ echo -n $2" ";
+ date;
+ echo;
+ cat) >> $1
address@hidden example
+
address@hidden Keeping a checked out copy
address@hidden Keeping a checked out copy
+
address@hidden What other index entries? It seems like
address@hidden people might want to use a lot of different
address@hidden words for this functionality.
address@hidden Keeping a checked out copy
address@hidden Checked out copy, keeping
address@hidden Web pages, maintaining with CVS
+
+It is often useful to maintain a directory tree which
+contains files which correspond to the latest version
+in the repository. For example, other developers might
+want to refer to the latest sources without having to
+check them out, or you might be maintaining a web site
+with @sc{cvs} and want every checkin to cause the files
+used by the web server to be updated.
address@hidden Can we offer more details on the web example? Or
address@hidden point the user at how to figure it out? This text
address@hidden strikes me as sufficient for someone who already has
address@hidden some idea of what we mean but not enough for the naive
address@hidden user/sysadmin to understand it and set it up.
+
+The way to do this is by having loginfo invoke
address@hidden update}. Doing so in the naive way will
+cause a problem with locks, so the @code{cvs update}
+must be run in the background.
address@hidden Should we try to describe the problem with locks?
address@hidden It seems like a digression for someone who just
address@hidden wants to know how to make it work.
address@hidden Another choice which might work for a single file
address@hidden is to use "cvs -n update -p" which doesn't take
address@hidden out locks (I think) but I don't see many advantages
address@hidden of that and we might as well document something which
address@hidden works for multiple files.
+Here is an example for unix (this should all be on one line):
+
address@hidden
+^cyclic-pages (date; cat; (sleep 2; cd /u/www/local-docs;
+ cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1
address@hidden example
+
+This will cause checkins to repository directories
+starting with @code{cyclic-pages} to update the checked
+out tree in @file{/u/www/local-docs}.
address@hidden More info on some of the details? The "sleep 2" is
address@hidden so if we are lucky the lock will be gone by the time
address@hidden we start and we can wait 2 seconds instead of 30.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden rcsinfo
address@hidden Rcsinfo
address@hidden rcsinfo (admin file)
address@hidden Form for log message
address@hidden Log message template
address@hidden Template for log message
+
+The @file{rcsinfo} file can be used to specify a form to
+edit when filling out the commit log. The
address@hidden file has a syntax similar to the
address@hidden, @file{commitinfo} and @file{loginfo}
+files. @xref{syntax}. Unlike the other files the second
+part is @emph{not} a command-line template. Instead,
+the part after the regular expression should be a full pathname to
+a file containing the log message template.
+
+If the repository name does not match any of the
+regular expressions in this file, the @samp{DEFAULT}
+line is used, if it is specified.
+
+All occurrences of the name @samp{ALL} appearing as a
+regular expression are used in addition to the first
+matching regular expression or @samp{DEFAULT}.
+
address@hidden FIXME: should be offering advice, somewhere around
address@hidden here, about where to put the template file. The
address@hidden verifymsg example uses /usr/cvssupport but doesn't
address@hidden say anything about what that directory is for or
address@hidden whether it is hardwired into CVS or who creates
address@hidden it or anything. In particular we should say
address@hidden how to version control the template file. A
address@hidden probably better answer than the /usr/cvssupport
address@hidden stuff is to use checkoutlist (with xref to the
address@hidden checkoutlist doc).
address@hidden Also I am starting to see a connection between
address@hidden this and the Keeping a checked out copy node.
address@hidden Probably want to say something about that.
+The log message template will be used as a default log
+message. If you specify a log message with @samp{cvs
+commit -m @var{message}} or @samp{cvs commit -f
address@hidden that log message will override the
+template.
+
address@hidden, for an example @file{rcsinfo}
+file.
+
+When @sc{cvs} is accessing a remote repository,
+the contents of @file{rcsinfo} at the time a directory
+is first checked out will specify a template. This
+template will be updated on all @samp{cvs update}
+commands. It will also be added to new directories
+added with a @samp{cvs add new-directry} command.
+In versions of @sc{cvs} prior to version 1.12, the
address@hidden/Template} file was not updated. If the
address@hidden server is at version 1.12 or higher an older
+client may be used and the @file{CVS/Template} will
+be updated from the server.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden cvsignore
address@hidden Ignoring files via cvsignore
address@hidden cvsignore (admin file), global
address@hidden Global cvsignore
address@hidden Ignoring files
address@hidden -- This chapter should maybe be moved to the
address@hidden tutorial part of the manual?
+
+There are certain file names that frequently occur
+inside your working copy, but that you don't want to
+put under @sc{cvs} control. Examples are all the object
+files that you get while you compile your sources.
+Normally, when you run @samp{cvs update}, it prints a
+line for each file it encounters that it doesn't know
+about (@pxref{update output}).
+
address@hidden has a list of files (or sh(1) file name patterns)
+that it should ignore while running @code{update},
address@hidden and @code{release}.
address@hidden -- Are those the only three commands affected?
+This list is constructed in the following way.
+
address@hidden @bullet
address@hidden
+The list is initialized to include certain file name
+patterns: names associated with @sc{cvs}
+administration, or with other common source control
+systems; common names for patch files, object files,
+archive files, and editor backup files; and other names
+that are usually artifacts of assorted utilities.
+Currently, the default list of ignored file name
+patterns is:
+
address@hidden Ignored files
address@hidden Automatically ignored files
address@hidden
+ RCS SCCS CVS CVS.adm
+ RCSLOG cvslog.*
+ tags TAGS
+ .make.state .nse_depinfo
+ *~ #* .#* ,* _$* *$
+ *.old *.bak *.BAK *.orig *.rej .del-*
+ *.a *.olb *.o *.obj *.so *.exe
+ *.Z *.elc *.ln
+ core
address@hidden example
+
address@hidden
+The per-repository list in
address@hidden/CVSROOT/cvsignore} is appended to
+the list, if that file exists.
+
address@hidden
+The per-user list in @file{.cvsignore} in your home
+directory is appended to the list, if it exists.
+
address@hidden
+Any entries in the environment variable
address@hidden is appended to the list.
+
address@hidden
+Any @samp{-I} options given to @sc{cvs} is appended.
+
address@hidden
+As @sc{cvs} traverses through your directories, the contents
+of any @file{.cvsignore} will be appended to the list.
+The patterns found in @file{.cvsignore} are only valid
+for the directory that contains them, not for
+any sub-directories.
address@hidden itemize
+
+In any of the 5 places listed above, a single
+exclamation mark (@samp{!}) clears the ignore list.
+This can be used if you want to store any file which
+normally is ignored by @sc{cvs}.
+
+Specifying @samp{-I !} to @code{cvs import} will import
+everything, which is generally what you want to do if
+you are importing files from a pristine distribution or
+any other source which is known to not contain any
+extraneous files. However, looking at the rules above
+you will see there is a fly in the ointment; if the
+distribution contains any @file{.cvsignore} files, then
+the patterns from those files will be processed even if
address@hidden !} is specified. The only workaround is to
+remove the @file{.cvsignore} files in order to do the
+import. Because this is awkward, in the future
address@hidden !} might be modified to override
address@hidden files in each directory.
+
+Note that the syntax of the ignore files consists of a
+series of lines, each of which contains a space
+separated list of filenames. This offers no clean way
+to specify filenames which contain spaces, but you can
+use a workaround like @file{foo?bar} to match a file
+named @file{foo bar} (it also matches @file{fooxbar}
+and the like). Also note that there is currently no
+way to specify comments.
address@hidden FIXCVS? I don't _like_ this syntax at all, but
address@hidden changing it raises all the usual compatibility
address@hidden issues and I'm also not sure what to change it to.
+
address@hidden checkoutlist
address@hidden The checkoutlist file
address@hidden checkoutlist
+
+It may be helpful to use @sc{cvs} to maintain your own
+files in the @file{CVSROOT} directory. For example,
+suppose that you have a script @file{logcommit.pl}
+which you run by including the following line in the
address@hidden administrative file:
+
address@hidden
+ALL $CVSROOT/CVSROOT/logcommit.pl
address@hidden example
+
+To maintain @file{logcommit.pl} with @sc{cvs} you would
+add the following line to the @file{checkoutlist}
+administrative file:
+
address@hidden
+logcommit.pl
address@hidden example
+
+The format of @file{checkoutlist} is one line for each
+file that you want to maintain using @sc{cvs}, giving
+the name of the file.
+
+After setting up @file{checkoutlist} in this fashion,
+the files listed there will function just like
address@hidden's built-in administrative files. For example,
+when checking in one of the files you should get a
+message such as:
+
address@hidden
+cvs commit: Rebuilding administrative file database
address@hidden example
+
address@hidden
+and the checked out copy in the @file{CVSROOT}
+directory should be updated.
+
+Note that listing @file{passwd} (@pxref{Password
+authentication server}) in @file{checkoutlist} is not
+recommended for security reasons.
+
+For information about keeping a checkout out copy in a
+more general context than the one provided by
address@hidden, see @ref{Keeping a checked out
+copy}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden history file
address@hidden The history file
address@hidden History file
address@hidden Log information, saving
+
+The file @file{$CVSROOT/CVSROOT/history} is used
+to log information for the @code{history} command
+(@pxref{history}). This file must be created to turn
+on logging. This is done automatically if the
address@hidden init} command is used to set up the
+repository (@pxref{Creating a repository}).
+
+The file format of the @file{history} file is
+documented only in comments in the @sc{cvs} source
+code, but generally programs should use the @code{cvs
+history} command to access it anyway, in case the
+format changes with future releases of @sc{cvs}.
+
address@hidden Variables
address@hidden Expansions in administrative files
address@hidden Internal variables
address@hidden Variables
+
+Sometimes in writing an administrative file, you might
+want the file to be able to know various things based
+on environment @sc{cvs} is running in. There are
+several mechanisms to do that.
+
+To find the home directory of the user running @sc{cvs}
+(from the @code{HOME} environment variable), use
address@hidden followed by @samp{/} or the end of the line.
+Likewise for the home directory of @var{user}, use
address@hidden@var{user}}. These variables are expanded on
+the server machine, and don't get any reasonable
+expansion if pserver (@pxref{Password authenticated})
+is in use; therefore user variables (see below) may be
+a better choice to customize behavior based on the user
+running @sc{cvs}.
address@hidden Based on these limitations, should we deprecate ~?
address@hidden What is it good for? Are people using it?
+
+One may want to know about various pieces of
+information internal to @sc{cvs}. A @sc{cvs} internal
+variable has the syntax @address@hidden@address@hidden,
+where @var{variable} starts with a letter and consists
+of alphanumeric characters and @samp{_}. If the
+character following @var{variable} is a
+non-alphanumeric character other than @samp{_}, the
address@hidden@{} and @address@hidden can be omitted. The @sc{cvs}
+internal variables are:
+
address@hidden @code
address@hidden CVSROOT
address@hidden CVSROOT, internal variable
+This is the absolute path to the current @sc{cvs} root directory.
address@hidden, for a description of the various
+ways to specify this, but note that the internal
+variable contains just the directory and not any
+of the access method information.
+
address@hidden RCSBIN
address@hidden RCSBIN, internal variable
+In @sc{cvs} 1.9.18 and older, this specified the
+directory where @sc{cvs} was looking for @sc{rcs}
+programs. Because @sc{cvs} no longer runs @sc{rcs}
+programs, specifying this internal variable is now an
+error.
+
address@hidden CVSEDITOR
address@hidden CVSEDITOR, internal variable
address@hidden EDITOR
address@hidden EDITOR, internal variable
address@hidden VISUAL
address@hidden VISUAL, internal variable
+These all expand to the same value, which is the editor
+that @sc{cvs} is using. @xref{Global options}, for how
+to specify this.
+
address@hidden USER
address@hidden USER, internal variable
+Username of the user running @sc{cvs} (on the @sc{cvs}
+server machine).
+When using pserver, this is the user specified in the repository
+specification which need not be the same as the username the
+server is running as (@pxref{Password authentication server}).
+Do not confuse this with the environment variable of the same name.
address@hidden table
+
+If you want to pass a value to the administrative files
+which the user who is running @sc{cvs} can specify,
+use a user variable.
address@hidden User variables
+To expand a user variable, the
+administrative file contains
address@hidden@address@hidden@}}. To set a user variable,
+specify the global option @samp{-s} to @sc{cvs}, with
+argument @address@hidden@var{value}}. It may be
+particularly useful to specify this option via
address@hidden (@pxref{~/.cvsrc}).
+
+For example, if you want the administrative file to
+refer to a test directory you might create a user
+variable @code{TESTDIR}. Then if @sc{cvs} is invoked
+as
+
address@hidden
+cvs -s TESTDIR=/work/local/tests
address@hidden example
+
address@hidden
+and the
+administrative file contains @code{sh
address@hidden@}/runtests}, then that string is expanded
+to @code{sh /work/local/tests/runtests}.
+
+All other strings containing @samp{$} are reserved;
+there is no way to quote a @samp{$} character so that
address@hidden represents itself.
+
+Environment variables passed to administrative files are:
+
address@hidden @code
address@hidden environment variables, passed to administrative files
+
address@hidden CVS_USER
address@hidden CVS_USER, environment variable
+The @sc{cvs}-specific username provided by the user, if it
+can be provided (currently just for the pserver access
+method), and to the empty string otherwise. (@code{CVS_USER}
+and @code{USER} may differ when @file{$CVSROOT/CVSROOT/passwd}
+is used to map @sc{cvs} usernames to system usernames.)
+
address@hidden LOGNAME
address@hidden LOGNAME, environment variable
+The username of the system user.
+
address@hidden USER
address@hidden USER, environment variable
+Same as @code{LOGNAME}.
+Do not confuse this with the internal variable of the same name.
address@hidden table
+
address@hidden config
address@hidden The CVSROOT/config configuration file
+
address@hidden config, in CVSROOT
address@hidden CVSROOT/config
+
+The administrative file @file{config} contains various
+miscellaneous settings which affect the behavior of
address@hidden The syntax is slightly different from the
+other administrative files. Variables are not
+expanded. Lines which start with @samp{#} are
+considered comments.
address@hidden FIXME: where do we define comments for the other
address@hidden administrative files.
+Other lines consist of a keyword, @samp{=}, and a
+value. Note that this syntax is very strict.
+Extraneous spaces or tabs are not permitted.
address@hidden See comments in parseinfo.c:parse_config for more
address@hidden discussion of this strictness.
+
+Currently defined keywords are:
+
address@hidden @code
address@hidden RCSBIN, in CVSROOT/config
address@hidden address@hidden
+For @sc{cvs} 1.9.12 through 1.9.18, this setting told
address@hidden to look for @sc{rcs} programs in the
address@hidden directory. Current versions of @sc{cvs}
+do not run @sc{rcs} programs; for compatibility this
+setting is accepted, but it does nothing.
+
address@hidden SystemAuth, in CVSROOT/config
address@hidden address@hidden
+If @var{value} is @samp{yes}, then pserver should check
+for users in the system's user database if not found in
address@hidden/passwd}. If it is @samp{no}, then all
+pserver users must exist in @file{CVSROOT/passwd}.
+The default is @samp{yes}. For more on pserver, see
address@hidden authenticated}.
+
+
address@hidden TopLevelAdmin, in CVSROOT/config
address@hidden address@hidden
+Modify the @samp{checkout} command to create a
address@hidden directory at the top level of the new
+working directory, in addition to @samp{CVS}
+directories created within checked-out directories.
+The default value is @samp{no}.
+
+This option is useful if you find yourself performing
+many commands at the top level of your working
+directory, rather than in one of the checked out
+subdirectories. The @file{CVS} directory created there
+will mean you don't have to specify @code{CVSROOT} for
+each command. It also provides a place for the
address@hidden/Template} file (@pxref{Working directory
+storage}).
+
address@hidden LockDir, in CVSROOT/config
address@hidden address@hidden
+Put @sc{cvs} lock files in @var{directory} rather than
+directly in the repository. This is useful if you want
+to let users read from the repository while giving them
+write access only to @var{directory}, not to the
+repository.
+It can also be used to put the locks on a very fast
+in-memory file system to speed up locking and unlocking
+the repository.
+You need to create @var{directory}, but
address@hidden will create subdirectories of @var{directory} as it
+needs them. For information on @sc{cvs} locks, see
address@hidden
+
address@hidden Mention this in Compatibility section?
+Before enabling the LockDir option, make sure that you
+have tracked down and removed any copies of @sc{cvs} 1.9 or
+older. Such versions neither support LockDir, nor will
+give an error indicating that they don't support it.
+The result, if this is allowed to happen, is that some
address@hidden users will put the locks one place, and others will
+put them another place, and therefore the repository
+could become corrupted. @sc{cvs} 1.10 does not support
+LockDir but it will print a warning if run on a
+repository with LockDir enabled.
+
address@hidden LogHistory, in CVSROOT/config
address@hidden address@hidden
+Control what is logged to the @file{CVSROOT/history} file (@pxref{history}).
+Default of @samp{TOEFWUCGMAR} (or simply @samp{all}) will log
+all transactions. Any subset of the default is
+legal. (For example, to only log transactions that modify the
address@hidden,v} files, use @samp{LogHistory=TMAR}.)
+
address@hidden RereadLogAfterVerify, in CVSROOT/config
address@hidden @file{verifymsg}, changing the log message
address@hidden address@hidden
+Modify the @samp{commit} command such that CVS will reread the
+log message after running the program specified by @file{verifymsg}.
address@hidden may be one of @samp{yes} or @samp{always}, indicating that
+the log message should always be reread; @samp{no}
+or @samp{never}, indicating that it should never be
+reread; or @var{value} may be @samp{stat}, indicating
+that the file should be checked with the filesystem
address@hidden()} function to see if it has changed (see warning below)
+before rereading. The default value is @samp{always}.
+
address@hidden: the `stat' mode can cause CVS to pause for up to
+one extra second per directory committed. This can be less IO and
+CPU intensive but is not recommended for use with large repositories}
+
address@hidden, for more information on how verifymsg
+may be used.
+
address@hidden UserAdminOptions, in CVSROOT/config
address@hidden address@hidden
+Control what options will be allowed with the @code{cvs admin}
+command (@pxref{admin}) for users not in the @code{cvsadmin} group.
+The @var{value} string is a list of single character options
+which should be allowed. If a user who is not a member of the
address@hidden group tries to execute any @code{cvs admin}
+option which is not listed they will will receive an error message
+reporting that the option is restricted.
+
+If no @code{cvsadmin} group exists on the server, @sc{cvs} will
+ignore the @code{UserAdminOptions} keyword (@pxref{admin}).
+
+When not specified, @code{UserAdminOptions} defaults to
address@hidden In other words, it defaults to allowing
+users outside of the @code{cvsadmin} group to use the
address@hidden admin} command only to change the default keyword
+expansion mode for files.
+
+As an example, to restrict users not in the @code{cvsadmin}
+group to using @code{cvs admin} to change the default keyword
+substitution mode, lock revisions, unlock revisions, and
+replace the log message, use @samp{UserAdminOptions=klum}.
address@hidden table
+
address@hidden
---------------------------------------------------------------------
address@hidden Environment variables
address@hidden All environment variables which affect CVS
address@hidden Environment variables
address@hidden Reference manual for variables
+
+This is a complete list of all environment variables
+that affect @sc{cvs}.
+
address@hidden @code
address@hidden CVSIGNORE, environment variable
address@hidden $CVSIGNORE
+A whitespace-separated list of file name patterns that
address@hidden should ignore. @xref{cvsignore}.
+
address@hidden CVSWRAPPERS, environment variable
address@hidden $CVSWRAPPERS
+A whitespace-separated list of file name patterns that
address@hidden should treat as wrappers. @xref{Wrappers}.
+
address@hidden CVSREAD, environment variable
address@hidden Read-only files, and CVSREAD
address@hidden $CVSREAD
+If this is set, @code{checkout} and @code{update} will
+try hard to make the files in your working directory
+read-only. When this is not set, the default behavior
+is to permit modification of your working files.
+
address@hidden CVSREADONLYFS, environment variable
address@hidden $CVSREADONLYFS
+Turns on read-only repository mode. This allows one to
+check out from a read-only repository, such as within
+an anoncvs server, or from a CDROM repository.
+
+It has the same effect as if the @samp{-R} command-line
+option is used. This can also allow the use of
+read-only NFS repositories.
+
address@hidden $CVSUMASK
+Controls permissions of files in the repository. See
address@hidden permissions}.
+
address@hidden $CVSROOT
+Should contain the full pathname to the root of the @sc{cvs}
+source repository (where the @sc{rcs} files are
+kept). This information must be available to @sc{cvs} for
+most commands to execute; if @code{$CVSROOT} is not set,
+or if you wish to override it for one invocation, you
+can supply it on the command line: @samp{cvs -d cvsroot
address@hidden Once you have checked out a working
+directory, @sc{cvs} stores the appropriate root (in
+the file @file{CVS/Root}), so normally you only need to
+worry about this when initially checking out a working
+directory.
+
address@hidden $CVSEDITOR
address@hidden CVSEDITOR, environment variable
address@hidden $EDITOR
address@hidden EDITOR, environment variable
address@hidden $VISUAL
address@hidden VISUAL, environment variable
+Specifies the program to use for recording log messages
+during commit. @code{$CVSEDITOR} overrides
address@hidden, which overrides @code{$VISUAL}.
+See @ref{Committing your changes} for more or
address@hidden options} for alternative ways of specifying a
+log editor.
+
address@hidden PATH, environment variable
address@hidden $PATH
+If @code{$RCSBIN} is not set, and no path is compiled
+into @sc{cvs}, it will use @code{$PATH} to try to find all
+programs it uses.
+
address@hidden HOME, environment variable
address@hidden $HOME
address@hidden HOMEPATH, environment variable
address@hidden $HOMEPATH
address@hidden HOMEDRIVE, environment variable
address@hidden $HOMEDRIVE
+Used to locate the directory where the @file{.cvsrc}
+file, and other such files, are searched. On Unix, @sc{cvs}
+just checks for @code{HOME}. On Windows NT, the system will
+set @code{HOMEDRIVE}, for example to @samp{d:} and @code{HOMEPATH},
+for example to @file{\joe}. On Windows 95, you'll
+probably need to set @code{HOMEDRIVE} and @code{HOMEPATH} yourself.
address@hidden We are being vague about whether HOME works on
address@hidden Windows; see long comment in windows-NT/filesubr.c.
+
address@hidden CVS_RSH, environment variable
address@hidden $CVS_RSH
+Specifies the external program which @sc{cvs} connects with,
+when @code{:ext:} access method is specified.
address@hidden via rsh}.
+
address@hidden $CVS_SERVER
+Used in client-server mode when accessing a remote
+repository using @sc{rsh}. It specifies the name of
+the program to start on the server side (and any
+necessary arguments) when accessing a remote repository
+using the @code{:ext:}, @code{:fork:}, or @code{:server:} access methods.
+The default value for @code{:ext:} and @code{:server:} is @code{cvs};
+the default value for @code{:fork:} is the name used to run the client.
address@hidden via rsh}
+
address@hidden $CVS_PASSFILE
+Used in client-server mode when accessing the @code{cvs
+login server}. Default value is @file{$HOME/.cvspass}.
address@hidden authentication client}
+
address@hidden $CVS_CLIENT_PORT
+Used in client-server mode to set the port to use when accessing the server
+via Kerberos, GSSAPI, or @sc{cvs}'s password authentication protocol
+if the port is not specified in the CVSROOT.
address@hidden repositories}
+
address@hidden CVS_RCMD_PORT, environment variable
address@hidden $CVS_RCMD_PORT
+Used in client-server mode. If set, specifies the port
+number to be used when accessing the @sc{rcmd} demon on
+the server side. (Currently not used for Unix clients).
+
address@hidden CVS_CLIENT_LOG, environment variable
address@hidden $CVS_CLIENT_LOG
+Used for debugging only in client-server
+mode. If set, everything sent to the server is logged
+into @address@hidden and everything
+sent from the server is logged into
address@hidden@code{$CVS_CLIENT_LOG}.out}.
+
address@hidden CVS_SERVER_SLEEP, environment variable
address@hidden $CVS_SERVER_SLEEP
+Used only for debugging the server side in
+client-server mode. If set, delays the start of the
+server child process the specified amount of
+seconds so that you can attach to it with a debugger.
+
address@hidden CVS_IGNORE_REMOTE_ROOT, environment variable
address@hidden $CVS_IGNORE_REMOTE_ROOT
+For @sc{cvs} 1.10 and older, setting this variable
+prevents @sc{cvs} from overwriting the @file{CVS/Root}
+file when the @samp{-d} global option is specified.
+Later versions of @sc{cvs} do not rewrite
address@hidden/Root}, so @code{CVS_IGNORE_REMOTE_ROOT} has no
+effect.
+
address@hidden CVS_LOCAL_BRANCH_NUM, environment variable
address@hidden $CVS_LOCAL_BRANCH_NUM
+Setting this variable allows some control over the
+branch number that is assigned. This is specifically to
+support the local commit feature of CVSup. If one sets
address@hidden to (say) 1000 then branches
+the local repository, the revision numbers will look
+like 1.66.1000.xx. There is almost a dead-set certainty
+that there will be no conflicts with version numbers.
+
address@hidden COMSPEC, environment variable
address@hidden $COMSPEC
+Used under OS/2 only. It specifies the name of the
+command interpreter and defaults to @sc{cmd.exe}.
+
address@hidden TMPDIR, environment variable
address@hidden $TMPDIR
address@hidden TMP, environment variable
address@hidden $TMP
address@hidden TEMP, environment variable
address@hidden $TEMP
address@hidden Temporary files, location of
address@hidden This is quite nuts. We don't talk about tempnam
address@hidden or mkstemp which we sometimes use. The discussion
address@hidden of "Global options" is semi-incoherent.
address@hidden I'm not even sure those are the only inaccuracies.
address@hidden Furthermore, the conventions are
address@hidden pretty crazy and they should be simplified.
+Directory in which temporary files are located.
+The @sc{cvs} server uses
address@hidden @xref{Global options}, for a
+description of how to specify this.
+Some parts of @sc{cvs} will always use @file{/tmp} (via
+the @code{tmpnam} function provided by the system).
+
+On Windows NT, @code{TMP} is used (via the @code{_tempnam}
+function provided by the system).
+
+The @code{patch} program which is used by the @sc{cvs}
+client uses @code{TMPDIR}, and if it is not set, uses
address@hidden/tmp} (at least with GNU patch 2.1). Note that
+if your server and client are both running @sc{cvs}
+1.9.10 or later, @sc{cvs} will not invoke an external
address@hidden program.
+
address@hidden CVS_PID, environment variable
address@hidden $CVS_PID
+This is the process identification (aka pid) number of
+the @sc{cvs} process. It is often useful in the
+programs and/or scripts specified by the
address@hidden, @file{verifymsg}, @file{loginfo}
+files.
address@hidden table
+
address@hidden Compatibility
address@hidden Compatibility between CVS Versions
+
address@hidden CVS, versions of
address@hidden Versions, of CVS
address@hidden Compatibility, between CVS versions
address@hidden We don't mention versions older than CVS 1.3
address@hidden on the theory that it would clutter it up for the vast
address@hidden majority of people, who don't have anything that old.
address@hidden
+The repository format is compatible going back to
address@hidden 1.3. But see @ref{Watches Compatibility}, if
+you have copies of @sc{cvs} 1.6 or older and you want
+to use the optional developer communication features.
address@hidden If you "cvs rm" and commit using 1.3, then you'll
address@hidden want to run "rcs -sdead <file,v>" on each of the
address@hidden files in the Attic if you then want 1.5 and
address@hidden later to recognize those files as dead (I think the
address@hidden symptom if this is not done is that files reappear
address@hidden in joins). (Wait: the above will work but really to
address@hidden be strictly correct we should suggest checking
address@hidden in a new revision rather than just changing the
address@hidden state of the head revision, shouldn't we?).
address@hidden The old convert.sh script was for this, but it never
address@hidden did get updated to reflect use of the RCS "dead"
address@hidden state.
address@hidden Note: this is tricky to document without confusing
address@hidden people--need to carefully say what CVS version we
address@hidden are talking about and keep in mind the distinction
address@hidden between a
address@hidden repository created with 1.3 and on which one now
address@hidden uses 1.5+, and a repository on which one wants to
address@hidden use both versions side by side (e.g. during a
address@hidden transition period).
address@hidden Wait, can't CVS just detect the case in which a file
address@hidden is in the Attic but the head revision is not dead?
address@hidden Not sure whether this should produce a warning or
address@hidden something, and probably needs further thought, but
address@hidden it would appear that the situation can be detected.
address@hidden
address@hidden We might want to separate out the 1.3 compatibility
address@hidden section (for repository & working directory) from the
address@hidden rest--that might help avoid confusing people who
address@hidden are upgrading (for example) from 1.6 to 1.8.
address@hidden
address@hidden A minor incompatibility is if a current version of CVS
address@hidden puts "Nfoo" into CVS/Tag, then CVS 1.9 or older will
address@hidden see this as if there is no tag. Seems to me this is
address@hidden too obscure to mention.
+
+The working directory format is compatible going back
+to @sc{cvs} 1.5. It did change between @sc{cvs} 1.3
+and @sc{cvs} 1.5. If you run @sc{cvs} 1.5 or newer on
+a working directory checked out with @sc{cvs} 1.3,
address@hidden will convert it, but to go back to @sc{cvs}
+1.3 you need to check out a new working directory with
address@hidden 1.3.
+
+The remote protocol is interoperable going back to @sc{cvs} 1.5, but no
+further (1.5 was the first official release with the remote protocol,
+but some older versions might still be floating around). In many
+cases you need to upgrade both the client and the server to take
+advantage of new features and bugfixes, however.
+
address@hidden Perhaps should be saying something here about the
address@hidden "D" lines in Entries (written by CVS 1.9; 1.8 and
address@hidden older don't use them). These are supposed to be
address@hidden compatible in both directions, but I'm not sure
address@hidden they quite are 100%. One common gripe is if you
address@hidden "rm -r" a directory and 1.9 gets confused, as it
address@hidden still sees it in Entries. That one is fixed in
address@hidden (say) 1.9.6. Someone else reported problems with
address@hidden starting with a directory which was checked out with
address@hidden an old version, and then using a new version, and
address@hidden some "D" lines appeared, but not for every
address@hidden directory, causing some directories to be skipped.
address@hidden They weren't sure how to reproduce this, though.
+
address@hidden
---------------------------------------------------------------------
address@hidden Troubleshooting
address@hidden Troubleshooting
+
+If you are having trouble with @sc{cvs}, this appendix
+may help. If there is a particular error message which
+you are seeing, then you can look up the message
+alphabetically. If not, you can look through the
+section on other problems to see if your problem is
+mentioned there.
+
address@hidden
+* Error messages:: Partial list of CVS errors
+* Connection:: Trouble making a connection to a CVS server
+* Other problems:: Problems not readily listed by error message
address@hidden menu
+
+
address@hidden Error messages
address@hidden Partial list of error messages
+
+Here is a partial list of error messages that you may
+see from @sc{cvs}. It is not a complete address@hidden
+is capable of printing many, many error messages, often
+with parts of them supplied by the operating system,
+but the intention is to list the common and/or
+potentially confusing error messages.
+
+The messages are alphabetical, but introductory text
+such as @samp{cvs update: } is not considered in
+ordering them.
+
+In some cases the list includes messages printed by old
+versions of @sc{cvs} (partly because users may not be
+sure which version of @sc{cvs} they are using at any
+particular moment).
address@hidden If we want to start retiring messages, perhaps we
address@hidden should pick a cutoff version (for example, no more
address@hidden messages which are specific to versions before 1.9)
address@hidden and then move the old messages to an "old messages"
address@hidden node rather than deleting them completely.
+
address@hidden @code
address@hidden FIXME: What is the correct way to format a multiline
address@hidden error message here? Maybe @table is the wrong
address@hidden choice? Texinfo gurus?
address@hidden @var{file}:@var{line}: Assertion '@var{text}' failed
+The exact format of this message may vary depending on
+your system. It indicates a bug in @sc{cvs}, which can
+be handled as described in @ref{BUGS}.
+
address@hidden cvs @var{command}: authorization failed: server @var{host}
rejected access
+This is a generic response when trying to connect to a
+pserver server which chooses not to provide a
+specific reason for denying authorization. Check that
+the username and password specified are correct and
+that the @code{CVSROOT} specified is allowed by @samp{--allow-root}
+in @file{inetd.conf}. See @ref{Password authenticated}.
+
address@hidden cvs @var{command}: conflict: removed @var{file} was modified by
second party
+This message indicates that you removed a file, and
+someone else modified it. To resolve the conflict,
+first run @samp{cvs add @var{file}}. If desired, look
+at the other party's modification to decide whether you
+still want to remove it. If you don't want to remove
+it, stop here. If you do want to remove it, proceed
+with @samp{cvs remove @var{file}} and commit your
+removal.
address@hidden Tests conflicts2-142b* in sanity.sh test for this.
+
address@hidden cannot change permissions on temporary directory
address@hidden
+Operation not permitted
address@hidden example
+This message has been happening in a non-reproducible,
+occasional way when we run the client/server testsuite,
+both on Red Hat Linux 3.0.3 and 4.1. We haven't been
+able to figure out what causes it, nor is it known
+whether it is specific to linux (or even to this
+particular machine!). If the problem does occur on
+other unices, @samp{Operation not permitted} would be
+likely to read @samp{Not owner} or whatever the system
+in question uses for the unix @code{EPERM} error. If
+you have any information to add, please let us know as
+described in @ref{BUGS}. If you experience this error
+while using @sc{cvs}, retrying the operation which
+produced it should work fine.
address@hidden This has been seen in a variety of tests, including
address@hidden multibranch-2, multibranch-5, and basic1-24-rm-rm,
address@hidden so it doesn't seem particularly specific to any one
address@hidden test.
+
address@hidden cvs [server aborted]: Cannot check out files into the repository
itself
+The obvious cause for this message (especially for
+non-client/server @sc{cvs}) is that the @sc{cvs} root
+is, for example, @file{/usr/local/cvsroot} and you try
+to check out files when you are in a subdirectory, such
+as @file{/usr/local/cvsroot/test}. However, there is a
+more subtle cause, which is that the temporary
+directory on the server is set to a subdirectory of the
+root (which is also not allowed). If this is the
+problem, set the temporary directory to somewhere else,
+for example @file{/var/tmp}; see @code{TMPDIR} in
address@hidden variables}, for how to set the
+temporary directory.
+
address@hidden cannot commit files as 'root'
+See @samp{'root' is not allowed to commit files}.
+
address@hidden For one example see basica-1a10 in the testsuite
address@hidden For another example, "cvs co ." on NT; see comment
address@hidden at windows-NT/filesubr.c (expand_wild).
address@hidden For another example, "cvs co foo/bar" where foo exists.
address@hidden cannot open CVS/Entries for reading: No such file or directory
+This generally indicates a @sc{cvs} internal error, and
+can be handled as with other @sc{cvs} bugs
+(@pxref{BUGS}). Usually there is a workaround---the
+exact nature of which would depend on the situation but
+which hopefully could be figured out.
+
address@hidden This is more obscure than it might sound; it only
address@hidden happens if you run "cvs init" from a directory which
address@hidden contains a CVS/Root file at the start.
address@hidden cvs [init aborted]: cannot open CVS/Root: No such file or
directory
+This message is harmless. Provided it is not
+accompanied by other errors, the operation has
+completed successfully. This message should not occur
+with current versions of @sc{cvs}, but it is documented
+here for the benefit of @sc{cvs} 1.9 and older.
+
address@hidden cvs server: cannot open /root/.cvsignore: Permission denied
address@hidden cvs [server aborted]: can't chdir(/root): Permission denied
+See @ref{Connection}.
+
address@hidden cvs [checkout aborted]: cannot rename file @var{file} to
CVS/,,@var{file}: Invalid argument
+This message has been reported as intermittently
+happening with @sc{cvs} 1.9 on Solaris 2.5. The cause is
+unknown; if you know more about what causes it, let us
+know as described in @ref{BUGS}.
+
address@hidden cvs address@hidden aborted]: cannot start server via rcmd
+This, unfortunately, is a rather nonspecific error
+message which @sc{cvs} 1.9 will print if you are
+running the @sc{cvs} client and it is having trouble
+connecting to the server. Current versions of @sc{cvs}
+should print a much more specific error message. If
+you get this message when you didn't mean to run the
+client at all, you probably forgot to specify
address@hidden:local:}, as described in @ref{Repository}.
+
address@hidden ci: @var{file},v: bad diff output line: Binary files - and
/tmp/T2a22651 differ
address@hidden 1.9 and older will print this message
+when trying to check in a binary file if
address@hidden is not correctly installed. Re-read the
+instructions that came with your @sc{rcs} distribution
+and the @sc{install} file in the @sc{cvs}
+distribution. Alternately, upgrade to a current
+version of @sc{cvs}, which checks in files itself
+rather than via @sc{rcs}.
+
address@hidden cvs checkout: could not check out @var{file}
+With @sc{cvs} 1.9, this can mean that the @code{co} program
+(part of @sc{rcs}) returned a failure. It should be
+preceded by another error message, however it has been
+observed without another error message and the cause is
+not well-understood. With the current version of @sc{cvs},
+which does not run @code{co}, if this message occurs
+without another error message, it is definitely a @sc{cvs}
+bug (@pxref{BUGS}).
address@hidden My current suspicion is that the RCS in the rcs (not
address@hidden cvs/winnt/rcs57nt.zip) directory on the _Practical_
address@hidden CD is bad (remains to be confirmed).
address@hidden There is also a report of something which looks
address@hidden very similar on SGI, Irix 5.2, so I dunno.
+
address@hidden cvs [login aborted]: could not find out home directory
+This means that you need to set the environment
+variables that @sc{cvs} uses to locate your home directory.
+See the discussion of @code{HOME}, @code{HOMEDRIVE}, and @code{HOMEPATH} in
address@hidden variables}.
+
address@hidden cvs update: could not merge revision @var{rev} of @var{file}: No
such file or directory
address@hidden 1.9 and older will print this message if there was
+a problem finding the @code{rcsmerge} program. Make
+sure that it is in your @code{PATH}, or upgrade to a
+current version of @sc{cvs}, which does not require
+an external @code{rcsmerge} program.
+
address@hidden cvs [update aborted]: could not patch @var{file}: No such file
or directory
+This means that there was a problem finding the
address@hidden program. Make sure that it is in your
address@hidden Note that despite appearances the message
+is @emph{not} referring to whether it can find @var{file}.
+If both the client and the server are running a current
+version of @sc{cvs}, then there is no need for an
+external patch program and you should not see this
+message. But if either client or server is running
address@hidden 1.9, then you need @code{patch}.
+
address@hidden cvs update: could not patch @var{file}; will refetch
+This means that for whatever reason the client was
+unable to apply a patch that the server sent. The
+message is nothing to be concerned about, because
+inability to apply the patch only slows things down and
+has no effect on what @sc{cvs} does.
address@hidden xref to update output. Or File status?
address@hidden Or some place else that
address@hidden explains this whole "patch"/P/Needs Patch thing?
+
address@hidden dying gasps from @var{server} unexpected
+There is a known bug in the server for @sc{cvs} 1.9.18
+and older which can cause this. For me, this was
+reproducible if I used the @samp{-t} global option. It
+was fixed by Andy Piper's 14 Nov 1997 change to
+src/filesubr.c, if anyone is curious.
+If you see the message,
+you probably can just retry the operation which failed,
+or if you have discovered information concerning its
+cause, please let us know as described in @ref{BUGS}.
+
address@hidden end of file from server (consult above messages if any)
+The most common cause for this message is if you are
+using an external @code{rsh} program and it exited with
+an error. In this case the @code{rsh} program should
+have printed a message, which will appear before the
+above message. For more information on setting up a
address@hidden client and server, see @ref{Remote repositories}.
+
address@hidden cvs [update aborted]: EOF in key in RCS file @var{file},v
address@hidden cvs [checkout aborted]: EOF while looking for end of string in
RCS file @var{file},v
+This means that there is a syntax error in the given
address@hidden file. Note that this might be true even if @sc{rcs} can
+read the file OK; @sc{cvs} does more error checking of
+errors in the RCS file. That is why you may see this
+message when upgrading from @sc{cvs} 1.9 to @sc{cvs}
+1.10. The likely cause for the original corruption is
+hardware, the operating system, or the like. Of
+course, if you find a case in which @sc{cvs} seems to
+corrupting the file, by all means report it,
+(@pxref{BUGS}).
+There are quite a few variations of this error message,
+depending on exactly where in the @sc{rcs} file @sc{cvs}
+finds the syntax error.
+
address@hidden mkmodules
address@hidden cvs commit: Executing 'mkmodules'
+This means that your repository is set up for a version
+of @sc{cvs} prior to @sc{cvs} 1.8. When using @sc{cvs}
+1.8 or later, the above message will be preceded by
+
address@hidden
+cvs commit: Rebuilding administrative file database
address@hidden example
+
+If you see both messages, the database is being rebuilt
+twice, which is unnecessary but harmless. If you wish
+to avoid the duplication, and you have no versions of
address@hidden 1.7 or earlier in use, remove @code{-i mkmodules}
+every place it appears in your @code{modules}
+file. For more information on the @code{modules} file,
+see @ref{modules}.
+
address@hidden This message comes from "co", and I believe is
address@hidden possible only with older versions of CVS which call
address@hidden co. The problem with being able to create the bogus
address@hidden RCS file still exists, though (and I think maybe
address@hidden there is a different symptom(s) now).
address@hidden FIXME: Would be nice to have a more exact wording
address@hidden for this message.
address@hidden missing author
+Typically this can happen if you created an RCS file
+with your username set to empty. @sc{cvs} will, bogusly,
+create an illegal RCS file with no value for the author
+field. The solution is to make sure your username is
+set to a non-empty value and re-create the RCS file.
address@hidden "make sure your username is set" is complicated in
address@hidden and of itself, as there are the environment
address@hidden variables the system login name, &c, and it depends
address@hidden on the version of CVS.
+
address@hidden cvs [checkout aborted]: no such tag @var{tag}
+This message means that @sc{cvs} isn't familiar with
+the tag @var{tag}. Usually this means that you have
+mistyped a tag name; however there are (relatively
+obscure) cases in which @sc{cvs} will require you to
address@hidden Search sanity.sh for "no such tag" to see some of
address@hidden the relatively obscure cases.
+try a few other @sc{cvs} commands involving that tag,
+before you find one which will cause @sc{cvs} to update
+the @file{val-tags} file; see discussion of val-tags in
address@hidden permissions}. You only need to worry about
+this once for a given tag; when a tag is listed in
address@hidden, it stays there. Note that using
address@hidden to not require tag matches does not override
+this check; see @ref{Common options}.
+
address@hidden *PANIC* administration files missing
+This typically means that there is a directory named
address@hidden but it does not contain the administrative files
+which @sc{cvs} puts in a CVS directory. If the problem is
+that you created a CVS directory via some mechanism
+other than @sc{cvs}, then the answer is simple, use a name
+other than @sc{cvs}. If not, it indicates a @sc{cvs} bug
+(@pxref{BUGS}).
+
address@hidden rcs error: Unknown option: -x,v/
+This message will be followed by a usage message for
address@hidden It means that you have an old version of
address@hidden (probably supplied with your operating
+system), as well as an old version of @sc{cvs}.
address@hidden 1.9.18 and earlier only work with @sc{rcs} version 5 and
+later; current versions of @sc{cvs} do not run @sc{rcs} programs.
address@hidden For more information on installing @sc{cvs}, see
address@hidden (FIXME: where? it depends on whether you are
address@hidden getting binaries or sources or what).
address@hidden The message can also say "ci error" or something
address@hidden instead of "rcs error", I suspect.
+
address@hidden cvs [server aborted]: received broken pipe signal
+This message seems to be caused by a hard-to-track-down
+bug in @sc{cvs} or the systems it runs on (we don't
+know---we haven't tracked it down yet!). It seems to
+happen only after a @sc{cvs} command has completed, and
+you should be able to just ignore the message.
+However, if you have discovered information concerning its
+cause, please let us know as described in @ref{BUGS}.
+
address@hidden 'root' is not allowed to commit files
+When committing a permanent change, @sc{cvs} makes a log entry of
+who committed the change. If you are committing the change logged
+in as "root" (not under "su" or other root-priv giving program),
address@hidden cannot determine who is actually making the change.
+As such, by default, @sc{cvs} disallows changes to be committed by users
+logged in as "root". (You can disable this option by passing the
address@hidden option to @file{configure} and recompiling @sc{cvs}.
+On some systems this means editing the appropriate @file{config.h} file
+before building @sc{cvs}.)
+
address@hidden Too many arguments!
+This message is typically printed by the @file{log.pl}
+script which is in the @file{contrib} directory in the
address@hidden source distribution. In some versions of
address@hidden, @file{log.pl} has been part of the default
address@hidden installation. The @file{log.pl} script gets
+called from the @file{loginfo} administrative file.
+Check that the arguments passed in @file{loginfo} match
+what your version of @file{log.pl} expects. In
+particular, the @file{log.pl} from @sc{cvs} 1.3 and
+older expects the logfile as an argument whereas the
address@hidden from @sc{cvs} 1.5 and newer expects the
+logfile to be specified with a @samp{-f} option. Of
+course, if you don't need @file{log.pl} you can just
+comment it out of @file{loginfo}.
+
address@hidden cvs [update aborted]: unexpected EOF reading @var{file},v
+See @samp{EOF in key in RCS file}.
+
address@hidden cvs [login aborted]: unrecognized auth response from @var{server}
+This message typically means that the server is not set
+up properly. For example, if @file{inetd.conf} points
+to a nonexistent cvs executable. To debug it further,
+find the log file which inetd writes
+(@file{/var/log/messages} or whatever inetd uses on
+your system). For details, see @ref{Connection}, and
address@hidden authentication server}.
+
address@hidden cvs commit: Up-to-date check failed for address@hidden'
+This means that someone else has committed a change to
+that file since the last time that you did a @code{cvs
+update}. So before proceeding with your @code{cvs
+commit} you need to @code{cvs update}. @sc{cvs} will merge
+the changes that you made and the changes that the
+other person made. If it does not detect any conflicts
+it will report @samp{M @var{file}} and you are ready
+to @code{cvs commit}. If it detects conflicts it will
+print a message saying so, will report @samp{C @var{file}},
+and you need to manually resolve the
+conflict. For more details on this process see
address@hidden example}.
+
address@hidden Usage: diff3 [-exEX3 [-i | -m] [-L label1 -L label3]] file1
file2 file3
address@hidden
+Only one of [exEX3] allowed
address@hidden example
+This indicates a problem with the installation of
address@hidden and @code{rcsmerge}. Specifically
address@hidden was compiled to look for GNU diff3, but
+it is finding unix diff3 instead. The exact text of
+the message will vary depending on the system. The
+simplest solution is to upgrade to a current version of
address@hidden, which does not rely on external
address@hidden or @code{diff3} programs.
+
address@hidden warning: unrecognized response address@hidden' from cvs server
+If @var{text} contains a valid response (such as
address@hidden) followed by an extra carriage return
+character (on many systems this will cause the second
+part of the message to overwrite the first part), then
+it probably means that you are using the @samp{:ext:}
+access method with a version of rsh, such as most
+non-unix rsh versions, which does not by default
+provide a transparent data stream. In such cases you
+probably want to try @samp{:server:} instead of
address@hidden:ext:}. If @var{text} is something else, this
+may signify a problem with your @sc{cvs} server.
+Double-check your installation against the instructions
+for setting up the @sc{cvs} server.
address@hidden FIXCVS: should be printing CR as \r or \015 or some
address@hidden such, probably.
+
address@hidden cvs commit: address@hidden waiting for @var{user}'s lock in
@var{directory}
+This is a normal message, not an error. See
address@hidden, for more details.
+
address@hidden cvs commit: warning: editor session failed
address@hidden Exit status, of editor
+This means that the editor which @sc{cvs} is using exits with a nonzero
+exit status. Some versions of vi will do this even when there was not
+a problem editing the file. If so, point the
address@hidden environment variable to a small script
+such as:
+
address@hidden
+#!/bin/sh
+vi $*
+exit 0
address@hidden example
+
address@hidden "warning: foo was lost" and "no longer pertinent" (both normal).
address@hidden Would be nice to write these up--they are
address@hidden potentially confusing for the new user.
address@hidden table
+
address@hidden Connection
address@hidden Trouble making a connection to a CVS server
+
+This section concerns what to do if you are having
+trouble making a connection to a @sc{cvs} server. If
+you are running the @sc{cvs} command line client
+running on Windows, first upgrade the client to
address@hidden 1.9.12 or later. The error reporting in
+earlier versions provided much less information about
+what the problem was. If the client is non-Windows,
address@hidden 1.9 should be fine.
+
+If the error messages are not sufficient to track down
+the problem, the next steps depend largely on which
+access method you are using.
+
address@hidden @code
address@hidden :ext:, troubleshooting
address@hidden :ext:
+Try running the rsh program from the command line. For
+example: "rsh servername cvs -v" should print @sc{cvs}
+version information. If this doesn't work, you need to
+fix it before you can worry about @sc{cvs} problems.
+
address@hidden :server:, troubleshooting
address@hidden :server:
+You don't need a command line rsh program to use this
+access method, but if you have an rsh program around,
+it may be useful as a debugging tool. Follow the
+directions given for :ext:.
+
address@hidden :pserver:, troubleshooting
address@hidden :pserver:
+Errors along the lines of "connection refused" typically indicate
+that inetd isn't even listening for connections on port 2401
+whereas errors like "connection reset by peer",
+"received broken pipe signal", "recv() from server: EOF",
+or "end of file from server"
+typically indicate that inetd is listening for
+connections but is unable to start @sc{cvs} (this is frequently
+caused by having an incorrect path in @file{inetd.conf}
+or by firewall software rejecting the connection).
+"unrecognized auth response" errors are caused by a bad command
+line in @file{inetd.conf}, typically an invalid option or forgetting
+to put the @samp{pserver} command at the end of the line.
+Another less common problem is invisible control characters that
+your editor "helpfully" added without you noticing.
+
+One good debugging tool is to "telnet servername
+2401". After connecting, send any text (for example
+"foo" followed by return). If @sc{cvs} is working
+correctly, it will respond with
+
address@hidden
+cvs [pserver aborted]: bad auth protocol start: foo
address@hidden example
+
+If instead you get:
+
address@hidden
+Usage: cvs [cvs-options] command [command-options-and-arguments]
+...
address@hidden example
+
address@hidden
+then you're missing the @samp{pserver} command at the end of the
+line in @file{inetd.conf}; check to make sure that the entire command
+is on one line and that it's complete.
+
+Likewise, if you get something like:
+
address@hidden
+Unknown command: `pserved'
+
+CVS commands are:
+ add Add a new file/directory to the repository
+...
address@hidden example
+
address@hidden
+then you've misspelled @samp{pserver} in some way. If it isn't
+obvious, check for invisible control characters (particularly
+carriage returns) in @file{inetd.conf}.
+
+If it fails to work at all, then make sure inetd is working
+right. Change the invocation in @file{inetd.conf} to run the
+echo program instead of cvs. For example:
+
address@hidden
+2401 stream tcp nowait root /bin/echo echo hello
address@hidden example
+
+After making that change and instructing inetd to
+re-read its configuration file, "telnet servername
+2401" should show you the text hello and then the
+server should close the connection. If this doesn't
+work, you need to fix it before you can worry about
address@hidden problems.
+
+On AIX systems, the system will often have its own
+program trying to use port 2401. This is AIX's problem
+in the sense that port 2401 is registered for use with
address@hidden I hear that there is an AIX patch available
+to address this problem.
+
+Another good debugging tool is the @samp{-d}
+(debugging) option to inetd. Consult your system
+documentation for more information.
+
+If you seem to be connecting but get errors like:
+
address@hidden
+cvs server: cannot open /root/.cvsignore: Permission denied
+cvs [server aborted]: can't chdir(/root): Permission denied
address@hidden example
+
address@hidden
+then you probably haven't specified @samp{-f} in @file{inetd.conf}.
+(In releases prior to @sc{cvs} 1.11.1, this problem can be caused by
+your system setting the @code{$HOME} environment variable
+for programs being run by inetd. In this case, you can either
+have inetd run a shell script that unsets @code{$HOME} and then runs
address@hidden, or you can use @code{env} to run @sc{cvs} with a pristine
+environment.)
+
+If you can connect successfully for a while but then can't,
+you've probably hit inetd's rate limit.
+(If inetd receives too many requests for the same service
+in a short period of time, it assumes that something is wrong
+and temporarily disables the service.)
+Check your inetd documentation to find out how to adjust the
+rate limit (some versions of inetd have a single rate limit,
+others allow you to set the limit for each service separately.)
address@hidden table
+
address@hidden Other problems
address@hidden Other common problems
+
+Here is a list of problems which do not fit into the
+above categories. They are in no particular order.
+
address@hidden @bullet
address@hidden
+On Windows, if there is a 30 second or so delay when
+you run a @sc{cvs} command, it may mean that you have
+your home directory set to @file{C:/}, for example (see
address@hidden and @code{HOMEPATH} in
address@hidden variables}). @sc{cvs} expects the home
+directory to not end in a slash, for example @file{C:}
+or @file{C:\cvs}.
address@hidden FIXCVS: CVS should at least detect this and print an
address@hidden error, presumably.
+
address@hidden
+If you are running @sc{cvs} 1.9.18 or older, and
address@hidden update} finds a conflict and tries to
+merge, as described in @ref{Conflicts example}, but
+doesn't tell you there were conflicts, then you may
+have an old version of @sc{rcs}. The easiest solution
+probably is to upgrade to a current version of
address@hidden, which does not rely on external @sc{rcs}
+programs.
address@hidden itemize
+
address@hidden
---------------------------------------------------------------------
address@hidden Credits
address@hidden Credits
+
address@hidden Contributors (manual)
address@hidden Credits (manual)
+Roland Pesch, then of Cygnus Support <@t{roland@@wrs.com}>
+wrote the manual pages which were distributed with
address@hidden 1.3. Much of their text was copied into this
+manual. He also read an early draft
+of this manual and contributed many ideas and
+corrections.
+
+The mailing-list @code{info-cvs} is sometimes
+informative. I have included information from postings
+made by the following persons:
+David G. Grubbs <@t{dgg@@think.com}>.
+
+Some text has been extracted from the man pages for
address@hidden
+
+The @sc{cvs} @sc{faq} by David G. Grubbs has provided
+useful material. The @sc{faq} is no longer maintained,
+however, and this manual is about the closest thing there
+is to a successor (with respect to documenting how to
+use @sc{cvs}, at least).
+
+In addition, the following persons have helped by
+telling me about mistakes I've made:
+
address@hidden
+Roxanne Brunskill <@t{rbrunski@@datap.ca}>,
+Kathy Dyer <@t{dyer@@phoenix.ocf.llnl.gov}>,
+Karl Pingle <@t{pingle@@acuson.com}>,
+Thomas A Peterson <@t{tap@@src.honeywell.com}>,
+Inge Wallin <@t{ingwa@@signum.se}>,
+Dirk Koschuetzki <@t{koschuet@@fmi.uni-passau.de}>
+and Michael Brown <@t{brown@@wi.extrel.com}>.
address@hidden display
+
+The list of contributors here is not comprehensive; for a more
+complete list of who has contributed to this manual see
+the file @file{doc/ChangeLog} in the @sc{cvs} source
+distribution.
+
address@hidden
---------------------------------------------------------------------
address@hidden BUGS
address@hidden Dealing with bugs in CVS or this manual
+
address@hidden Bugs in this manual or CVS
+Neither @sc{cvs} nor this manual is perfect, and they
+probably never will be. If you are having trouble
+using @sc{cvs}, or think you have found a bug, there
+are a number of things you can do about it. Note that
+if the manual is unclear, that can be considered a bug
+in the manual, so these problems are often worth doing
+something about as well as problems with @sc{cvs} itself.
+
address@hidden Reporting bugs
address@hidden Bugs, reporting
address@hidden Errors, reporting
address@hidden @bullet
address@hidden
+If you want someone to help you and fix bugs that you
+report, there are companies which will do that for a
+fee. One such company is:
+
address@hidden Ximbiot
address@hidden Support, getting CVS support
address@hidden
+Ximbiot
+319 S. River St.
+Harrisburg, PA 17104-1657
+USA
+Email: info@@ximbiot.com
+Phone: (717) 579-6168
+Fax: (717) 234-3125
+http://ximbiot.com/
+
address@hidden example
+
address@hidden
+If you got @sc{cvs} through a distributor, such as an
+operating system vendor or a vendor of freeware
address@hidden, you may wish to see whether the
+distributor provides support. Often, they will provide
+no support or minimal support, but this may vary from
+distributor to distributor.
+
address@hidden
+If you have the skills and time to do so, you may wish
+to fix the bug yourself. If you wish to submit your
+fix for inclusion in future releases of @sc{cvs}, see
+the file @sc{hacking} in the @sc{cvs} source
+distribution. It contains much more information on the
+process of submitting fixes.
+
address@hidden
+There may be resources on the net which can help. Two
+good places to start are:
+
address@hidden
+http://www.cvshome.org
+http://www.loria.fr/~molli/cvs-index.html
address@hidden example
+
+If you are so inspired, increasing the information
+available on the net is likely to be appreciated. For
+example, before the standard @sc{cvs} distribution
+worked on Windows 95, there was a web page with some
+explanation and patches for running @sc{cvs} on Windows
+95, and various people helped out by mentioning this
+page on mailing lists or newsgroups when the subject
+came up.
+
address@hidden
+It is also possible to report bugs to @code{bug-cvs}.
+Note that someone may or may not want to do anything
+with your bug report---if you need a solution consider
+one of the options mentioned above. People probably do
+want to hear about bugs which are particularly severe
+in consequences and/or easy to fix, however. You can
+also increase your odds by being as clear as possible
+about the exact nature of the bug and any other
+relevant information. The way to report bugs is to
+send email to @code{bug-cvs@@gnu.org}. Note
+that submissions to @code{bug-cvs} may be distributed
+under the terms of the @sc{gnu} Public License, so if
+you don't like this, don't submit them. There is
+usually no justification for sending mail directly to
+one of the @sc{cvs} maintainers rather than to
address@hidden; those maintainers who want to hear
+about such bug reports read @code{bug-cvs}. Also note
+that sending a bug report to other mailing lists or
+newsgroups is @emph{not} a substitute for sending it to
address@hidden It is fine to discuss @sc{cvs} bugs on
+whatever forum you prefer, but there are not
+necessarily any maintainers reading bug reports sent
+anywhere except @code{bug-cvs}.
address@hidden itemize
+
address@hidden Known bugs in this manual or CVS
+People often ask if there is a list of known bugs or
+whether a particular bug is a known one. The file
address@hidden in the @sc{cvs} source distribution is one
+list of known bugs, but it doesn't necessarily try to
+be comprehensive. Perhaps there will never be a
+comprehensive, detailed list of known bugs.
+
address@hidden
---------------------------------------------------------------------
address@hidden Index
address@hidden Index
address@hidden Index
+
address@hidden cp
+
address@hidden
+
address@hidden
+
address@hidden
Index: res/texi_hello/hello.texi.first
===================================================================
RCS file: res/texi_hello/hello.texi.first
diff -N res/texi_hello/hello.texi.first
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ res/texi_hello/hello.texi.first 2 Aug 2009 13:10:59 -0000 1.1
@@ -0,0 +1,789 @@
+\input texinfo @c -*-texinfo-*-
address@hidden %**start of header
address@hidden hello.info
address@hidden UPDATED 28 March 2002
address@hidden UPDATED-MONTH March 2002
address@hidden EDITION 4.2
address@hidden VERSION 4.2
address@hidden GNU Hello 4.2
address@hidden %**end of header
+
address@hidden If your manual is published on paper by the FSF, it should
include
address@hidden the standard FSF Front-Cover and Back-Cover Texts, as given in
address@hidden maintain.texi.
+
address@hidden Define a new index for options.
address@hidden op
address@hidden Combine everything into one index (arbitrarily chosen to be the
address@hidden concept index).
address@hidden op cp
+
address@hidden Basics
address@hidden
+* Hello: (hello). Hello, GNU world.
address@hidden direntry
+
+
address@hidden
+
+
address@hidden Top
address@hidden GNU Hello
+
+This manual is for GNU Hello (version 4.2, 28 March 2002).
+
address@hidden
+* Overview:: General purpose and information.
+* Sample output:: Sample output from @command{hello}.
+* Invoking hello:: How to run @command{hello}.
+* Reporting bugs:: Sending bug reports and feature suggestions.
+* GNU Free Documentation License:: Copying and sharing this documentation.
+* Concept index:: Index of concepts.
address@hidden menu
+
+
address@hidden Overview
address@hidden Overview
+
address@hidden greetings
address@hidden overview
+
+The GNU @command{hello} program
+(@url{http://www.gnu.org/software/hello/}) produces a familiar,
+friendly greeting. It allows nonprogrammers to use a classic computer
+science tool which would otherwise be unavailable to them. Because it
+is protected by the GNU General Public License, users are free (in
+perpetuity) to share and change it.
+
address@hidden joke, not
+Not to spoil the joke, but of course the practical purpose of GNU
+Hello is to serve as a minimal example of a GNU package. So, although
+most manuals don't need to discuss the implementation of the programs
+they document, that is part of the goal here.
+
address@hidden GNU coding standards
address@hidden GNU maintainer standards
address@hidden standards, GNU coding
address@hidden standards, GNU maintainer
+First, GNU Hello follows the GNU coding standards
+(@pxref{Top,,Preface,standards, GNU Coding Standards}) and GNU
+maintainer standards (@pxref{Top,,Preface,maintain, Information for
+GNU Maintainers}). These are the basic documents which all GNU
+packages should adhere to.
+
+The Hello package also implements recommended development practices
+not embodied in the standards, using other GNU packages and features:
+
address@hidden @bullet
+
address@hidden
address@hidden Automake
address@hidden Autoconf
+It uses Automake (@pxref{Top,,Introduction,Automake,GNU Automake}) and
+hence also Autoconf (@pxref{Top,,Introduction,Autoconf,GNU Autoconf})
+for configuration.
+
address@hidden
address@hidden Gnulib
+It uses Gnulib (@pxref{Top,,Gnulib,gnulib,GNU Gnulib}) to enhance
+portability and avoid duplication of common sources.
+
address@hidden
address@hidden Gettext
+GNU Gettext (@pxref{Top,,Introduction,gettext,GNU Gettext}) is used
+for internationalization support. Hello's greeting has been translated
+into many languages.
+
address@hidden
address@hidden --help
+Internally, Hello uses the GNU @code{getopt_long} function
+(@pxref{Getopt Long Options,,,libc,GNU C Library}) to parse options,
+thus supporting GNU-style long options such as @option{--help}.
+
address@hidden
address@hidden Help2man
+Man pages are generated with GNU @code{help2man}
+(@pxref{Top,,Overview,help2man,GNU @code{help2man}}) from the
address@hidden output. This relieves the maintainers of the burden
+of maintaining man documentation separately, yet provides a reasonable
+overview for man devotees.
+
address@hidden
address@hidden Texinfo
+Finally, Texinfo (@pxref{Top,,Introduction,texinfo,Texinfo}) is the
+documentation format for this manual. It supports output in Info,
+HTML, PDF, DVI, plain text, XML, and other formats.
+
address@hidden itemize
+
+GNU Hello is implemented in C. GNU Gettext contains ``hello world''
+examples in a variety of other programming languages; see the Gettext
+home page at @url{http://www.gnu.org/software/gettext/}.
+
address@hidden authors
address@hidden Haertel, Mike
address@hidden MacKenzie, David
address@hidden Brittenson, Jan
address@hidden Hannum, Charles
address@hidden McGrath, Roland
address@hidden Friedman, Noah
address@hidden Eichwalder, Karl
address@hidden King, The
address@hidden Berry, Karl
+GNU Hello was written by Mike Haertel, David MacKenzie, Jan
+Brittenson, Charles Hannum, Roland McGrath, Noah Friedman, Karl
+Eichwalder, Karl Berry, and @w{The King}.
+
+
address@hidden Sample output
address@hidden Sample output
+
address@hidden sample output
address@hidden examples
+
+Here are some realistic examples of running GNU Hello.
+
+This is the output of the command @samp{hello}:
+
address@hidden
+Hello, world!
address@hidden example
+
+This is the output of the command @samp{hello --traditional}:
+
address@hidden
+hello, world
address@hidden example
+
+This is the output of the command @samp{hello --greeting=hi}:
+
address@hidden
+hi
address@hidden example
+
+
address@hidden Invoking hello
address@hidden Invoking @command{hello}
+
address@hidden invoking
address@hidden options
address@hidden usage
address@hidden help
+
+The format for running the @command{hello} program is:
+
address@hidden
+hello @var{option} @dots{}
address@hidden example
+
+With no options, @command{hello} prints the greeting @samp{Hello,
+world!}.
+
address@hidden supports the following options:
+
address@hidden @option
address@hidden address@hidden
address@hidden -g @var{text}
address@hidden --greeting
address@hidden -g
+Output @var{text} instead of the default greeting.
+
address@hidden --help
address@hidden -h
address@hidden --help
address@hidden -h
+Print an informative help message on standard output and exit
+successfully.
+
address@hidden environment variables, help for
+For the @option{--help} output of GNU programs, it's strongly
+encouraged to include a brief (one or two sentences) description of
+what the program does, as well as the synopsis of how to run the
+program. Any environment variables which affect execution should also
+be mentioned (Hello doesn't have any).
+
address@hidden --next-generation
address@hidden -n
address@hidden --next-generation
address@hidden -n
+Output @samp{Hello, world!}, but possibly including box-drawing
+characters or other fancy stuff, especially in translated locales.
+(If you would like to volunteer to translate messages for GNU packages,
+please see @url{http://translationproject.org}.)
+
address@hidden --traditional
address@hidden -t
address@hidden --traditional
address@hidden -t
address@hidden traditional
address@hidden modern
+Output the traditional greeting message @samp{hello, world}.
+
address@hidden --version
address@hidden -v
address@hidden --version
address@hidden -v
+Print the version number and licensing information of Hello on
+standard output and then exit successfully.
+
address@hidden table
+
+If more than one of the greeting options (@option{-g}, @option{-n},
address@hidden, and their long-named equivalents) is specified, whichever
+comes last takes precedence.
+
+
address@hidden Reporting bugs
address@hidden Reporting bugs
+
address@hidden bug reporting
address@hidden problems
address@hidden reporting bugs
+
+To report bugs or suggest enhancements for GNU Hello, please
+send electronic mail to @email{bug-hello@@gnu.org}.
+
address@hidden checklist for bug reports
+For bug reports, please include enough information for the maintainers
+to reproduce the problem. Generally speaking, that means:
+
address@hidden @bullet
address@hidden The version numbers of Hello (which you can find by running
+ @address@hidden --version}}) and any other program(s) or
+ manual(s) involved.
address@hidden Hardware and operating system names and versions.
address@hidden The contents of any input files necessary to reproduce the bug.
address@hidden The expected behavior and/or output.
address@hidden A description of the problem and samples of any erroneous output.
address@hidden Options you gave to @command{configure} other than specifying
+ installation directories.
address@hidden Anything else that you think would be helpful.
address@hidden 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.
+
address@hidden patches, contributing
+Patches are welcome; if possible, please make them with @address@hidden
+-c}} (@pxref{Top,, Overview, diff, Comparing and Merging Files}) and
+include @file{ChangeLog} entries (@pxref{Change Log,,, emacs, The GNU
+Emacs Manual}). Please follow the existing coding style.
+
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
+
address@hidden The GNU Free Documentation License.
address@hidden Version 1.3, 3 November 2008
+
address@hidden This file is intended to be included within another document,
address@hidden hence no sectioning command or @node.
+
address@hidden
+Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation,
Inc.
address@hidden://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
address@hidden display
+
address@hidden 0
address@hidden
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{free} in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
address@hidden
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The ``Document'', below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as ``you''. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section
+of the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall
+subject (or to related matters) and contains nothing that could fall
+directly within that overall subject. (Thus, if the Document is in
+part a textbook of mathematics, a Secondary Section may not explain
+any mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
address@hidden without markup, Texinfo input format, address@hidden input
+format, @acronym{SGML} or @acronym{XML} using a publicly available
address@hidden, and standard-conforming simple @acronym{HTML},
+PostScript or @acronym{PDF} designed for human modification. Examples
+of transparent image formats include @acronym{PNG}, @acronym{XCF} and
address@hidden Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, @acronym{SGML} or
address@hidden for which the @acronym{DTD} and/or processing tools are
+not generally available, and the machine-generated @acronym{HTML},
+PostScript or @acronym{PDF} produced by some word processors for
+output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+The ``publisher'' means any person or entity that distributes copies
+of the Document to the public.
+
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements'',
+``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
address@hidden
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
address@hidden
+COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
address@hidden
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
address@hidden A
address@hidden
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
address@hidden
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
+
address@hidden
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
address@hidden
+Preserve all the copyright notices of the Document.
+
address@hidden
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
address@hidden
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
address@hidden
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
address@hidden
+Include an unaltered copy of this License.
+
address@hidden
+Preserve the section Entitled ``History'', Preserve its Title, and add
+to it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section Entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
address@hidden
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
address@hidden
+For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
+the Title of the section, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements and/or
+dedications given therein.
+
address@hidden
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
address@hidden
+Delete any section Entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
address@hidden
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
address@hidden
+Preserve any Warranty Disclaimers.
address@hidden enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
address@hidden
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements'',
+and any sections Entitled ``Dedications''. You must delete all
+sections Entitled ``Endorsements.''
+
address@hidden
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
address@hidden
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
address@hidden
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
address@hidden
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document
+except as expressly provided under this License. Any attempt
+otherwise to copy, modify, sublicense, or distribute it is void, and
+will automatically terminate your rights under this License.
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License. If your rights have been terminated and not permanently
+reinstated, receipt of a copy of some or all of the same material does
+not give you any rights to use it.
+
address@hidden
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
address@hidden://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation. If the Document
+specifies that a proxy can decide which future versions of this
+License can be used, that proxy's public statement of acceptance of a
+version permanently authorizes you to choose that version for the
+Document.
+
address@hidden
+RELICENSING
+
+``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
+World Wide Web server that publishes copyrightable works and also
+provides prominent facilities for anybody to edit those works. A
+public wiki that anybody can edit is an example of such a server. A
+``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
+site means any set of copyrightable works thus published on the MMC
+site.
+
+``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
+license published by Creative Commons Corporation, a not-for-profit
+corporation with a principal place of business in San Francisco,
+California, as well as future copyleft versions of that license
+published by that same organization.
+
+``Incorporate'' means to publish or republish a Document, in whole or
+in part, as part of another Document.
+
+An MMC is ``eligible for relicensing'' if it is licensed under this
+License, and if all works that were first published under this License
+somewhere other than this MMC, and subsequently incorporated in whole
+or in part into the MMC, (1) had no cover texts or invariant sections,
+and (2) were thus incorporated prior to November 1, 2008.
+
+The operator of an MMC Site may republish an MMC contained in the site
+under CC-BY-SA on the same site at any time before August 1, 2009,
+provided the MMC is eligible for relicensing.
+
address@hidden enumerate
+
address@hidden
address@hidden ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
address@hidden
address@hidden
+ Copyright (C) @var{year} @var{your name}.
+ 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, no Front-Cover Texts, and no Back-Cover
+ Texts. A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
address@hidden group
address@hidden smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the address@hidden'' line with this:
+
address@hidden
address@hidden
+ with the Invariant Sections being @var{list their titles}, with
+ the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
+ being @var{list}.
address@hidden group
address@hidden smallexample
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
address@hidden Local Variables:
address@hidden ispell-local-pdict: "ispell-dict"
address@hidden End:
+
+
+
address@hidden Concept index
address@hidden Concept index
+
address@hidden cp
+
address@hidden
Index: res/texi_info-stnd/info-stnd.texi.first
===================================================================
RCS file: res/texi_info-stnd/info-stnd.texi.first
diff -N res/texi_info-stnd/info-stnd.texi.first
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ res/texi_info-stnd/info-stnd.texi.first 2 Aug 2009 13:10:59 -0000
1.1
@@ -0,0 +1,2521 @@
+\input texinfo @c -*-texinfo-*-
address@hidden Id: info-stnd.texi,v 1.1 2003/02/03 16:10:29 pertusus Exp $
address@hidden %**start of header
address@hidden info-stnd.info
address@hidden UPDATED 23 March 2002
address@hidden UPDATED-MONTH March 2002
address@hidden EDITION 4.2
address@hidden VERSION 4.2
address@hidden GNU Info 4.2
address@hidden vr cp
address@hidden fn cp
address@hidden ky cp
address@hidden %**end of header
+
+
address@hidden Texinfo documentation system
address@hidden
+* info standalone: (info-stnd). Read Info documents without Emacs.
+* infokey: (info-stnd)Invoking infokey. Compile Info customizations.
address@hidden direntry
+
+
address@hidden
+
address@hidden Top
address@hidden GNU Info
+
address@hidden
+
+This documentation is different from the documentation for the Info
+reader that is part of GNU Emacs. If you do not know how to use Info,
+but have a working Info reader, you should read the Emacs documentation
+first, as it includes more background information and a thorough tutorial.
+
address@hidden
+* What is Info:: What is Info?
+* Invoking Info:: Options you can pass on the command line.
+* Cursor Commands:: Commands which move the cursor within a node.
+* Scrolling Commands:: Commands for reading the text within a node.
+* Node Commands:: Commands for selecting a new node.
+* Searching Commands:: Commands for searching an Info file.
+* Xref Commands:: Commands for selecting cross references.
+* Window Commands:: Commands which manipulate multiple windows.
+* Printing Nodes:: How to print out the contents of a node.
+* Miscellaneous Commands:: A few commands that defy categories.
+* Variables:: How to change the default behavior of Info.
+* Custom Key Bindings:: How to define your own key-to-command
+ bindings.
+* Copying This Manual:: The GNU Free Documentation License.
+* Index:: Global index containing keystrokes,
+ command names, variable names,
+ and general concepts.
address@hidden menu
+
+
address@hidden What is Info
address@hidden What is Info?
+
address@hidden is a program which is used to view Info files on an ASCII
+terminal. @dfn{Info files} are the result of processing Texinfo files
+with the program @code{makeinfo} or with one of the Emacs commands, such
+as @code{M-x texinfo-format-buffer}. Texinfo itself is a documentation
+system that uses a single source file to produce both on-line
+information and printed output. You can typeset and print the files
+that you read in Info.
+
+
address@hidden Invoking Info
address@hidden Invoking Info
+
address@hidden Info, invoking
address@hidden invoking Info
address@hidden command line options
address@hidden options, command line
address@hidden arguments, command line
+
+GNU Info accepts several options to control the initial node being
+viewed, and to specify which directories to search for Info files. Here
+is a template showing an invocation of GNU Info from the shell:
+
address@hidden
+info address@hidden@dots{} address@hidden@dots{}]
address@hidden example
+
+The program accepts the following options:
+
address@hidden @code
address@hidden
address@hidden address@hidden
address@hidden Searching all indices
address@hidden Info address@hidden, searching all indices}
address@hidden address@hidden, in Info files}
+Specify a string to search in every index of every Info file installed
+on your system. Info looks up the named @var{string} in all the indices
+it can find, prints the results to standard output, and then exits. If
+you are not sure which Info file explains certain issues, this option is
+your friend. Note that if your system has a lot of Info files
+installed, searching all of them might take some time.
+
+You can invoke the apropos command from inside Info; see
address@hidden Commands}.
+
address@hidden directory path
address@hidden --directory @var{directory-path}
address@hidden -d @var{directory-path}
+Prepend @var{directory-path} to the list of directory paths searched
+when Info needs to find a file. You may issue @code{--directory}
+multiple times; once for each directory which contains Info files. The
+list of directories searched by Info is constructed from the value of
+the environment variable @code{INFOPATH}; @code{--directory} causes the
+named @var{directory-path} to be prepended to that list. The value of
address@hidden is a list of directories usually separated by a colon;
+on MS-DOS/MS-Windows systems, the semicolon is used. If you do not
+define @code{INFOPATH}, Info uses a default path defined when Info was
+built as the initial list of directories. If the value of
address@hidden ends with a colon (or semicolon on MS-DOS/MS-Windows),
+the initial list of directories is constructed by appending the
+build-time default to the value of @code{INFOPATH}.
+
address@hidden keystrokes, recording
address@hidden remembering user keystrokes
address@hidden address@hidden
+Specify a file where all user keystrokes will be recorded. This file
+can be used later to replay the same sequence of commands, see the
address@hidden option below.
+
address@hidden --file @var{filename}
address@hidden -f @var{filename}
address@hidden Info file, selecting
+Specify a particular Info file to visit. By default, Info visits
+the file @code{dir}; if you use this option, Info will start with
address@hidden(@var{filename})Top} as the first file and node.
+
address@hidden relative Info file names
address@hidden file names, relative
address@hidden Info files, relative
+If @var{filename} is an absolute file name, or begins with @file{./} or
address@hidden/}, Info looks for @var{filename} only in the directory of the
+specified @var{filename}, and adds the directory of @var{filename} to
+the value of @code{INFOPATH}. In contrast, if @var{filename} is in the
+form of a relative file name, but without the @file{./} or @file{../}
+prefix, Info will only look for it in the directories specified in
address@hidden In other words, Info does @emph{not} treat file names
+which lack @file{./} and @file{../} prefix as relative to the current
+directory.
+
address@hidden compressed Info files
address@hidden files, compressed
address@hidden Info files, compressed
+In every directory Info tries, if @var{filename} is not found, Info
+looks for it with a number of known extensions of Info address@hidden
address@hidden, @file{-info}, @file{/index}, and @file{.inf}.}. For every
+known extension, Info looks for a compressed file, if a regular file
+isn't found. Info supports files compressed with @code{gzip},
address@hidden, @code{compress} and @code{yabba} programs; it calls
address@hidden, @code{bunzip2}, @code{uncompress} and @code{unyabba},
+accordingly, to decompress such files. Compressed Info files are
+assumed to have @file{.z}, @file{.gz}, @file{.bz2}, @file{.Z}, or
address@hidden extensions, possibly in addition to one of the known Info
+files address@hidden MS-DOS version allows for the Info
+extension, such as @code{.inf}, and the short compressed file
+extensions, such as @file{.z} and @file{.gz}, to be merged into a single
+extension, since DOS doesn't allow more than a single dot in the
+basename of a file. Thus, on MS-DOS, if Info looks for @file{bison},
+file names like @file{bison.igz} and @file{bison.inz} will be found and
+decompressed by @code{gunzip}.}.
+
address@hidden --help
address@hidden -h
+Produces a relatively brief description of the available Info options.
+
address@hidden --index-search @var{string}
address@hidden index search, selecting from the command line
address@hidden online help, using Info as
+After processing all command-line arguments, go to the index in the Info
+file and search for index entries which matche @var{string}. If such an
+entry is found, the Info session begins with displaying the node pointed
+to by the first matching index entry; press @kbd{,} to step through the
+rest of the matching entries. If no such entry exists, print @samp{no
+entries found} and exit with nonzero status. This can be used from
+another program as a way to provide online help, or as a quick way of
+starting to read an Info file at a certain node when you don't know the
+exact name of that node.
+
+This command can also be invoked from inside Info; see @ref{Searching
+Commands}.
+
address@hidden --node @var{nodename}
address@hidden -n @var{nodename}
address@hidden node, selecting from the command line
+Specify a particular node to visit in the initial file that Info
+loads. This is especially useful in conjunction with
address@hidden@footnote{Of course, you can specify both the file and node
+in a @code{--node} command; but don't forget to escape the open and
+close parentheses and whitespace from the shell as in: @code{info --node
+"(emacs)Buffers"}.}. You may specify @code{--node} multiple times; for
+an interactive Info, each @var{nodename} is visited in its own window,
+for a non-interactive Info (such as when @code{--output} is given) each
address@hidden is processed sequentially.
+
address@hidden --output @var{filename}
address@hidden -o @var{filename}
address@hidden file, outputting to
address@hidden outputting to a file
+Specify @var{filename} as the name of a file to which to direct output.
+Each node that Info visits will be output to @var{filename} instead of
+interactively viewed. A value of @code{-} for @var{filename} specifies
+the standard output.
+
address@hidden colors in man pages
address@hidden ANSI escape sequences in man pages
address@hidden --raw-escapes
address@hidden -R
+Do not remove ANSI escape sequences from man pages. Some versions of
+Groff, the GNU document formatter, produce man pages with ANSI escape
+sequences for bold, italics, and underlined characters, and for
+colorized text. By default, Info removes those escape sequences
+before it displays the man page. If your terminal supports these
+escapes, use @code{--raw-escapes} to let the terminal handle them and
+display the man pages with those attributes.
+
address@hidden replaying recorded keystrokes
address@hidden address@hidden
+Read keystrokes from @var{dribble-file}, presumably recorded during
+previous Info session (see the description of the @samp{--dribble}
+option above). When the keystrokes in the files are all read, Info
+reverts its input to the usual interactive operation.
+
address@hidden
address@hidden command-line options, how to find
address@hidden invocation description, how to find
address@hidden --show-options
address@hidden --usage
address@hidden -O
+This option causes Info to look for the node that describes how to
+invoke the program and its command-line options, and begin the session
+by displaying that node. It is provided to make it easier to find the
+most important usage information in a manual without the need to wade
+through complex menu hierarchies. The effect is similar to the
address@hidden goto-invocation} command (@pxref{goto-invocation}) from inside
+Info.
+
address@hidden speech synthesizers
address@hidden --speech-friendly
address@hidden -b
+On MS-DOS/MS-Windows only, this option causes Info to use standard file
+I/O functions for screen writes. (By default, Info uses direct writes
+to the video memory on these systems, for faster operation and colored
+display support.) This allows the speech synthesizers used by blind
+persons to catch the output and convert it to audible speech.
+
address@hidden --subnodes
address@hidden @code{--subnodes}, command line option
+This option only has meaning when given in conjunction with
address@hidden It means to recursively output the nodes appearing in
+the menus of each node being output. Menu items which resolve to
+external Info files are not output, and neither are menu items which are
+members of an index. Each node is only output once.
+
address@hidden --version
address@hidden version information
+Prints the version information of Info and exits.
+
address@hidden
address@hidden vi-like key bindings
address@hidden Less-like key bindings
address@hidden --vi-keys
+This option binds functions to keys differently, to emulate the key
+bindings of @code{vi} and Less. The default key bindings are generally
+modeled after Emacs.
+(@xref{Custom Key Bindings},
+for a more general way of altering GNU Info's key bindings.)
+
address@hidden @var{menu-item}
address@hidden menu, following
address@hidden menu items}
+Info treats its remaining arguments as the names of menu items. The
+first argument is a menu item in the initial node visited (generally
address@hidden), the second argument is a menu item in the first argument's
+node, etc. You can easily move to the node of your choice by specifying
+the menu names which describe the path to that node. For example,
+
address@hidden
+info emacs buffers
address@hidden example
+
address@hidden
+first selects the menu item @samp{Emacs} in the node @samp{(dir)Top},
+and then selects the menu item @samp{Buffers} in the node
address@hidden(emacs)Top}.
address@hidden table
+
+To avoid searching the @file{dir} files and just show some arbitrary
+file, use @samp{-f} and the filename, as in @samp{info -f ./foo.info}.
+
+The index search and the search for the node which describes program
+invocation and command-line options begins @emph{after} processing all
+the command-line menu items. Therefore, the Info file searched for the
+index or the invocation node is the file where Info finds itself after
+following all the menu items given on the command line. This is so
address@hidden emacs --show-options} does what you'd expect.
+
address@hidden FIXME: the feature with lowercasing the file name isn't
documented
+
+
address@hidden Cursor Commands
address@hidden Moving the Cursor
address@hidden cursor, moving
address@hidden moving the cursor
+
+Many people find that reading screens of text page by page is made
+easier when one is able to indicate particular pieces of text with some
+kind of pointing device. Since this is the case, GNU Info (both the
+Emacs and standalone versions) have several commands which allow you to
+move the cursor about the screen. The notation used in this manual to
+describe keystrokes is identical to the notation used within the Emacs
+manual, and the GNU Readline manual. @xref{Characters, , Character
+Conventions, emacs, the GNU Emacs Manual}, if you are unfamiliar with the
address@hidden
+Here's a short summary. @address@hidden means press the @kbd{CTRL} key
+and the key @var{x}. @address@hidden means press the @kbd{META} key and
+the key @var{x}. On many terminals th @kbd{META} key is known as the
address@hidden key. @kbd{SPC} is the space bar. The other keys are usually
+called by the names imprinted on them.}.
+
+The following table lists the basic cursor movement commands in Info.
+Each entry consists of the key sequence you should type to execute the
+cursor movement, the @address@hidden@code{M-x} is also a command; it
+invokes @code{execute-extended-command}. @xref{M-x, , Executing an
+extended command, emacs, the GNU Emacs Manual}, for more detailed
+information.} command name (displayed in parentheses), and a short
+description of what the command does. All of the cursor motion commands
+can take a @dfn{numeric} argument (see @ref{Miscellaneous Commands,
address@hidden, to find out how to supply them}. With a
+numeric argument, the motion commands are simply executed that
+many times; for example, a numeric argument of 4 given to
address@hidden causes the cursor to move down 4 lines. With a
+negative numeric argument, the motion is reversed; an argument of -4
+given to the @code{next-line} command would cause the cursor to move
address@hidden 4 lines.
+
address@hidden @asis
address@hidden @key{C-n} (@code{next-line})
address@hidden @key{DOWN} (an arrow key)
address@hidden C-n
address@hidden DOWN (an arrow key)
address@hidden next-line
+Move the cursor down to the next line.
+
address@hidden @key{C-p} (@code{prev-line})
address@hidden @key{UP} (an arrow key)
address@hidden C-p
address@hidden UP (an arrow key)
address@hidden prev-line
+Move the cursor up to the previous line.
+
address@hidden @key{C-a} (@code{beginning-of-line})
address@hidden @key{Home} (on DOS/Windows only)
address@hidden C-a, in Info windows
address@hidden Home
address@hidden beginning-of-line
+Move the cursor to the start of the current line.
+
address@hidden @key{C-e} (@code{end-of-line})
address@hidden @key{End} (on DOS/Windows only)
address@hidden C-e, in Info windows
address@hidden End
address@hidden end-of-line
+Move the cursor to the end of the current line.
+
address@hidden @key{C-f} (@code{forward-char})
address@hidden @key{RIGHT} (an arrow key)
address@hidden C-f, in Info windows
address@hidden RIGHT (an arrow key)
address@hidden forward-char
+Move the cursor forward a character.
+
address@hidden @key{C-b} (@code{backward-char})
address@hidden @key{LEFT} (an arrow key)
address@hidden C-b, in Info windows
address@hidden LEFT (an arrow key)
address@hidden backward-char
+Move the cursor backward a character.
+
address@hidden @key{M-f} (@code{forward-word})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden M-f, in Info windows
address@hidden C-RIGHT
address@hidden forward-word
+Move the cursor forward a word.
+
address@hidden @key{M-b} (@code{backward-word})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden M-b, in Info windows
address@hidden C-LEFT
address@hidden backward-word
+Move the cursor backward a word.
+
address@hidden @key{M-<} (@code{beginning-of-node})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden @key{b}
address@hidden @key{M-b}, vi-like operation
address@hidden b, in Info windows
address@hidden M-<
address@hidden C-Home
address@hidden M-b, vi-like operation
address@hidden beginning-of-node
+Move the cursor to the start of the current node.
+
address@hidden @key{M->} (@code{end-of-node})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden @key{e}
address@hidden M->
address@hidden e, in Info windows
address@hidden C-End
address@hidden end-of-node
+Move the cursor to the end of the current node.
+
address@hidden @key{M-r} (@code{move-to-window-line})
address@hidden M-r
address@hidden move-to-window-line
+Move the cursor to a specific line of the window. Without a numeric
+argument, @code{M-r} moves the cursor to the start of the line in the
+center of the window. With a numeric argument of @var{n}, @code{M-r}
+moves the cursor to the start of the @var{n}th line in the window.
address@hidden table
+
+
address@hidden Scrolling Commands
address@hidden Moving Text Within a Window
address@hidden scrolling
+
+Sometimes you are looking at a screenful of text, and only part of the
+current paragraph you are reading is visible on the screen. The
+commands detailed in this section are used to shift which part of the
+current node is visible on the screen.
+
+Scrolling commands are bound differently when @samp{--vi-keys} operation
+(@pxref{--vi-keys}) is in effect. These key bindings are designated
+with ``vi-like operation''.
+
address@hidden @asis
address@hidden @key{SPC} (@code{scroll-forward})
address@hidden SPC, in Info windows
address@hidden scroll-forward
+Shift the text in this window up. That is, show more of the node which
+is currently below the bottom of the window. With a numeric argument,
+show that many more lines at the bottom of the window; a numeric
+argument of 4 would shift all of the text in the window up 4 lines
+(discarding the top 4 lines), and show you four new lines at the bottom
+of the window. Without a numeric argument, @key{SPC} takes the bottom
+two lines of the window and places them at the top of the window,
+redisplaying almost a completely new screenful of lines. If you are at
+the end of a node, @key{SPC} takes you to the ``next'' node, so that you can
+read an entire manual from start to finish by repeating @key{SPC}.
+
+The default scroll size is one screen-full, but it can be changed by
+invoking the (@code{scroll-forward-page-only-set-window}) command,
address@hidden under @samp{--vi-keys}, with a numeric argument.
+
address@hidden @key{NEXT} (an arrow key) (@code{scroll-forward-page-only})
address@hidden @key{C-v}
address@hidden @key{C-f}, vi-like operation
address@hidden @key{f}, vi-like operation
address@hidden @key{M-SPC}, vi-like operation
address@hidden NEXT
address@hidden C-v
address@hidden C-f, vi-like operation
address@hidden f, vi-like operation
address@hidden M-SPC, vi-like operation
address@hidden scroll-forward-page-only
+Shift the text in this window up. This is identical to the @key{SPC}
+operation above, except that it never scrolls beyond the end of the
+current node.
+
address@hidden PageDown
+The @key{NEXT} key is known as the @key{PageDown} key on some
+keyboards.
+
address@hidden @key{z} (@code{scroll-forward-page-only-set-window}, vi-like
operation)
address@hidden z, vi-like operation
address@hidden scroll-forward-page-only-set-window
+Scroll forward, like with @key{NEXT}, but if a numeric argument is
+specified, it becomes the default scroll size for subsequent
address@hidden and @code{scroll-backward} commands and their
+ilk.
+
address@hidden @key{DEL} (@code{scroll-backward})
address@hidden DEL, in Info windows
address@hidden scroll-backward
+Shift the text in this window down. The inverse of
address@hidden
+If you are at the start of a node, @key{DEL} takes you to the
+``previous'' node, so that you can read an entire manual from finish to
+start by repeating @key{DEL}. The default scroll size can be changed by
+invoking the (@code{scroll-backward-page-only-set-window}) command,
address@hidden under @samp{--vi-keys}, with a numeric argument.
+
address@hidden @key{PREVIOUS} (arrow key) (@code{scroll-backward-page-only})
address@hidden @key{PRIOR} (arrow key)
address@hidden @key{M-v}
address@hidden @key{b}, vi-like operation
address@hidden @key{C-b}, vi-like operation
address@hidden PREVIOUS
address@hidden M-v
address@hidden b, vi-like operation
address@hidden C-b, vi-like operation
address@hidden scroll-backward-page-only
+Shift the text in this window down. The inverse of
address@hidden Does not scroll beyond the start of
+the current node. The default scroll size can be changed by invoking
+the(@code{scroll-backward-page-only-set-window}) command, @samp{w} under
address@hidden, with a numeric argument.
+
address@hidden @key{w} (@code{scroll-backward-page-only-set-window}, vi-like
operation)
address@hidden w, vi-like operation
address@hidden scroll-backward-page-only-set-window
+Scroll backward, like with @key{PREVIOUS}, but if a numeric argument is
+specified, it becomes the default scroll size for subsequent
address@hidden and @code{scroll-backward} commands.
+
address@hidden @key{C-n} (@code{down-line}, vi-like operation)
address@hidden @key{C-e}, vi-like operation
address@hidden @key{RET}, vi-like operation
address@hidden @key{LFD}, vi-like operation
address@hidden @key{DOWN}, vi-like operation
address@hidden C-n, vi-like operation
address@hidden C-e, vi-like operation
address@hidden RET, vi-like operation
address@hidden LFD, vi-like operation
address@hidden DOWN, vi-like operation
address@hidden down-line
+Scroll forward by one line. With a numeric argument, scroll forward
+that many lines.
+
address@hidden @key{C-p} (@code{up-line}, vi-like operation)
address@hidden @key{UP}, vi-like operation
address@hidden @key{y}, vi-like operation
address@hidden @key{k}, vi-like operation
address@hidden @key{C-k}, vi-like operation
address@hidden @key{C-y}, vi-like operation
address@hidden C-p, vi-like operation
address@hidden UP, vi-like operation
address@hidden y, vi-like operation
address@hidden k, vi-like operation
address@hidden C-k, vi-like operation
address@hidden C-y, vi-like operation
address@hidden up-line
+Scroll backward one line. With a numeric argument, scroll backward that
+many lines.
+
address@hidden @key{d} (@code{scroll-half-screen-down}, vi-like operation)
address@hidden @key{C-d}, vi-like operation
address@hidden d, vi-like operation
address@hidden C-d, vi-like operation
address@hidden scroll-half-screen-down
+Scroll forward by half of the screen size. With a numeric argument,
+scroll that many lines. If an argument is specified, it becomes the new
+default number of lines to scroll for subsequent @samp{d} and @samp{u}
+commands.
+
address@hidden @key{u} (@code{scroll-half-screen-up}, vi-like operation)
address@hidden @key{C-u}, vi-like operation
address@hidden u, vi-like operation
address@hidden C-u, vi-like operation
address@hidden scroll-half-screen-up
+Scroll back by half of the screen size. With a numeric argument,
+scroll that many lines. If an argument is specified, it becomes the new
+default number of lines to scroll for subsequent @samp{u} and @samp{d}
+commands.
address@hidden table
+
address@hidden scrolling through node structure
+The @code{scroll-forward} and @code{scroll-backward} commands can also
+move forward and backward through the node structure of the file. If
+you press @key{SPC} while viewing the end of a node, or @key{DEL} while
+viewing the beginning of a node, what happens is controlled by the
+variable @code{scroll-behavior}. @xref{Variables,
address@hidden, for more information.
+
+The @code{scroll-forward-page-only} and @code{scroll-backward-page-only}
+commands never scroll beyond the current node.
+
address@hidden PageUp
+The @key{PREVIOUS} key is the @key{PageUp} key on many keyboards. Emacs
+refers to it by the name @key{PRIOR}. When you use @key{PRIOR} or
address@hidden to scroll, Info never scrolls beyond the beginning of the
+current node.
+
address@hidden BS (backspace)
+If your keyboard lacks the @key{DEL} key, look for a key called
address@hidden, or @samp{BackSpace}, sometimes designated with an arrow which
+points to the left, which should perform the same function.
+
address@hidden @asis
address@hidden @key{C-l} (@code{redraw-display})
address@hidden C-l
address@hidden redraw-display
+Redraw the display from scratch, or shift the line containing the cursor
+to a specified location. With no numeric argument, @samp{C-l} clears
+the screen, and then redraws its entire contents. Given a numeric
+argument of @var{n}, the line containing the cursor is shifted so that
+it is on the @var{n}th line of the window.
+
address@hidden @kbd{C-x @key{w}} (@code{toggle-wrap})
address@hidden C-w
address@hidden toggle-wrap
+Toggles the state of line wrapping in the current window. Normally,
+lines which are longer than the screen width @dfn{wrap}, i.e., they are
+continued on the next line. Lines which wrap have a @samp{\} appearing
+in the rightmost column of the screen. You can cause such lines to be
+terminated at the rightmost column by changing the state of line
+wrapping in the window with @code{C-x w}. When a line which needs more
+space than one screen width to display is displayed, a @samp{$} appears
+in the rightmost column of the screen, and the remainder of the line is
+invisible. When long lines are truncated, the modeline displays the
address@hidden character near its left edge.
address@hidden table
+
+
address@hidden Node Commands
address@hidden Selecting a Node
address@hidden nodes, selection of
+
+This section details the numerous Info commands which select a new node
+to view in the current window.
+
+The most basic node commands are @samp{n}, @samp{p}, @samp{u}, and
address@hidden Note that the commands to select nodes are mapped differently
+when @samp{--vi-keys} is in effect; these keybindings are designated
+below as ``vi-like operation''.
+
+When you are viewing a node, the top line of the node contains some Info
address@hidden which describe where the next, previous, and up nodes
+are. Info uses this line to move about the node structure of the file
+when you use the following commands:
+
address@hidden @asis
address@hidden @key{n} (@code{next-node})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden @kbd{C-x @key{n}}, vi-like operation
address@hidden n
address@hidden C-NEXT
address@hidden C-x n, vi-like operation
address@hidden next-node
+Select the `Next' node.
+
address@hidden C-PgDn
+The @key{NEXT} key is known as the @key{PgDn} key on some
+keyboards.
+
address@hidden @key{p} (@code{prev-node})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden p
address@hidden C-PREVIOUS
address@hidden prev-node
+Select the `Prev' node.
+
address@hidden C-PgUp
+The @key{PREVIOUS} key is known as the @key{PgUp} key on some
+keyboards.
+
address@hidden @key{u} (@code{up-node})
address@hidden @address@hidden (an arrow key on DOS/Windows only)
address@hidden @kbd{C-x @key{u}}, vi-like operation
address@hidden u
address@hidden C-UP
address@hidden C-x u, vi-like operation
address@hidden up-node
+Select the `Up' node.
address@hidden table
+
+You can easily select a node that you have already viewed in this window
+by using the @samp{l} command -- this name stands for "last", and
+actually moves backwards through the history of visited nodes for this
+window. This is handy when you followed a reference to another node,
+possibly to read about a related issue, and would like then to resume
+reading at the same place where you started the excursion.
+
+Each node where you press @samp{l} is discarded from the history. Thus,
+by the time you get to the first node you visited in a window, the
+entire history of that window is discarded.
+
address@hidden @asis
address@hidden @key{l} (@code{history-node})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden @key{'}, vi-like operation
address@hidden l
address@hidden C-CENTER
address@hidden ', vi-like operation
address@hidden history-node
+Pop the most recently selected node in this window from the node
+history.
address@hidden table
+
+Two additional commands make it easy to select the most commonly
+selected nodes; they are @samp{t} and @samp{d}.
+
address@hidden @asis
address@hidden @key{t} (@code{top-node})
address@hidden @key{M-t}, vi-like operation
address@hidden t
address@hidden M-t, vi-like operation
address@hidden top-node
+Select the node @samp{Top} in the current Info file.
+
address@hidden @key{d} (@code{dir-node})
address@hidden @key{M-d}, vi-like operation
address@hidden d
address@hidden M-d, vi-like operation
address@hidden dir-node
+Select the directory node (i.e., the node @samp{(dir)}).
address@hidden table
+
+Here are some other commands which immediately result in the selection
+of a different node in the current window:
+
address@hidden @asis
address@hidden @key{<} (@code{first-node})
address@hidden @key{g}, vi-like operation
address@hidden <
address@hidden g, vi-like operation
address@hidden first-node
+Selects the first node which appears in this file. This node is most
+often @samp{Top}, but it does not have to be. With a numeric argument
address@hidden, select the @var{N}th node (the first node is node 1). An
+argument of zero is the same as the argument of 1.
+
address@hidden @key{>} (@code{last-node})
address@hidden @key{G}, vi-like operation
address@hidden >
address@hidden G, vi-like operation
address@hidden last-node
+Select the last node which appears in this file. With a numeric argument
address@hidden, select the @var{N}th node (the first node is node 1). An
+argument of zero is the same as no argument, i.e., it selects the last
+node.
+
address@hidden @key{]} (@code{global-next-node})
address@hidden ]
address@hidden global-next-node
+Move forward or down through node structure. If the node that you are
+currently viewing has a @samp{Next} pointer, that node is selected.
+Otherwise, if this node has a menu, the first menu item is selected. If
+there is no @samp{Next} and no menu, the same process is tried with the
address@hidden node of this node.
+
address@hidden @key{[} (@code{global-prev-node})
address@hidden [
address@hidden global-prev-node
+Move backward or up through node structure. If the node that you are
+currently viewing has a @samp{Prev} pointer, that node is selected.
+Otherwise, if the node has an @samp{Up} pointer, that node is selected,
+and if it has a menu, the last item in the menu is selected.
address@hidden table
+
+You can get the same behavior as @code{global-next-node} and
address@hidden while simply scrolling through the file with
address@hidden and @key{DEL}; @xref{Variables, @code{scroll-behavior}}, for
+more information.
+
address@hidden @asis
address@hidden
address@hidden @key{g} (@code{goto-node})
address@hidden @kbd{C-x @key{g}}, vi-like operation
address@hidden g
address@hidden C-x g, vi-like operation
address@hidden goto-node
+Read the name of a node and select it. While reading the node name,
+completion (@pxref{The Echo Area, completion}) is only done for the
+nodes which reside in one of the Info files that were loaded in the
+current Info session; if the desired node resides in some other file,
+you must type the node exactly as it appears in that Info file, and you
+must include the Info file of the other file. For example,
+
address@hidden
address@hidden(emacs)Buffers}
address@hidden example
+
+finds the node @samp{Buffers} in the Info file @file{emacs}.
+
address@hidden
address@hidden @key{O} (@code{goto-invocation}
address@hidden @key{I}
address@hidden O
address@hidden I
address@hidden goto-invocation
address@hidden finding the Invocation node
+Read the name of a program and look for a node in the current Info file
+which describes the invocation and the command-line options for that
+program. The default program name is derived from the name of the
+current Info file. This command does the same as the
address@hidden command-line option (@pxref{--show-options}), but
+it also allows to specify the program name; this is important for those
+manuals which describe several programs.
+
+If you need to find the Invocation node of a program that is documented
+in another Info file, you need to visit that file before invoking
address@hidden For example, if you are reading the Emacs manual and want to
+see the command-line options of the @code{makeinfo} program, type @kbd{g
+(texinfo) @key{RET}} and then @kbd{I makeinfo @key{RET}}. If you don't
+know what Info file documents the command, or if invoking @samp{I}
+doesn't display the right node, go to the @samp{(dir)} node (using the
address@hidden command) and invoke @samp{I} from there.
+
address@hidden @key{G} (@code{menu-sequence})
address@hidden G
address@hidden menu-sequence
address@hidden menu, following, from inside Info
+Read a sequence of menu entries and follow it. Info prompts for a
+sequence of menu items separated by commas. (Since commas are not
+allowed in a node name, they are a natural choice for a delimiter in a
+list of menu items.) Info then looks up the first item in the menu of
+the node @samp{(dir)} (if the @samp{(dir)} node cannot be found, Info
+uses @samp{Top}). If such an entry is found, Info goes to the node it
+points to and looks up the second item in the menu of that node, etc.
+In other words, you can specify a complete path which descends through
+the menu hierarchy of a particular Info file starting at the
address@hidden(dir)} node. This has the same effect as if you typed the menu
+item sequence on Info's command line, see @ref{command-line menu items,,
+Info command-line arguments processing}. For example,
+
address@hidden
+ @kbd{G Texinfo,Overview,Reporting Bugs @key{RET}}
address@hidden example
+
address@hidden
+displays the node @samp{Reporting Bugs} in the Texinfo manual. (You
+don't actually need to type the menu items in their full length, or in
+their exact letter-case. However, if you do type the menu items
+exactly, Info will find it faster.)
+
+If any of the menu items you type are not found, Info stops at the last
+entry it did find and reports an error.
+
address@hidden @kbd{C-x @key{k}} (@code{kill-node})
address@hidden C-x k
address@hidden kill-node
+Kill a node. The node name is prompted for in the echo area, with a
+default of the current node. @dfn{Killing} a node means that Info tries
+hard to forget about it, removing it from the list of history nodes kept
+for the window where that node is found. Another node is selected in
+the window which contained the killed node.
+
address@hidden @kbd{C-x C-f} (@code{view-file})
address@hidden C-x C-f
address@hidden view-file
+Read the name of a file and selects the entire file. The command
address@hidden
address@hidden C-f @var{filename}}
address@hidden example
+is equivalent to typing
address@hidden
address@hidden(@var{filename})*}
address@hidden example
+
address@hidden @kbd{C-x C-b} (@code{list-visited-nodes})
address@hidden C-x C-b
address@hidden list-visited-nodes
+Make a window containing a menu of all of the currently visited nodes.
+This window becomes the selected window, and you may use the standard
+Info commands within it.
+
address@hidden @kbd{C-x @key{b}} (@code{select-visited-node})
address@hidden C-x b
address@hidden select-visited-node
+Select a node which has been previously visited in a visible window.
+This is similar to @samp{C-x C-b} followed by @samp{m}, but no window is
+created.
address@hidden table
+
+
address@hidden Searching Commands
address@hidden Searching an Info File
address@hidden searching
+
+GNU Info allows you to search for a sequence of characters throughout an
+entire Info file, search through the indices of an Info file, or find
+areas within an Info file which discuss a particular topic.
+
address@hidden @asis
address@hidden @key{s} (@code{search})
address@hidden @key{/}
address@hidden s
address@hidden /
address@hidden search
+Read a string in the echo area and search for it. If the string
+includes upper-case characters, the Info file is searched
+case-sensitively; otherwise Info ignores the letter case. With a
+numeric argument of @var{N}, search for @var{N}th occurrence of the
+string. Negative arguments search backwards.
+
address@hidden @key{?} (@code{search-backward}, vi-like operation)
address@hidden ?, vi-like operation
address@hidden search-backward
+Read a string in the echo area and search backward through the Info file
+for that string. If the string includes upper-case characters, the Info
+file is searched case-sensitively; otherwise Info ignores the letter
+case. With a numeric argument of @var{N}, search for @var{N}th
+occurrence of the string. Negative arguments search forward.
+
address@hidden @key{S} (@code{search-case-sensitively}
address@hidden S
address@hidden search-case-sensitively
address@hidden search, case-sensitive
address@hidden case-sensitive search
+Read a string in the echo area and search for it case-sensitively, even
+if the string includes only lower-case letters. With a numeric argument
+of @var{N}, search for @var{N}th occurrence of the string. Negative
+arguments search backwards.
+
address@hidden @kbd{C-x @key{n}} (@code{search-next})
address@hidden @key{n}, vi-like operation
address@hidden C-x n
address@hidden n, vi-like operation
address@hidden search-next
address@hidden repeated search
+Search for the same string used in the last search command, in the same
+direction, and with the same case-sensitivity option. With a numeric
+argument of @var{N}, search for @var{N}th next occurrence.
+
address@hidden @kbd{C-x @key{N}} (@code{search-previous})
address@hidden @key{N}, vi-like operation
address@hidden C-x N
address@hidden n, vi-like operation
address@hidden search-previous
+Search for the same string used in the last search command, and with the
+same case-sensitivity option, but in the reverse direction. With a
+numeric argument of @var{N}, search for @var{N}th previous occurrence.
+
address@hidden @key{C-s} (@code{isearch-forward})
address@hidden C-s
address@hidden isearch-forward
address@hidden incremental search
+Interactively search forward through the Info file for a string as you
+type it. If the string includes upper-case characters, the search is
+case-sensitive; otherwise Info ignores the letter case.
+
address@hidden @key{C-r} (@code{isearch-backward})
address@hidden C-r
address@hidden isearch-backward
+Interactively search backward through the Info file for a string as
+you type it. If the string includes upper-case characters, the search
+is case-sensitive; otherwise Info ignores the letter case.
+
address@hidden @key{i} (@code{index-search})
address@hidden i
address@hidden index-search
address@hidden index, searching
address@hidden searching, in the indices
+Look up a string in the indices for this Info file, and select a node
+where the found index entry points to.
+
address@hidden @key{,} (@code{next-index-match})
address@hidden ,
address@hidden next-index-match
+Move to the node containing the next matching index item from the last
address@hidden command.
+
address@hidden @kbd{M-x index-apropos}
address@hidden index-apropos
+Grovel the indices of all the known Info files on your system for a
+string, and build a menu of the possible matches.
address@hidden table
+
+The most basic searching command is @samp{s} or @samp{/}
+(@code{search}). The @samp{s} command prompts you for a string in the
+echo area, and then searches the remainder of the Info file for an
+occurrence of that string. If the string is found, the node containing
+it is selected, and the cursor is left positioned at the start of the
+found string. Subsequent @samp{s} commands show you the default search
+string within @samp{[} and @samp{]}; pressing @key{RET} instead of
+typing a new string will use the default search string. Under
address@hidden (@pxref{--vi-keys}), using the @samp{n} or @samp{N}
+commands is a faster way of searching for the same string.
+
address@hidden searching} is similar to basic searching, but the
+string is looked up while you are typing it, instead of waiting until
+the entire search string has been specified.
+
address@hidden search, and case-sensitivity
address@hidden case-sensitivity, and search
+Both incremental and non-incremental search by default ignore the case
+of letters when comparing the Info file text with the search string.
+However, an uppercase letter in the search string makes the search
+case-sensitive. You can force a case-sensitive non-incremental search,
+even for a string that includes only lower-case letters, by using the
address@hidden command (@code{search-case-sensitively}). The @samp{n} and
address@hidden commands operate case-sensitively if the last search command
+was @samp{S}.
+
+The most efficient means of finding something quickly in a manual is
+the @samp{i} command (@code{index-search}). This command prompts for
+a string, and then looks for that string in all the indices of the
+current Info manual. If it finds a matching index entry, it displays
+the node to which that entry refers and prints the full text of the
+entry in the echo area. You can press @samp{,}
+(@code{next-index-match}) to find more matches. A good Info manual
+has all of its important concepts indexed, so the @samp{i} command
+lets you use a manual as a reference.
+
+If you don't know what manual documents something, try the @kbd{M-x
+index-apropos}. It prompts for a string and then looks up that string
+in all the indices of all the Info documents installed on your system.
+It can also be invoked from the command line; see @ref{--apropos}.
+
+
address@hidden Xref Commands
address@hidden Selecting Cross References
+
+We have already discussed the @samp{Next}, @samp{Prev}, and @samp{Up}
+pointers which appear at the top of a node. In addition to these
+pointers, a node may contain other pointers which refer you to a
+different node, perhaps in another Info file. Such pointers are called
address@hidden references}, or @dfn{xrefs} for short.
+
address@hidden
+* Parts of an Xref:: What a cross reference is made of.
+* Selecting Xrefs:: Commands for selecting menu or note items.
address@hidden menu
+
address@hidden Parts of an Xref, Selecting Xrefs, , Xref Commands
address@hidden Parts of an Xref
+
+Cross references have two major parts: the first part is called the
address@hidden; it is the name that you can use to refer to the cross
+reference, and the second is the @dfn{target}; it is the full name of
+the node that the cross reference points to.
+
+The target is separated from the label by a colon @samp{:}; first the
+label appears, and then the target. For example, in the sample menu
+cross reference below, the single colon separates the label from the
+target.
+
address@hidden
+* Foo Label: Foo Target. More information about Foo.
address@hidden example
+
+Note the @samp{.} which ends the name of the target. The @samp{.} is
+not part of the target; it serves only to let Info know where the target
+name ends.
+
+A shorthand way of specifying references allows two adjacent colons to
+stand for a target name which is the same as the label name:
+
address@hidden
+* Foo Commands:: Commands pertaining to Foo.
address@hidden example
+
+In the above example, the name of the target is the same as the name of
+the label, in this case @code{Foo Commands}.
+
+You will normally see two types of cross reference while viewing nodes:
address@hidden references, and @dfn{note} references. Menu references
+appear within a node's menu; they begin with a @samp{*} at the beginning
+of a line, and continue with a label, a target, and a comment which
+describes what the contents of the node pointed to contains.
+
+Note references appear within the body of the node text; they begin with
address@hidden, and continue with a label and a target.
+
+Like @samp{Next}, @samp{Prev}, and @samp{Up} pointers, cross references
+can point to any valid node. They are used to refer you to a place
+where more detailed information can be found on a particular subject.
+Here is a cross reference which points to a node within the Texinfo
+documentation: @xref{xref, , Writing an Xref, texinfo, the Texinfo
+Manual}, for more information on creating your own texinfo cross
+references.
+
address@hidden Selecting Xrefs, , Parts of an Xref, Xref Commands
address@hidden Selecting Xrefs
+
+The following table lists the Info commands which operate on menu items.
+
address@hidden @asis
address@hidden @key{1} (@code{menu-digit})
address@hidden @key{2} @dots{} @key{9}
address@hidden @key{M-1}, vi-like operation
address@hidden @key{M-2} @dots{} @key{M-9}, vi-like operation
address@hidden 1 @dots{} 9, in Info windows
address@hidden M-1 @dots{} M-9, vi-like operation
address@hidden 1 @dots{} 9, in Info windows
address@hidden M-1 @dots{} M-9, vi-like operation
address@hidden menu-digit
+Within an Info window, pressing a single digit, (such as @samp{1}),
+selects that menu item, and places its node in the current window.
+For convenience, there is one exception; pressing @samp{0} selects the
address@hidden item in the node's menu. When @samp{--vi-keys} is in
+effect, digits set the numeric argument, so these commands are remapped
+to their @samp{M-} varieties. For example, to select the last menu
+item, press @key{M-0}.
+
address@hidden @key{0} (@code{last-menu-item})
address@hidden @key{M-0}, vi-like operation
address@hidden 0, in Info windows
address@hidden M-0, vi-like operation
address@hidden last-menu-item
+Select the last item in the current node's menu.
+
address@hidden @key{m} (@code{menu-item})
address@hidden m
address@hidden menu-item
+Reads the name of a menu item in the echo area and selects its node.
+Completion is available while reading the menu label. @xref{The Echo
+Area, completion}.
+
address@hidden @kbd{M-x find-menu}
address@hidden find-menu
+Move the cursor to the start of this node's menu.
address@hidden table
+
+This table lists the Info commands which operate on cross references.
+
address@hidden @asis
address@hidden @key{f} (@code{xref-item})
address@hidden @key{r}
address@hidden @key{M-f}, vi-like operation
address@hidden @kbd{C-x @key{r}}, vi-like operation
address@hidden f
address@hidden r
address@hidden M-f, vi-like operation
address@hidden C-x r, vi-like operation
address@hidden xref-item
+Reads the name of a note cross reference in the echo area and selects
+its node. Completion is available while reading the cross reference
+label. @xref{The Echo Area, completion}.
address@hidden table
+
+Finally, the next few commands operate on menu or note references alike:
+
address@hidden @asis
address@hidden @key{TAB} (@code{move-to-next-xref})
address@hidden TAB, in Info windows
address@hidden move-to-next-xref
+Move the cursor to the start of the next nearest menu item or note
+reference in this node. You can then use @key{RET}
+(@code{select-reference-this-line}) to select the menu or note reference.
+
address@hidden @key{M-TAB} (@code{move-to-prev-xref})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden M-TAB, in Info windows
address@hidden move-to-prev-xref
+Move the cursor the start of the nearest previous menu item or note
+reference in this node.
+
address@hidden Shift-TAB, in Info windows
address@hidden BackTab, in Info windows
+On DOS/Windows only, the @address@hidden key is an alias for
address@hidden@key{TAB}}. This key is sometimes called @samp{BackTab}.
+
address@hidden @key{RET} (@code{select-reference-this-line})
address@hidden @key{M-g}, vi-like operation
address@hidden RET, in Info windows
address@hidden M-g, vi-like operation
address@hidden select-reference-this-line
+Select the menu item or note reference appearing on this line.
address@hidden table
+
+
address@hidden Window Commands
address@hidden Manipulating Multiple Windows
address@hidden windows, manipulating
+
+A @dfn{window} is a place to show the text of a node. Windows have a
+view area where the text of the node is displayed, and an associated
address@hidden line}, which briefly describes the node being viewed.
+
+GNU Info supports multiple windows appearing in a single screen; each
+window is separated from the next by its modeline. At any time, there
+is only one @dfn{active} window, that is, the window in which the cursor
+appears. There are commands available for creating windows, changing
+the size of windows, selecting which window is active, and for deleting
+windows.
+
address@hidden
+* The Mode Line:: What appears in the mode line?
+* Basic Windows:: Manipulating windows in Info.
+* The Echo Area:: Used for displaying errors and reading input.
address@hidden menu
+
address@hidden The Mode Line, Basic Windows, , Window Commands
address@hidden The Mode Line
+
+A @dfn{mode line} is a line of inverse video which appears at the bottom
+of an Info window. It describes the contents of the window just above
+it; this information includes the name of the file and node appearing in
+that window, the number of screen lines it takes to display the node,
+and the percentage of text that is above the top of the window. It can
+also tell you if the indirect tags table for this Info file needs to be
+updated, and whether or not the Info file was compressed when stored on
+disk.
+
+Here is a sample mode line for a window containing an uncompressed file
+named @file{dir}, showing the node @samp{Top}.
+
address@hidden
address@hidden
+-----Info: (dir)Top, 40 lines --Top-------------------------------------
+ ^^ ^ ^^^ ^^
+ (file)Node #lines where
address@hidden group
address@hidden example
+
+When a node comes from a file which is compressed on disk, this is
+indicated in the mode line with two small @samp{z}'s. In addition, if
+the Info file containing the node has been split into subfiles, the name
+of the subfile containing the node appears in the modeline as well:
+
address@hidden
+--zz-Info: (emacs)Top, 291 lines --Top-- Subfile: emacs-1.Z-------------
address@hidden example
+
+Truncation of long lines (as opposed to wrapping them to the next
+display line, @pxref{Scrolling Commands, toggle-wrap}) is indicated by a
address@hidden at the left edge of the mode line:
+
address@hidden
+--$--Info: (texinfo)Top, 480 lines --Top-- Subfile: texinfo-1-----------
address@hidden example
+
+When Info makes a node internally, such that there is no corresponding
+info file on disk, the name of the node is surrounded by asterisks
+(@samp{*}). The name itself tells you what the contents of the window
+are; the sample mode line below shows an internally constructed node
+showing possible completions:
+
address@hidden
+-----Info: *Completions*, 7 lines --All---------------------------------
address@hidden example
+
address@hidden Basic Windows, The Echo Area, The Mode Line, Window Commands
address@hidden Window Commands
+
+It can be convenient to view more than one node at a time. To allow
+this, Info can display more than one @dfn{window}. Each window has its
+own mode line (@pxref{The Mode Line}) and history of nodes viewed in that
+window (@pxref{Node Commands, , @code{history-node}}).
+
address@hidden @asis
address@hidden @kbd{C-x @key{o}} (@code{next-window})
address@hidden windows, selecting
address@hidden C-x o
address@hidden next-window
+Select the next window on the screen. Note that the echo area can only be
+selected if it is already in use, and you have left it temporarily.
+Normally, @samp{C-x o} simply moves the cursor into the next window on
+the screen, or if you are already within the last window, into the first
+window on the screen. Given a numeric argument, @samp{C-x o} moves over
+that many windows. A negative argument causes @samp{C-x o} to select
+the previous window on the screen.
+
address@hidden @kbd{M-x prev-window}
address@hidden prev-window
+Select the previous window on the screen. This is identical to
address@hidden o} with a negative argument.
+
address@hidden @kbd{C-x @key{2}} (@code{split-window})
address@hidden windows, creating
address@hidden C-x 2
address@hidden split-window
+Split the current window into two windows, both showing the same node.
+Each window is one half the size of the original window, and the cursor
+remains in the original window. The variable @code{automatic-tiling}
+can cause all of the windows on the screen to be resized for you
+automatically, please @pxref{Variables, , automatic-tiling} for more
+information.
+
address@hidden @kbd{C-x @key{0}} (@code{delete-window})
address@hidden windows, deleting
address@hidden C-x 0
address@hidden delete-window
+Delete the current window from the screen. If you have made too many
+windows and your screen appears cluttered, this is the way to get rid of
+some of them.
+
address@hidden @kbd{C-x @key{1}} (@code{keep-one-window})
address@hidden C-x 1
address@hidden keep-one-window
+Delete all of the windows excepting the current one.
+
address@hidden @kbd{ESC @key{C-v}} (@code{scroll-other-window})
address@hidden ESC C-v, in Info windows
address@hidden scroll-other-window
+Scroll the other window, in the same fashion that @samp{C-v} might
+scroll the current window. Given a negative argument, scroll the
+"other" window backward.
+
address@hidden @kbd{C-x @key{^}} (@code{grow-window})
address@hidden C-x ^
address@hidden grow-window
+Grow (or shrink) the current window. Given a numeric argument, grow
+the current window that many lines; with a negative numeric argument,
+shrink the window instead.
+
address@hidden @kbd{C-x @key{t}} (@code{tile-windows})
address@hidden tiling
address@hidden C-x t
address@hidden tile-windows
+Divide the available screen space among all of the visible windows.
+Each window is given an equal portion of the screen in which to display
+its contents. The variable @code{automatic-tiling} can cause
address@hidden to be called when a window is created or deleted.
address@hidden, , @code{automatic-tiling}}.
address@hidden table
+
address@hidden The Echo Area, , Basic Windows, Window Commands
address@hidden The Echo Area
address@hidden echo area
+
+The @dfn{echo area} is a one line window which appears at the bottom of
+the screen. It is used to display informative or error messages, and to
+read lines of input from you when that is necessary. Almost all of the
+commands available in the echo area are identical to their Emacs
+counterparts, so please refer to that documentation for greater depth of
+discussion on the concepts of editing a line of text. The following
+table briefly lists the commands that are available while input is being
+read in the echo area:
+
address@hidden @asis
address@hidden @key{C-f} (@code{echo-area-forward})
address@hidden @key{RIGHT} (an arrow key)
address@hidden @key{M-h}, vi-like operation
address@hidden C-f, in the echo area
address@hidden RIGHT, in the echo area
address@hidden M-h, in the echo area, vi-like operation
address@hidden echo-area-forward
+Move forward a character.
+
address@hidden @key{C-b} (@code{echo-area-backward})
address@hidden @key{LEFT} (an arrow key)
address@hidden @key{M-l}, vi-like operation
address@hidden LEFT, in the echo area
address@hidden C-b, in the echo area
address@hidden M-l, in the echo area, vi-like operation
address@hidden echo-area-backward
+Move backward a character.
+
address@hidden @key{C-a} (@code{echo-area-beg-of-line})
address@hidden @key{M-0}, vi-like operation
address@hidden C-a, in the echo area
address@hidden M-0, in the echo area, vi-like operation
address@hidden echo-area-beg-of-line
+Move to the start of the input line.
+
address@hidden @key{C-e} (@code{echo-area-end-of-line})
address@hidden @key{M-$}, vi-like operation
address@hidden C-e, in the echo area
address@hidden M-$, vi-like operation
address@hidden echo-area-end-of-line
+Move to the end of the input line.
+
address@hidden @key{M-f} (@code{echo-area-forward-word})
address@hidden @address@hidden (DOS/Windows only)
address@hidden @key{M-w}, vi-like operation
address@hidden M-f, in the echo area
address@hidden M-w, in the echo area, vi-like operation
address@hidden echo-area-forward-word
+Move forward a word.
+
address@hidden C-RIGHT, in the echo area
+On DOS/Windows, @address@hidden moves forward by words.
+
address@hidden @key{M-b} (@code{echo-area-backward-word})
address@hidden @address@hidden (DOS/Windows only)
address@hidden M-b, in the echo area
address@hidden echo-area-backward-word
+Move backward a word.
+
address@hidden C-LEFT, in the echo area
+On DOS/Windows, @address@hidden moves backward by words.
+
address@hidden @key{C-d} (@code{echo-area-delete})
address@hidden @key{M-x}, vi-like operation
address@hidden C-d, in the echo area
address@hidden M-x, in the echo area, vi-like operation
address@hidden echo-area-delete
+Delete the character under the cursor.
+
address@hidden @key{DEL} (@code{echo-area-rubout})
address@hidden DEL, in the echo area
address@hidden echo-area-rubout
+Delete the character behind the cursor.
+
+On some keyboards, this key is designated @key{BS}, for
address@hidden Those keyboards will usually bind @key{DEL} in the
+echo area to @code{echo-area-delete}.
+
address@hidden @key{C-g} (@code{echo-area-abort})
address@hidden @key{C-u}, vi-like operation
address@hidden C-g, in the echo area
address@hidden C-u, in the echo area, vi-like operation
address@hidden echo-area-abort
+Cancel or quit the current operation. If completion is being read, this
+command discards the text of the input line which does not match any
+completion. If the input line is empty, it aborts the calling function.
+
address@hidden @key{RET} (@code{echo-area-newline})
address@hidden RET, in the echo area
address@hidden echo-area-newline
+Accept (or forces completion of) the current input line.
+
address@hidden @key{C-q} (@code{echo-area-quoted-insert})
address@hidden @key{C-v}, vi-like operation
address@hidden C-q, in the echo area
address@hidden C-v, in the echo area, vi-like operation
address@hidden echo-area-quoted-insert
+Insert the next character verbatim. This is how you can insert control
+characters into a search string, for example, or the @samp{?} character
+when Info prompts with completion.
+
address@hidden @var{printing character} (@code{echo-area-insert})
address@hidden printing characters, in the echo area
address@hidden echo-area-insert
+Insert the character. Characters that have their 8th bit set, and not
+bound to @samp{M-} commands, are also inserted verbatim; this is useful
+for terminals which support Latin scripts.
+
address@hidden @key{M-TAB} (@code{echo-area-tab-insert})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden M-TAB, in the echo area
address@hidden Shift-TAB, in the echo area
address@hidden echo-area-tab-insert
+Insert a TAB character.
+
address@hidden Shift-TAB, in the echo area
address@hidden BackTab, in the echo area
+On DOS/Windows only, the @address@hidden key is an alias for
address@hidden@key{TAB}}. This key is sometimes called @samp{BackTab}.
+
address@hidden @key{C-t} (@code{echo-area-transpose-chars})
address@hidden C-t, in the echo area
address@hidden echo-area-transpose-chars
+Transpose the characters at the cursor.
address@hidden table
+
+The next group of commands deal with @dfn{killing}, and @dfn{yanking}
address@hidden
+Some people are used to calling these operations @dfn{cut} and
address@hidden, respectively.}. For an in depth discussion of killing and
+yanking, @pxref{Killing, , Killing and Deleting, emacs, the GNU Emacs
+Manual}
+
address@hidden @asis
address@hidden @key{M-d} (@code{echo-area-kill-word})
address@hidden @key{M-X}, vi-like operation
address@hidden M-d, in the echo area
address@hidden M-X, in the echo area, vi-like operation
address@hidden echo-area-kill-word
+Kill the word following the cursor.
+
address@hidden @key{M-DEL} (@code{echo-area-backward-kill-word})
address@hidden @address@hidden
address@hidden M-DEL, in the echo area
address@hidden echo-area-backward-kill-word
+Kill the word preceding the cursor.
+
address@hidden M-BS, in the echo area
+On some keyboards, the @code{Backspace} key is used instead of
address@hidden, so @address@hidden has the same effect as
address@hidden@key{DEL}}.
+
address@hidden @key{C-k} (@code{echo-area-kill-line})
address@hidden C-k, in the echo area
address@hidden echo-area-kill-line
+Kill the text from the cursor to the end of the line.
+
address@hidden @kbd{C-x @key{DEL}} (@code{echo-area-backward-kill-line})
address@hidden C-x DEL, in the echo area
address@hidden echo-area-backward-kill-line
+Kill the text from the cursor to the beginning of the line.
+
address@hidden @key{C-y} (@code{echo-area-yank})
address@hidden C-y, in the echo area
address@hidden echo-area-yank
+Yank back the contents of the last kill.
+
address@hidden @key{M-y} (@code{echo-area-yank-pop})
address@hidden M-y, in the echo area
address@hidden echo-area-yank-pop
+Yank back a previous kill, removing the last yanked text first.
address@hidden table
+
address@hidden completion
+Sometimes when reading input in the echo area, the command that needed
+input will only accept one of a list of several choices. The choices
+represent the @dfn{possible completions}, and you must respond with one
+of them. Since there are a limited number of responses you can make,
+Info allows you to abbreviate what you type, only typing as much of the
+response as is necessary to uniquely identify it. In addition, you can
+request Info to fill in as much of the response as is possible; this
+is called @dfn{completion}.
+
+The following commands are available when completing in the echo area:
+
address@hidden @asis
address@hidden @key{TAB} (@code{echo-area-complete})
address@hidden @key{SPC}
address@hidden TAB, in the echo area
address@hidden SPC, in the echo area
address@hidden echo-area-complete
+Insert as much of a completion as is possible.
+
address@hidden @key{?} (@code{echo-area-possible-completions})
address@hidden ?, in the echo area
address@hidden echo-area-possible-completions
+Display a window containing a list of the possible completions of what
+you have typed so far. For example, if the available choices are:
+
address@hidden
address@hidden
+bar
+foliate
+food
+forget
address@hidden group
address@hidden example
+
address@hidden
+and you have typed an @samp{f}, followed by @samp{?}, Info will pop up a
+window showing a node called @samp{*Completions*} which lists the
+possible completions like this:
+
address@hidden
address@hidden
+3 completions:
+foliate food
+forget
address@hidden group
address@hidden example
+
address@hidden
+i.e., all of the choices which begin with @samp{f}. Pressing @key{SPC}
+or @key{TAB} would result in @samp{fo} appearing in the echo area, since
+all of the choices which begin with @samp{f} continue with @samp{o}.
+Now, typing @samp{l} followed by @samp{TAB} results in @samp{foliate}
+appearing in the echo area, since that is the only choice which begins
+with @samp{fol}.
+
address@hidden @key{ESC C-v} (@code{echo-area-scroll-completions-window})
address@hidden ESC C-v, in the echo area
address@hidden echo-area-scroll-completions-window
+Scroll the completions window, if that is visible, or the "other"
+window if not.
address@hidden table
+
+
address@hidden Printing Nodes
address@hidden Printing Nodes
address@hidden printing
+
+In general, we recommend that you use @TeX{} to format the document and
+print sections of it, by running @code{tex} on the Texinfo source file.
+However, you may wish to print out the contents of a node as a quick
+reference document for later use, or if you don't have @TeX{} installed.
+Info provides you with a command for doing this.
+
address@hidden @asis
address@hidden @kbd{M-x print-node}
address@hidden print-node
address@hidden INFO_PRINT_COMMAND, environment variable
+Pipe the contents of the current node through the command in the
+environment variable @code{INFO_PRINT_COMMAND}. If the variable does not
+exist, the node is simply piped to @code{lpr} (on DOS/Windows, the
+default is to print the node to the local printer device, @file{PRN}).
+
address@hidden printing nodes to the local printer
address@hidden local printer device
+The value of @code{INFO_PRINT_COMMAND} may begin with the @samp{>}
+character, as in @samp{>/dev/printer}, in which case Info treats the
+rest as the name of a file or a device. Instead of piping to a command,
+Info opens the file, writes the node contents, and closes the file,
+under the assumption that text written to that file will be printed by
+the underlying OS.
address@hidden table
+
+
address@hidden Miscellaneous Commands
address@hidden Miscellaneous Commands
+
+GNU Info contains several commands which self-document GNU Info:
+
address@hidden @asis
address@hidden @kbd{M-x describe-command}
address@hidden functions, describing
address@hidden commands, describing
address@hidden describe-command
+Read the name of an Info command in the echo area and then display a
+brief description of what that command does.
+
address@hidden @kbd{M-x describe-key}
address@hidden keys, describing
address@hidden describe-key
+Read a key sequence in the echo area, and then display the name and
+documentation of the Info command that the key sequence invokes.
+
address@hidden @kbd{M-x describe-variable}
+Read the name of a variable in the echo area and then display a brief
+description of what the variable affects.
+
address@hidden @kbd{M-x where-is}
address@hidden where-is
+Read the name of an Info command in the echo area, and then display
+a key sequence which can be typed in order to invoke that command.
+
address@hidden @key{C-h} (@code{get-help-window})
address@hidden @key{?}
address@hidden @key{F1} (on DOS/Windows only)
address@hidden h, vi-like operation
address@hidden C-h
address@hidden ?, in Info windows
address@hidden F1
address@hidden h, vi-like operation
address@hidden get-help-window
+Create (or Move into) the window displaying @code{*Help*}, and place
+a node containing a quick reference card into it. This window displays
+the most concise information about GNU Info available.
+
address@hidden @key{h} (@code{get-info-help-node})
address@hidden @key{M-h}, vi-like operation
address@hidden h
address@hidden M-h, vi-like operation
address@hidden get-info-help-node
+Try hard to visit the node @code{(info)Help}. The Info file
address@hidden distributed with GNU Info contains this node. Of
+course, the file must first be processed with @code{makeinfo}, and then
+placed into the location of your Info directory.
address@hidden table
+
+Here are the commands for creating a numeric argument:
+
address@hidden @asis
address@hidden @key{C-u} (@code{universal-argument})
address@hidden numeric arguments
address@hidden C-u
address@hidden universal-argument
+Start (or multiply by 4) the current numeric argument. @samp{C-u} is
+a good way to give a small numeric argument to cursor movement or
+scrolling commands; @samp{C-u C-v} scrolls the screen 4 lines, while
address@hidden C-u C-n} moves the cursor down 16 lines. @samp{C-u} followed
+by digit keys sets the numeric argument to the number thus typed:
address@hidden 1 2 0} sets the argument to 120.
+
address@hidden @key{M-1} (@code{add-digit-to-numeric-arg})
address@hidden @key{1}, vi-like operation
address@hidden @key{M-2} @dots{} @key{M-9}
address@hidden @key{2} @dots{} @key{9}, vi-like operation
address@hidden @key{M-0}
address@hidden @key{0}, vi-like operation
address@hidden M-0 @dots{} M-9
address@hidden 0 @dots{} 9, vi-like operation
address@hidden add-digit-to-numeric-arg
+Add the digit value of the invoking key to the current numeric
+argument. Once Info is reading a numeric argument, you may just type
+the digits of the argument, without the Meta prefix. For example, you
+might give @samp{C-l} a numeric argument of 32 by typing:
+
address@hidden
address@hidden 3 2 C-l}
address@hidden example
+
address@hidden
+or
+
address@hidden
address@hidden 2 C-l}
address@hidden example
+
address@hidden @key{M--} (@code{add-digit-to-numeric-arg}
address@hidden @key{-}
address@hidden M--
address@hidden -
address@hidden negative arguments
address@hidden arguments, negative
address@hidden numeric arguments, negative
+To make a negative argument, type @kbd{-}. Typing @kbd{-} alone makes a
+negative argument with a value of -1. If you continue to type digit or
+Meta-digit keys after @kbd{-}, the result is a negative number produced
+by those digits.
+
address@hidden doesn't work when you type in the echo area, because you need to
+be able to insert the @samp{-} character itself; use @kbd{M--} instead,
+if you need to specify negative arguments in the echo area.
address@hidden table
+
address@hidden is used to abort the reading of a multi-character key
+sequence, to cancel lengthy operations (such as multi-file searches) and
+to cancel reading input in the echo area.
+
address@hidden @asis
address@hidden @key{C-g} (@code{abort-key})
address@hidden @key{C-u}, vi-like operation
address@hidden cancelling typeahead
address@hidden cancelling the current operation
address@hidden C-g, in Info windows
address@hidden C-u cancels typeahead, vi-like operation
address@hidden abort-key
+Cancel current operation.
address@hidden table
+
+The @samp{q} command of Info simply quits running Info. Under
address@hidden (@pxref{--vi-keys}), you can also exit with @samp{:q}
+or @samp{ZZ}.
+
address@hidden @asis
address@hidden @key{q} (@code{quit})
address@hidden @kbd{C-x C-c}
address@hidden @kbd{:q}, vi-like operation
address@hidden @kbd{ZZ}, vi-like operation
address@hidden quitting
address@hidden q
address@hidden C-x C-c
address@hidden ZZ, vi-like operation
address@hidden quit
+Exit GNU Info.
address@hidden table
+
+If the operating system tells GNU Info that the screen is 60 lines tall,
+and it is actually only 40 lines tall, here is a way to tell Info that
+the operating system is correct.
+
address@hidden @asis
address@hidden @kbd{M-x set-screen-height}
address@hidden set-screen-height
address@hidden screen, changing the height of
+Read a height value in the echo area and set the height of the
+displayed screen to that value.
address@hidden table
+
+On MS-DOS/MS-Windows, this command actually tries to change the
+dimensions of the visible screen to the value you type in the echo
+area.
+
+Finally, Info provides a convenient way to display footnotes which might
+be associated with the current node that you are viewing:
+
address@hidden @asis
address@hidden @key{ESC C-f} (@code{show-footnotes})
address@hidden ESC C-f
address@hidden show-footnotes
address@hidden footnotes, displaying
+Show the footnotes (if any) associated with the current node in another
+window. You can have Info automatically display the footnotes
+associated with a node when the node is selected by setting the variable
address@hidden @xref{Variables, , @code{automatic-footnotes}}.
address@hidden table
+
+
address@hidden Variables
address@hidden Manipulating Variables
+
+GNU Info contains several @dfn{variables} whose values are looked at by
+various Info commands. You can change the values of these variables,
+and thus change the behavior of Info to more closely match your
+environment and Info file reading manner.
+
+There are two ways to set the value of a variable: interactively, using
+the @code{set-variable} command described below, or in the @code{#var}
+section of the @code{.infokey} file. @xref{Custom Key Bindings}.
+
address@hidden @asis
address@hidden @kbd{M-x set-variable}
address@hidden variables, setting
address@hidden set-variable
+Read the name of a variable, and the value for it, in the echo area and
+then set the variable to that value. Completion is available when
+reading the variable name (@pxref{The Echo Area, completion}); often,
+completion is available when reading the value to give to the variable,
+but that depends on the variable itself. If a variable does @emph{not}
+supply multiple choices to complete over, it expects a numeric value.
+
address@hidden @kbd{M-x describe-variable}
address@hidden variables, describing
address@hidden describe-variable
+Read the name of a variable in the echo area and then display a brief
+description of what the variable affects.
address@hidden table
+
+Here is a list of the variables that you can set in Info.
+
address@hidden @code
address@hidden automatic-footnotes
address@hidden automatic-footnotes
+When set to @code{On}, footnotes appear and disappear automatically.
+This variable is @code{On} by default. When a node is selected, a
+window containing the footnotes which appear in that node is created,
+and the footnotes are displayed within the new window. The window that
+Info creates to contain the footnotes is called @samp{*Footnotes*}. If
+a node is selected which contains no footnotes, and a @samp{*Footnotes*}
+window is on the screen, the @samp{*Footnotes*} window is deleted.
+Footnote windows created in this fashion are not automatically tiled so
+that they can use as little of the display as is possible.
+
address@hidden automatic-tiling
address@hidden automatic-tiling
+When set to @code{On}, creating or deleting a window resizes other
+windows. This variable is @code{Off} by default. Normally, typing
address@hidden 2} divides the current window into two equal parts. When
address@hidden is set to @code{On}, all of the windows are
+resized automatically, keeping an equal number of lines visible in each
+window. There are exceptions to the automatic tiling; specifically, the
+windows @samp{*Completions*} and @samp{*Footnotes*} are @emph{not}
+resized through automatic tiling; they remain their original size.
+
address@hidden errors-ring-bell
address@hidden errors-ring-bell
+When set to @code{On}, errors cause the bell to ring. The default
+setting of this variable is @code{On}.
+
address@hidden gc-compressed-files
address@hidden gc-compressed-files
+When set to @code{On}, Info garbage collects files which had to be
+uncompressed. The default value of this variable is @code{Off}.
+Whenever a node is visited in Info, the Info file containing that node
+is read into core, and Info reads information about the tags and nodes
+contained in that file. Once the tags information is read by Info, it
+is never forgotten. However, the actual text of the nodes does not need
+to remain in core unless a particular Info window needs it. For
+non-compressed files, the text of the nodes does not remain in core when
+it is no longer in use. But de-compressing a file can be a time
+consuming operation, and so Info tries hard not to do it twice.
address@hidden tells Info it is okay to garbage collect the
+text of the nodes of a file which was compressed on disk.
+
address@hidden ISO-Latin
address@hidden ISO Latin characters
address@hidden ISO-Latin
+When set to @code{On}, Info accepts and displays ISO Latin characters.
+By default, Info assumes an ASCII character set. @code{ISO-Latin} tells
+Info that it is running in an environment where the European standard
+character set is in use, and allows you to input such characters to
+Info, as well as display them.
+
address@hidden scroll-behavior
address@hidden scroll-behavior
+Control what happens when forward scrolling is requested at the end of
+a node, or when backward scrolling is requested at the beginning of a
+node. The default value for this variable is @code{Continuous}. There
+are three possible values for this variable:
+
address@hidden @code
address@hidden Continuous
+Try to get the first item in this node's menu, or failing that, the
address@hidden node, or failing that, the @samp{Next} of the @samp{Up}.
+This behavior is identical to using the @samp{]}
+(@code{global-next-node}) and @samp{[} (@code{global-prev-node})
+commands.
+
address@hidden Next Only
+Only try to get the @samp{Next} node.
+
address@hidden Page Only
+Simply give up, changing nothing. If @code{scroll-behavior} is
address@hidden Only}, no scrolling command can change the node that is being
+viewed.
address@hidden table
+
address@hidden scroll-step
address@hidden scroll-step
+The number of lines to scroll when the cursor moves out of the window.
+Scrolling happens automatically if the cursor has moved out of the
+visible portion of the node text when it is time to display. Usually
+the scrolling is done so as to put the cursor on the center line of the
+current window. However, if the variable @code{scroll-step} has a
+nonzero value, Info attempts to scroll the node text by that many lines;
+if that is enough to bring the cursor back into the window, that is what
+is done. The default value of this variable is 0, thus placing the
+cursor (and the text it is attached to) in the center of the window.
+Setting this variable to 1 causes a kind of "smooth scrolling" which
+some people prefer.
+
address@hidden show-index-match
address@hidden show-index-match
+When set to @code{On}, the portion of the matched search string is
+highlighted in the message which explains where the matched search
+string was found. The default value of this variable is @code{On}.
+When Info displays the location where an index match was found,
+(@pxref{Searching Commands, , @code{next-index-match}}), the portion of the
+string that you had typed is highlighted by displaying it in the inverse
+case from its surrounding characters.
+
address@hidden visible-bell
address@hidden visible-bell
+When set to @code{On}, GNU Info attempts to flash the screen instead of
+ringing the bell. This variable is @code{Off} by default. Of course,
+Info can only flash the screen if the terminal allows it; in the case
+that the terminal does not allow it, the setting of this variable has no
+effect. However, you can make Info perform quietly by setting the
address@hidden variable to @code{Off}.
+
address@hidden table
+
+
address@hidden Custom Key Bindings
address@hidden Customizing Key Bindings and Variables
+
address@hidden default key bindings, overriding
address@hidden overriding default key bindings
address@hidden customizing key bindings
address@hidden key bindings, customizing
address@hidden infokey
address@hidden .info
address@hidden .infokey
address@hidden _info file (MS-DOS)
+
+For those whose editor/pager of choice is not Emacs and who are not
+entirely satisfied with the --vi-keys option (@pxref{--vi-keys}), GNU
+Info provides a way to define different key-to-command bindings and
+variable settings from the defaults described in this document.
+
+On startup, GNU Info looks for a configuration file in the invoker's
+HOME directory called @address@hidden to the limitations of
+DOS filesystems, the MS-DOS version of Info looks for a file
address@hidden instead. If the @env{HOME} variable is not defined, Info
+additionally looks in the current directory.}. If it is present, and
+appears to contain Info configuration data, and was created with the
+current version of the @code{infokey} command, then Info adopts the
+key bindings and variable settings contained therein.
+
+The @file{.info} file contains compact, non-textual data for reasons of
+efficiency and because its design was lifted wholesale from the GNU Less
+program, which also does it that way. It must be created by compiling a
+textual source file using the @code{infokey} command.
+
address@hidden
+* Invoking infokey::
+* infokey source format::
address@hidden menu
+
+
address@hidden Invoking infokey
address@hidden Invoking @command{infokey}
+
address@hidden invoking infokey
address@hidden infokey, invoking
address@hidden _infokey file (MS-DOS)
+
address@hidden compiles a source file
+(@file{$HOME/address@hidden file is named @file{_infokey} in
+the MS-DOS version, and is looked for in the current directory if
address@hidden is undefined.} by default) containing Info customizations
+into a binary format (@file{$HOME/.info} by default). GNU Info reads
+the binary file at startup to override the default key bindings and
+variable definitions. Synopsis:
+
address@hidden
+infokey address@hidden@dots{}] address@hidden
address@hidden example
+
+Besides the standard @option{--help} and @option{--version}, the only
+option is @option{--output @var{file}}. This tells @command{infokey} to
+write the binary data to @var{file} instead of @file{$HOME/.info}.
+
+
address@hidden infokey source format
address@hidden @command{infokey} source format
+
address@hidden infokey source format
address@hidden .infokey source format
address@hidden format of .infokey source
+
+The format of the source file read by @command{infokey} is most easily
+illustrated by example. For instance, here is a sample @file{.infokey}
+source file suitable for aficionados of @command{vi} or @command{less}:
+
address@hidden
+#info
+j next-line
+k prev-line
+l forward-char
+h backward-char
+\kd next-line
+\ku prev-line
+\kr forward-char
+\kl backward-char
+\ scroll-forward
+\kD scroll-forward-page-only
+b scroll-backward
+\kU scroll-backward-page-only
+g beginning-of-node
+\kh beginning-of-node
+G end-of-node
+\ke end-of-node
+\t select-reference-this-line
+- history-node
+n next-node
+p prev-node
+u up-node
+t top-node
+d dir-node
+#var
+scroll-step=1
address@hidden example
+
+The source file consists of one or more @dfn{sections}.
+Each section starts with a line that identifies the type of section.
+Possible sections are:
+
address@hidden @code
address@hidden #info
+Key bindings for Info windows.
+The start of this section is indicated by a line containing just
address@hidden by itself. If this is the first section in the source
+file, the @code{#info} line can be omitted. The rest of this section
+consists of lines of the form:
+
address@hidden
address@hidden whitespace @var{action} [ whitespace [ # comment ] ] newline
address@hidden example
+
+Whitespace is any sequence of one or more spaces and/or tabs. Comment
+is any sequence of any characters, excluding newline. @var{string} is
+the key sequence which invokes the action. @var{action} is the name of
+an Info command. The characters in @var{string} are interpreted
+literally or prefixed by a caret (@code{^}) to indicate a control
+character. A backslash followed by certain characters specifies input
+keystrokes as follows:
+
address@hidden @code
address@hidden \b
+Backspace
address@hidden \e
+Escape (ESC)
address@hidden \n
+Newline
address@hidden \r
+Return
address@hidden \t
+Tab
address@hidden \ku
+Up arrow
address@hidden \kd
+Down arrow
address@hidden \kl
+Left arrow
address@hidden \kr
+Right arrow
address@hidden \kU
+Page Up
address@hidden \kD
+Page Down
address@hidden \kh
+HOME
address@hidden \ke
+END
address@hidden \kx
+Delete (DEL)
address@hidden address@hidden
address@hidden where @var{x} is any character as described above.
address@hidden table
+
+Backslash followed by any other character indicates that character is to
+be taken literally. Characters which must be preceded by a backslash
+include caret, space, tab, and backslash itself.
+
address@hidden #echo-area
+Key bindings for the echo area.
+The start of this section is indicated by a line containing just
address@hidden by itself. The rest of this section has a syntax
+identical to that for the key definitions for the Info area, described
+above.
+
address@hidden #var
+Variable initializations.
+The start of this section is indicated by a line containing just
address@hidden by itself. Following this line is a list of variable
+assignments, one per line. Each line consists of a variable name
+(@xref{Variables},) followed by @code{=} followed by a value.
+There may be no white space between the variable name and the @code{=},
+and all characters following the @code{=}, including white space,
+are included in the value.
address@hidden table
+
+Blank lines and lines starting with @code{#} are ignored, except for
+the special section header lines.
+
+Key bindings defined in the @file{.info} file take precedence over GNU
+Info's default key bindings, whether or not @samp{--vi-keys} is used. A
+default key binding may be disabled by overriding it in the @file{.info}
+file with the action @code{invalid}. In addition, @emph{all} default
+key bindings can be disabled by adding this line @emph{anywhere} in the
+relevant section:
+
address@hidden
+#stop
address@hidden example
+
+This will cause GNU Info to ignore all the default key commands for that
+section.
+
+Beware: @code{#stop} can be dangerous. Since it disables all default
+key bindings, you must supply enough new key bindings to enable all
+necessary actions. Failure to bind any key to the @code{quit} command,
+for example, can lead to frustration.
+
+The order in which key bindings are defined in the @file{.info} file is
+not important, except that the command summary produced by the
address@hidden command only displays the @emph{first} key that
+is bound to each command.
+
+
address@hidden the following is incomplete
+
+
address@hidden Copying This Manual
address@hidden Copying This Manual
+
address@hidden
+* GNU Free Documentation License:: License for copying this manual.
address@hidden menu
+
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
+
address@hidden FDL, GNU Free Documentation License
address@hidden Version 1.1, March 2000
+
address@hidden
+Copyright @copyright{} 2000 Free Software Foundation, Inc.
+59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
address@hidden display
+
address@hidden 0
address@hidden
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+written document @dfn{free} in the sense of freedom: to assure everyone
+the effective freedom to copy and redistribute it, with or without
+modifying it, either commercially or noncommercially. Secondarily,
+this License preserves for the author and publisher a way to get
+credit for their work, while not being considered responsible for
+modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
address@hidden
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work that contains a
+notice placed by the copyright holder saying it can be distributed
+under the terms of this License. The ``Document'', below, refers to any
+such manual or work. Any member of the public is a licensee, and is
+addressed as ``you''.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (For example, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, whose contents can be viewed and edited directly and
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is
+not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
address@hidden without markup, Texinfo input format, address@hidden input
format,
address@hidden or @acronym{XML} using a publicly available
address@hidden, and standard-conforming simple @acronym{HTML} designed
+for human modification. Opaque formats include PostScript,
address@hidden, proprietary formats that can be read and edited only by
+proprietary word processors, @acronym{SGML} or @acronym{XML} for which
+the @acronym{DTD} and/or processing tools are not generally available,
+and the machine-generated @acronym{HTML} produced by some word
+processors for output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
address@hidden
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
address@hidden
+COPYING IN QUANTITY
+
+If you publish printed copies of the Document numbering more than 100,
+and the Document's license notice requires Cover Texts, you must enclose
+the copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols. If you use the latter
+option, you must take reasonably prudent steps, when you begin
+distribution of Opaque copies in quantity, to ensure that this
+Transparent copy will remain thus accessible at the stated location
+until at least one year after the last time you distribute an Opaque
+copy (directly or through your agents or retailers) of that edition to
+the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
address@hidden
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
address@hidden A
address@hidden
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
address@hidden
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has less than five).
+
address@hidden
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
address@hidden
+Preserve all the copyright notices of the Document.
+
address@hidden
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
address@hidden
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
address@hidden
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
address@hidden
+Include an unaltered copy of this License.
+
address@hidden
+Preserve the section entitled ``History'', and its title, and add to
+it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
address@hidden
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
address@hidden
+In any section entitled ``Acknowledgments'' or ``Dedications'',
+preserve the section's title, and preserve in the section all the
+substance and tone of each of the contributor acknowledgments
+and/or dedications given therein.
+
address@hidden
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
address@hidden
+Delete any section entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
address@hidden
+Do not retitle any existing section as ``Endorsements''
+or to conflict in title with any Invariant Section.
address@hidden enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
address@hidden
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections entitled ``History''
+in the various original documents, forming one section entitled
+``History''; likewise combine any sections entitled ``Acknowledgments'',
+and any sections entitled ``Dedications''. You must delete all sections
+entitled ``Endorsements.''
+
address@hidden
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
address@hidden
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, does not as a whole count as a Modified Version
+of the Document, provided no compilation copyright is claimed for the
+compilation. Such a compilation is called an ``aggregate'', and this
+License does not apply to the other self-contained works thus compiled
+with the Document, on account of their being thus compiled, if they
+are not themselves derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one quarter
+of the entire aggregate, the Document's Cover Texts may be placed on
+covers that surround only the Document within the aggregate.
+Otherwise they must appear on covers around the whole aggregate.
+
address@hidden
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License provided that you also include the
+original English version of this License. In case of a disagreement
+between the translation and the original English version of this
+License, the original English version will prevail.
+
address@hidden
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
address@hidden
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
address@hidden://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
address@hidden enumerate
+
address@hidden
address@hidden ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
address@hidden
address@hidden
+ Copyright (C) @var{year} @var{your name}.
+ 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 the Invariant Sections being @var{list their titles}, with the
+ Front-Cover Texts being @var{list}, and with the Back-Cover Texts being
@var{list}.
+ A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
address@hidden group
address@hidden smallexample
+
+If you have no Invariant Sections, write ``with no Invariant Sections''
+instead of saying which ones are invariant. If you have no
+Front-Cover Texts, write ``no Front-Cover Texts'' instead of
+``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
address@hidden Local Variables:
address@hidden ispell-local-pdict: "ispell-dict"
address@hidden End:
+
+
+
address@hidden Index
address@hidden Index
+
address@hidden cp
+
address@hidden
Index: res/texi_mini_ker/mini_ker.texi.first
===================================================================
RCS file: res/texi_mini_ker/mini_ker.texi.first
diff -N res/texi_mini_ker/mini_ker.texi.first
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ res/texi_mini_ker/mini_ker.texi.first 2 Aug 2009 13:11:00 -0000
1.1
@@ -0,0 +1,4300 @@
+\input texinfo @c -*-texinfo-*-
address@hidden mini_ker.info
address@hidden UPDATED 28 March 2002
address@hidden UPDATED-MONTH March 2002
address@hidden EDITION 4.2
address@hidden VERSION 4.2
+
address@hidden @set myversion @value{VERSION}
address@hidden myversion 102
+
address@hidden myurl
@url{http://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}
+
address@hidden Minik{}
+Miniker
address@hidden macro
+
address@hidden Miniker 102 manual
+
address@hidden fn vr
+
address@hidden Miscellaneous
address@hidden
+* Miniker: (mini_ker). The mini_ker modeling tool.
address@hidden direntry
+
+
+
+
address@hidden Top
address@hidden Miniker 102 manual
+
+
address@hidden @insertcopying
+
address@hidden Miniker 102 manual
+
address@hidden: The TEF Collaboration}
+
address@hidden
+
+
address@hidden
+* Introduction::
+* TEF overview::
+* A model with Miniker::
+* Advanced programming::
+* Dynamic system analysis::
+* Advanced use of Miniker with make::
+
+Indices
+
+* Concepts index::
+* Variables macros and functions index::
+
+Appendices
+
+* Installation::
+* Cmz directives reference::
+* Copying This Manual:: The GNU Free Documentation License.
address@hidden menu
+
address@hidden
+
address@hidden Introduction
address@hidden Introduction
+
address@hidden TEF
address@hidden cells
address@hidden transfers
address@hidden ZOOM
address@hidden mortran
+
+ Miniker is a modeling tool, built especially in order to implement
+models written following the @acronym{TEF,Transfer Evolution Formalism}
+formalism, a mathematical framework for system analysis and
+simulation. Miniker allows for timewise simulation, system analysis,
+adjoint computation, Kalman filtering and more.
+
+Miniker uses a fortran preprocessor, @command{mortran}, designed in the
+1970's, to ease model writing using dedicated specific languages.
+For example partial derivatives are
+symbolicaly determined by @command{mortran} macros in Miniker.
+For the selection of
+another compile-time features, another set of preprocessor directives,
+the @dfn{cmz directives}, are used. In most cases the user does not need to
+know anything about that preprocessing that occurs behind the scene,
+he simply writes down the equations of his model and he is done.
+
address@hidden All partial derivatives needed to solve the TEF system are
automatically
address@hidden determined during the pre-compilation stage.
address@hidden Once all models written down and initial conditions
address@hidden given using a pseudo-Fortran type of language, the model is
ready to run.
+
address@hidden The language developed to get automatic symbolic partial
derivatives
address@hidden uses the Fortran pre-compiler @command{mortran}, designed in the
1970's.
+
+A comprehensive description
+of the @acronym{TEF} formalism in available on
address@hidden://www.lmd.jussieu.fr/ZOOM/doc/tef-GB-partA5.pdf}).
+The Miniker software is a reduced version of
address@hidden://www.lmd.jussieu.fr@//zoom,@strong{ZOOM}},
+that can only handle a hundreds of variables, but is much easier to use.
+
address@hidden
+* Intended audience::
+* Reading guide::
+* Other Manuals and documentation::
address@hidden menu
+
address@hidden Intended audience
address@hidden Intended audience
+
+The reader should have notions in system dynamics.
address@hidden and understand the basis of the TEF.
+Moreover a minimal knowledge of programmation and fortran is
+required. What is required is a basic understanding of variable types,
+affectation and fortran expressions.
+
address@hidden Reading guide
address@hidden Reading guide
+
+The first chapter is a brief overview of the @acronym{TEF}.
+The following describes how to write, compile and run a model in Miniker
+in its basic and comprehensive syntax.
address@hidden Reading the sections of this chapter up to the section
address@hidden @emph{Symbolic model description} is required to know the
address@hidden syntax of model description in @Minik{}.
+Reading up to the section
address@hidden the run} is required to be able to use Miniker.
+In this section it is assumed that Miniker is properly setup. The
+installation instructions are in the appendix at
address@hidden
+
address@hidden 2 programming environment to compile the model are available,
with cmz
address@hidden and make, you can skip the method description you are not
interested in.
address@hidden A reference for the usefull cmz directives is also in the
appendix
address@hidden (@pxref{Cmz directives reference}).
+
address@hidden You should also
address@hidden read the following section, @emph{Symbolic model description}
which presents an
address@hidden alternate syntax for model description, such that you can choose
what you
address@hidden prefer.
+
+The next chapter describes advanced features, first a general introduction to
+features settings and then a description of other model description related
+features.
+
+The next chapter describes system analysis tools available with Miniker. The
+sections are independant and each describes how to use a specific feature. If
+you plan on using these features, you should also read
address@hidden features, , Overview of feature setting}.
+
+A final chapter describes advanced features in a development environment
+using make,
+
+In the appendix the instructions for the installation are described
+(@pxref{Installation}).
+
address@hidden Other Manuals and documentation
address@hidden Other Manuals and documentation
+
+A programmers'Manual is available (in French), and can be asked for to
+any member of the collabration. See additional documents in
+ @url{http://www.lmd.jussieu.fr/Zoom/doc} or ask for Research
+texts and articles to members.
+
address@hidden TEF overview
address@hidden An overview of the @acronym{TEF} formalism
+
+The @acronym{TEF, Transfer Evolution Formalism} is based on partitionning
+and recoupling of model subsystems. It allows the study of the coupling
+between subsystems by the means of linearization and time discretization.
+
address@hidden
+* Cell and Transfer::
+* Linearization and discretization::
address@hidden menu
+
address@hidden Cell and Transfer
address@hidden Cell and Transfer equations
+
+In the @acronym{TEF}, a model is
+mathematically represented by a set of equations corresponding
+to two kinds objects:
+
address@hidden
address@hidden Cells which are elementary models and correspond to evolution
equations
+such as:
address@hidden
+$$\partial_t \eta (t) = g(\eta(t),\varphi(t))$$
address@hidden tex
+
address@hidden @math{d eta(t)/d t = g(eta(t),phi(t))}
+
+
+Vector @math{\eta} represent the state variables of cells and
+the vector @math{\varphi} represent the dependent
+boundary conditions, @i{i.e.} the
+variables considered as boundary conditions by a cell, but depending upon
+the complete model state. This dependent boundary conditions are
+required to make the cells correspond to well-posed problems.
address@hidden FIXME acceptable?
+These variables are often called state variables, and prognostic
+variables in meteorology.
+
+
address@hidden Transfers which are determined by constraint equations such as:
address@hidden
+$$
+\varphi(t) = f(\eta(t),\varphi(t))
+$$
address@hidden tex
+
address@hidden @math{phi(t) = f(eta(t),phi(t))}
+
+These equations are often called algebraic equations, and in meteorology
+diagnostic equations.
address@hidden enumerate
+
address@hidden Linearization and discretization
address@hidden Linearization and discretization in the @acronym{TEF}
+
+The relations between sub-systems is excessively difficult to exhibit when
+having to cope with non-linear system. In the @acronym{TEF}, the
address@hidden, Tangent Linear System} is constructed along the trajectory.
+One considers the system over a small portion along the trajectory, say
+between @math{t} and @math{t + \delta t}. The variation @math{\delta \eta}
+of @math{\eta} and @math{\delta \varphi} of @math{\varphi} is obtained
+through a Pad@'e approximation of the state-transition matrix. The final
+form of the algebraic system is closed to the classical Crank-Nicolson scheme:
+
address@hidden FIXME PAd'e? od Taylor?
address@hidden through a Taylor expansion followed by time integration.
address@hidden A time scheme is then applied to the @acronym{TLS} (a
Crank-Nicholson scheme),
address@hidden to obtain an algebraic system describing the relationships
between
address@hidden variations of transfers and cells variables:
+
+
+
address@hidden
+$$\pmatrix{A & B\cr
+-C^+ & I-D\cr} \pmatrix{\delta \eta\cr
+\delta \varphi\cr} = \pmatrix{\Gamma\cr
+\Omega\cr}$$
address@hidden tex
+
+The blocks appearing in the Jacobian matrix are constructed with partial
derivative
+of @math{f} and @math{g}, and with @math{\delta t}. From this system the
+elimination of @math{\delta \eta} leads to another formulation giving
+the coupling between transfers, and allows for the @math{\delta \varphi}
+computation. The @math{\delta \varphi} value is then substitued in
address@hidden \eta} to complete the time-step solving process.
+
address@hidden A model with Miniker
address@hidden Miniker model programming
+
address@hidden sequences
+
+Miniker works by combining the model specification code given by
+the user and other source files provided in the package. The code is
+assembled, preprocessed, compiled, linked and the resulting program
+can be run to produce the model trajectory and dynamic analysis.
+
+The code provided in the package contains a principal program, some usefull
+subroutines and pieces of code called @dfn{sequences} combined with the
+different codes. Among these sequences some hold the code describing the model
+and are to be written by the user (sequences are similar to
+Fortran include files).
+
address@hidden
+* Structure of the code::
+* A model description::
+* Setting and running a model::
+* Controlling the run::
address@hidden menu
+
address@hidden Structure of the code
address@hidden General structure of the code
+
address@hidden sequence
address@hidden zinit, general
+
+The sequences used to enter model description hold the @c vector dimensions,
+mathematical formulae for each cell and transfer component, dedicated
+derived computations, and time-step
+steering. During the code generation stage,
+cmz directives are preprocessed, then the user pseudo-Fortran
+instructions are translated by @command{mortran} using macros designed to
+generate in particular all Fortran instructions that compute the Jacobian
+matrices used in @acronym{TEF} modelling.
+
address@hidden A first users' sequence to program is: @file{dimetaphi} where
the model
address@hidden dimensions are given, for the two vector-array @code{eta(.)} for
cells
address@hidden and @code{ff(.)} for transfers (@pxref{Model size,,Entering
model size}).
+
+The sequence @file{zinit} contains the mathematical formulation of the model
+(@pxref{Model equation and parameters, Entering model equation and
parameters}).
+Another sequence, @file{zsteer}, is merged at
+the end of the time step advance of the simulation, where the user can
+monitor the time step values and printing levels, and perform particular
+computations etc.
+(@pxref{End of time step, ,Executing code at the end of each time step}).
+
address@hidden A model description
address@hidden Miniker programming illustrated
+
address@hidden TEF
+
+The general @acronym{TEF} system writes:
address@hidden
+$$\eqalign{\partial_t \eta (t) &= g(\eta(t),\varphi(t))\cr
+\varphi(t) &= f(\eta(t),\varphi(t))\cr
+}$$
address@hidden tex
+
address@hidden @math{d eta(t)/d t = g(eta(t),phi(t))@*
+phi(t) = f(eta(t),phi(t))}
+
+
+To illustrate the model description in Miniker a simple predator-prey
+model of Lotka-Volterra is used.
+This model can be written in the following @acronym{TEF} form:
+
address@hidden
+$$\left\{\eqalign{\partial_t \eta _{prey} &= a \eta _{prey} - a \varphi
_{meet} \cr
+\partial_t \eta _{pred} &= -c \eta _{pred} + c \varphi _{meet}\cr}\right.$$
address@hidden tex
address@hidden
+$$\varphi _{meet} = \eta _{prey}\eta _{pred}$$
address@hidden tex
address@hidden @math{d eta_prey(t)/d t = a * eta_prey - a * address@hidden
+d eta_pred(t)/d t = -c * eta_pred +c * phi_meet}
+
address@hidden @math{phi_meet = eta_prey * eta_pred}
+
+with two cell equations, @i{i.e}. state evolution of the prey and predator
+groups, and one transfer accounting for the meeting of individuals of
+different group.
+
address@hidden
+* A note about mortran and cmz directives::
+* Model equation and parameters::
address@hidden menu
+
address@hidden A note about mortran and cmz directives
address@hidden All you need to know about mortran and cmz directives
+
address@hidden mortran
+
+The first stage of code generation consists in cmz directives preprocessing.
+Cmz directives are used for conditional selection of features, and sequence
+inclusion. At that point you don't need to know anything about these
+directives. They are only usefull if you want to take advantage of advanced
+features
+(@pxref{Programming with cmz directives}).
+
+The code in sequences is written in Mortran and the second stage of code
+generation consists in mortran macro expansion. The mortran language is
+described
+in its own manual, here we only explain the very basics which is all you need
+to know to use Miniker. Mortran basic instructions are almost Fortran,
+the differences are the following:
+
address@hidden @bullet
address@hidden The code is free-form, and each statement should end with a
semi-colon
address@hidden;}.
address@hidden Comments may be introduced by an exclamation mark @code{!} at
the
+beginning of a line, or appear within double quotes @code{"} in a single line.
address@hidden It is possible to use blocs, for @code{do} or @code{if}
statement
+for example, and they are enclosed within brackets @samp{<} and @samp{>}.
+To be in the safe side, a semi-colon @code{;} should be added after a
+closng bracket @code{>}.
address@hidden itemize
+
+The following fictious code is legal mortran:
+
address@hidden
+real
+ param;
+param = 3.; ff(1) = ff(3)**eta(1); "a comment"
+! a line comment
+do inode=1,n_node <eta_move(inode)=0.01; eta_speed(inode)=0.0;>;
address@hidden example
+
+Thanks to mortran the model code is very simply specified, as you'll
+see next.
+
+
address@hidden Model equation and parameters
address@hidden Entering model equation and parameters
+
address@hidden @file{zinit}
address@hidden dt
address@hidden time
address@hidden nstep
address@hidden modzprint
+
+The model equation and parameters and some Miniker parameters are entered in
+the @file{zinit} sequence. The whole layout of the model is given
+before detailing the keywords.
+
address@hidden
+!%%%%%%%%%%%%%%%%%%%%%%
+! Parameters
+!%%%%%%%%%%%%%%%%%%%%%%
+ real apar,bpar; "optional Fortran type declaration"
+
+! required parameters
+ dt=.01; "initial time-step"
+ nstep=10 000; "number of iterations along the trajectory"
+ time=0.; "time initialisation "
+
+! model parameters
+ apar = 1.5;
+ cpar = 0.7;
+
+! misceallaneous parameters
+ modzprint = 1000; "printouts frequency"
+
+print*,'***************************************';
+print*,'Lotka-Volterra model with parameters as:';
+z_pr: apar,bpar;
+print*,'***************************************';
+
+!%%%%%%%%%%%%%%%%%%%%%%
+! Transfer definition
+!%%%%%%%%%%%%%%%%%%%%%%
+! rencontre (meeting)
+set_Phi
+< var: ff_interact, fun: f_interact = eta_prey*eta_pred;
+>;
+
+!%%%%%%%%%%%%%%%%%%%%%%
+! Cell definition
+!%%%%%%%%%%%%%%%%%%%%%%
+
+set_eta
+< var: eta_prey, fun: deta_prey = apar*eta_prey - apar*ff_interact;
+ var: eta_pred, fun: deta_pred = - cpar*eta_pred + cpar*ff_interact;
+>;
+
+
+!%%%%%%%%%%%%%%%%%%%%%%
+! Initial states
+!%%%%%%%%%%%%%%%%%%%%%%
+ eta_prey = 1.;
+ eta_pred = 1.;
+;
+ OPEN(50,FILE='title.tex',STATUS='UNKNOWN'); "title file"
+ write(50,5000) apar,cpar;
+5000;format('Lotka-Volterra par:',2F4.1);
address@hidden example
+
address@hidden Variables and model parameters
+
+The following variables are mandatory:
+
address@hidden @code
address@hidden dt
+The time step.
address@hidden time
+Model time initialisation.
address@hidden nstep
+Number of iterations along the trajectory.
address@hidden table
+
+There are no other mandatory variables. Some optional variables are used
+to monitor the printout and ouput of results of the code.
+As an example, the variable @code{modzprint} is used to set
+the frequency of the printout of the model matrix and vectors during the
+run (@pxref{Controlling the printout and data output}).
+
+User's defined variable and Fortran or Mortran instructions can always be
+added for intermediate calculus. To avoid conflict with the variables of the
+Miniker code, the rule is that a users symbol must not have characters
address@hidden
+in the first two symbol characters.
+
+In the predator-prey example there are two model parameters. The fortran
+variables are called here @code{apar} for @math{a} and @code{cpar} for
@math{c}.
+If a Fortan type definition is needed, it should be set at the very beginning
+of @file{zinit}. The predator-prey code variable initializations finally reads
+
address@hidden
address@hidden
+!%%%%%%%%%%%%%%%%%%%%%%
+! Parameters
+!%%%%%%%%%%%%%%%%%%%%%%
+ real apar,bpar; "optional Fortran type declaration"
+
+ dt=.01;
+ nstep=10 000;
+ time=0.;
+
+! model parameters
+ apar = 1.5;
+ cpar = 0.7;
+
+ modzprint = 1000;
address@hidden group
address@hidden example
+
address@hidden Model equations
address@hidden equations}
+
address@hidden set_Phi
address@hidden set_eta
address@hidden var:
address@hidden fun:
address@hidden eqn:
+
+The model equations for cells and model equations for transferts are
+entered in two mortran blocks, one for the transferts, the other for the
+cell components. The model equations for cells are entered into a
address@hidden block, and the transfer equations are entered into a
address@hidden block.
+
+In each block the couples variable-function are specified. For
+transfers the function defines the transfer itself while for cells
+the function describes the cell evolution. The variable is specified
+with @code{var:}, the function is defined with @code{fun:}.
+
+In the case of the predator-prey model, the transfer variable
+associated with @math{\varphi_{meet}} could be called @code{ff_interact}
+and the transfer definition would be given by:
address@hidden
+set_Phi
+< var: ff_interact, fun: f_interact = eta_prey*eta_pred;
+>;
address@hidden example
+
+The two cell equations of the predator-prey model, with name
address@hidden for the prey (@math{\eta_{prey}}) and @code{eta_pred}
+for the predator (@math{\eta_{pred}}) are:
+
address@hidden
+set_eta
+< var: eta_prey, fun: deta_prey = apar*eta_prey - apar*ff_interact;
+ var: eta_pred, fun: deta_pred = - cpar*eta_pred + cpar*ff_interact;
+>;
address@hidden example
+
+The @samp{;} at the end of the mortran block is important.
+
address@hidden
+The whole model equations are setup with:
+
address@hidden
address@hidden
+!%%%%%%%%%%%%%%%%%%%%%%
+! Transfer definition
+!%%%%%%%%%%%%%%%%%%%%%%
+! rencontre (meeting)
+set_Phi
+< var: ff_interact, fun: f_interact = eta_prey*eta_pred;
+>;
+
+!%%%%%%%%%%%%%%%%%%%%%%
+! Cell definition
+!%%%%%%%%%%%%%%%%%%%%%%
+
+set_eta
+< var: eta_prey, fun: deta_prey = apar*eta_prey - apar*ff_interact;
+ var: eta_pred, fun: deta_pred = - cpar*eta_pred + cpar*ff_interact;
+>;
address@hidden group
address@hidden example
+
+Whenever the user is not concerned with giving a specific name to a
+function, it is possible to specify the equation only with
address@hidden:}. Therefore the user may replace an instruction as:
address@hidden
+ var: ff_dump,
+ fun: f_dump = - rd*(eta_speed - eta_speed_limiting);
address@hidden example
+with:
address@hidden
+ eqn: ff_dump = - rd*(eta_speed - eta_speed_limiting);
address@hidden example
+
+In that case, the unnamed function will take the name of the defined
+variable preceded by the @samp{$} sign: @code{$ff_dump}.
+
address@hidden Starting points
+
address@hidden starting point
+
+The cells equations require state initial conditions. In some case, the
+transfers may also need starting points although they are determined from
+the cell values.
+
+In the predator-prey model the starting points for cells are:
address@hidden
+! initial state
+! -------------
+ eta_prey = 1.;
+ eta_pred = 1.;
address@hidden example
+
+When there is a non trivial implicit relationship between the transfers
+in the model, it may be usefull or even necessary to set some
+transfers to non-zero values. This difficulty is only relevant for the very
+first step of the simulation and will be used as a
+first guess of @math{\varphi}. The uninitialized transfers having
+a default compiler-dependant (often zero) value, an initialization
+to another value may help avoiding singular functions or matrix and
+ensure convergence in the Newton algorithm used to solve the transfer implicit
+equation.
+
+
address@hidden The cell and transfer arrays
+
address@hidden eta(.)
address@hidden ff(.)
address@hidden mp
address@hidden np
+
+Sometime it is easier to iterate over an array than to use the
+cell or transfer variable name. This is possible because there is a
+correspondence between the variable names
+and the fortran array @code{eta(.)} for the cell variables and
+the fortran array @code{ff(.)} for the transfer address@hidden fact
+the variables names are transformed into fortran array elements
+by mortran generated macros, so the symbolic names defined in the
+mortran blocks never appears in the generated fortran code, they are
+replaced by the fortran arrays.}.
+
+The index of the variable is determined by the order of appearance in
+the variable definition blocks. It is reminded in the output, as
+explained later (@pxref{Simulation and output}).
+
+The number of cells is in the integer @code{np} variable, and the
+number of transfer is in the integer @code{mp} variable.
+
address@hidden title file
+
address@hidden file}
address@hidden title file
address@hidden @file{title.tex}
+
+For some graphics generation, a file with name @file{title.tex} is required
+which sets the title. The following instructions take care of that:
+
address@hidden
+ OPEN(50,FILE='title.tex',STATUS='UNKNOWN');
+ write(50,5000) apar,cpar;
+5000;format('Lotka-Volterra par:',2F4.1);
+
+ close(50);
address@hidden example
+
+In that case the parameter values are written down, to differenciate between
+different runs. This step is in general not needed.
+
address@hidden The correspondence with basic components are printed out at
execution
address@hidden time as explained in @ref{Simulation and output,,
address@hidden Running a simulation and using the output}. Also, a
@file{Model.hlp} is
address@hidden generated that recalls the basic names and equations of the
model.
address@hidden It may be noted that whenever
address@hidden the order of variable-functions is the same between indexed
declaration and
address@hidden symbolic, the two generated Fortran code are almost identical.
+
address@hidden Setting and running a model
address@hidden Setting and running a model
+
+In this section it is assumed that a programming environment has been
+properly setup. This environment may use either cmz or make to drive
+the preprocessing and compilation.
+You can skip the part related with the environment you don't intend to use.
+
+For instructions regarding the
+installation, see @ref{Installation}.
+
+
address@hidden
+* Setting up a model with cmz::
+* Setting up a model with make::
+* Simulation and output::
+* Graphics::
address@hidden menu
+
address@hidden Setting up a model with cmz
address@hidden Setup a model and compile with cmz
+
address@hidden @command{mod}
address@hidden @file{$zinit}
address@hidden @file{$dimetaphi}
+
+The user defined sequences are @samp{KEEP} in the
+cmz world. The most common organization is to have a cmz file in a
+subdirectory of the directory containing the @file{mini_ker.cmz}
+cmz file. In this
+cmz file there should be a @samp{PATCH} called @samp{zinproc}
+with the KEEPs within the patch. The KEEP must be called @file{$zinit}.
address@hidden and @file{$dimetaphi}.
+
+From within cmz in the directory of your model the source extraction,
+compilation and linking will be triggered by a @command{mod} command. This
macro
+uses the @file{selseq.kumac} information to find the @file{mini_ker.cmz}
+cmz file.
address@hidden
+shall create a directory with the same name than the cmz file,
address@hidden/} in our example. In this directory there is another
+directory @file{cfs/} containing the sources extracted from the cmz file.
+
+The file @file{mymodel_o.tmp} contains all the mortran code generated
+by cmz with the sequences substituted, including the @file{$zinit}. @c and
address@hidden @file{$dimetaphi} sequences (assembled code).
+The fortran produced by the preprocessing and
+splitting of this file is in files with the traditional @samp{.f} suffix.
+The principal program is in @file{principal.f}. An efficient way of getting
+familiar with mini_ker methods is looking at the @file{mymodel_o.tmp} where
+all sequences and main Mortran instructions are gathered. Symbolic derivation
address@hidden FIXME pas ici la symbolic derivation
+is noted as @code{F_D(expression)(/variable)}, and the resulting Fortran code
+is in @file{principal.f}.
+
address@hidden also triggers compilation and linking. The object files are in
+the same @file{cfs/} directory and the executable is in the @file{mymodel/}
+directory, with name @file{mymodel.exe}.
+
address@hidden Setting up a model with make
address@hidden Setup a model and compile with make
+
address@hidden compilation
address@hidden @cindex @file{dimetaphi.mti}
address@hidden @file{zinit.mti}
address@hidden model_file_name
+
+With make, the sequences are files ending with @samp{.mti} (for
+mortran include files),
+called, for example, @file{zinit.mti}.
address@hidden and @file{dimetaphi.mti}.
+They are included by
address@hidden in other source files. You also need a @file{Makefile}
+to drive the compilation of the model.
+
+If you don't need additional code or libraries to be linked with your
+model you have two alternatives.
+
address@hidden
address@hidden
+The simplest alternative is to run
+the @command{start_miniker} script with the model file name as argument.
+It should copy a @file{zinit.mti} file
+ready to be edited and a Makefile ready to compile the model. For
+the predator prey model, for example, you could run
+
address@hidden
+$ start_miniker predator
address@hidden example
+
address@hidden
+Otherwise you can copy the Makefile from @file{template/Makefile}
+in the directory containing the sequences. You should then change the compiled
+model file name, by changing the value of the
address@hidden variable to the name of your choice
+in the Makefile. It is set to @file{mymodel} in the template. For the
+predator-prey model, it could be set like
+
address@hidden
+model_file_name = predator
address@hidden example
+
+If you want the executable model file to be built in another directory, you
could
+set
+
address@hidden
+model_file_name = some_dir/predator
address@hidden example
+
+The other items set in the default Makefile should be right.
address@hidden enumerate
+
+The preprocessing and the compilation are launched with
+
address@hidden
+make all
address@hidden example
+
+The mortran files are generated by the cmz directive preprocessor
+from files found in the package source directories. The mortran files
+end with @samp{.mtn} for the main files and @samp{.mti} for
+include files. They are output in the current directory.
+The mortran preprocessor then preprocess these mortran files and includes
+the sequences. The resulting fortran code is also in the current directory,
+in files with a @samp{.f} suffix.
+Some fortran files ending with @samp{.F} may also be
+created by the cmz directive preprocessor.
+The object files resulting from the compilation of all the
+fortran files (generated from mortran or directly from fortran files) are
+there too.
+
+In case you want to override the default sequences or a subroutine file
+you just have to create it in your working directory along with the
address@hidden @c and @file{dimetaphi.mti}.
+For example you could want to
+create or modify a @file{zsteer.mti} file (@pxref{End of time step,,
+Executing code at the end of each time step}), a @file{zcmd_law.mti} file
+(@pxref{Control laws}), a @file{monitor.f} file
+(@pxref{Turning the model into a subroutine}) to take advantage of
+features presented later in this manual.
+
+More in-depth discussion of using make to run Miniker is covered in
address@hidden use of Miniker with make}.
+For example it is also possible to create files that are to be
+preprocessed by the cmz directive
+preprocessor and separate source files and generated files.
+This advanced use is more precisely covered in
address@hidden with cmz directives}.
+
address@hidden
address@hidden Simulation and output
address@hidden Running a simulation and using the output
+
address@hidden running model
+
+Once compiled the model is ready to run, it only has to be executed. On
+standard output informations about the states, transfers, tangent linear
+system and other jacobian matrices are printed.
+For example the predator-prey model could be executed with:
+
address@hidden
+./predator > result.lis
address@hidden example
+
address@hidden output file
address@hidden dEta(.)
address@hidden @file{res.data}
address@hidden @file{dres.data}
address@hidden @file{tr.data}
address@hidden @file{aspha.data}
address@hidden @file{Model.hlp}
+
address@hidden In case of a model entered symbolically
address@hidden (@pxref{Symbolic model description})
+The correspondance
+between the symbolic variables and the basic vectors and functions
+are printed at run time:
+
address@hidden
+ ---------------- Informing on Phi definition -----------------
+ Var-name, Function-name, index in ff vector
+ ff_interact f_interact 1
+ ----------------------------------------------------
+
+ --------------- Informing on Eta definition ------------------
+ Var-name, Function-name, index in eta vector
+ eta_prey deta_prey 1
+ eta_pred deta_pred 2
address@hidden example
+
+A summary of the model equations are in @file{Model.hlp} file. For
+the same example:
+
address@hidden
+======================= set_Phi
+
+ 1 ff_interact f_interact eta_pray*eta_pred
+======================= set_Eta
+
+ 1 eta_pray deta_pray apar*eta_pray-apar*ff_interact
+ 2 eta_pred deta_pred -cpar*eta_pred+cpar*ff_interact
address@hidden example
address@hidden FIXME never talked about that. Certainly not here
+when other general functions are specified with @code{f_set}, it can appear
+also in the same help file when replaced by @code{fun_set}.
+
+As far as possible, all data printed in the listing are associated
+with a name related to a variable. Here is an extract:
+
address@hidden
+ Gamma :-8.19100E-02-1.42151E-01 3.87150E-02
+ eta_courant eta_T_czcx eta_T_sz
+ ------------------------------------------------
+ Omega : 0.00000E+00 0.00000E+00 0.00000E+00 0.00000E+00
+ courant_L T_czcx Psi_Tczc Psi_Tsz
+ ------------------------------------------------
address@hidden example
+for the two known vectors of the system, and:
address@hidden
+ >ker : Matrice de couplage 4 4 4 4
+courant_L Raw(1,j=1,4): 1.000 -9.9010E-03 0.000 0.000
+T_czcx Raw(2,j=1,4): -2.7972E-02 1.000 0.000 9.9900E-04
+Psi_Tczcx Raw(3,j=1,4): 0.1605 9.7359E-02 1.000 -5.7321E-03
+Psi_Tsz Raw(4,j=1,4): 0.000 -0.1376 5.7225E-03 1.000
+ Var-Name courant_L T_czcx Psi_Tczc Psi_Tsz
+ ----------------------------------------------------------
address@hidden example
+
+where the @code{couplage} (coupling matrix) is given that corresponds
+to the matrix coupling the four transfer components after @math{\delta\eta}
+has been eliminated from system. It is computed in the subprogram
address@hidden (for kernel) which solves the system.
+
+Basic results are output in a set of @samp{.data} files.
+The first line (or two lines) describes the column with a @samp{#}
+character used to mark the lines as comments (for @command{gnuplot}
+for example).
+In the @samp{.data} files, the data are simply separated with spaces.
+Each data file has the @code{time} variable values as first column.
address@hidden@file{dres.data} has another time related variable as second
column:
address@hidden @file{dres.data}
address@hidden dt
address@hidden, the time step that can vary in the course of a simulation.}.
+Following columns give the values of @code{eta(.)} in @file{res.data},
address@hidden(.)} in @file{dres.data} -- the step by step variation of
address@hidden(.)} -- and @code{ff(.)} in @file{tr.data}.
+
+Along the simulation the @acronym{TEF} Jacobian matrices are computed.
+A transfer variables elimination process also leads to the definition
+of the classical state advance matrix of the system
+(the corresponding array is @code{aspha(.,.)} in the code).
+This matrix is output in the file @file{aspha.data} that is used to
+post-run dynamics analyses. The matrix columns are written column wise on each
+record.
address@hidden of fastest modes,,Stability analysis of fastest modes}.
address@hidden TLS,,Generalized
+tangent linear system analysis}. It is not used in the solving process.
+
+Other @samp{.data} files will be described later.
+
address@hidden FIXME already said
address@hidden At the begining of a run, the help file @file{Model.hlp} is
generated for
address@hidden global checkiing of the model. In the example, it is:
+
address@hidden @example
address@hidden ======================= set_Phi
address@hidden 1 ff_interact f_interact eta_pray*eta_pred
address@hidden ======================= set_Eta
address@hidden 1 eta_pray deta_pray
apar*eta_pray-apar*ff_interact
address@hidden 2 eta_pred deta_pred
-cpar*eta_pred+cpar*ff_interact
address@hidden @end example
+
+
address@hidden Graphics
address@hidden Doing graphics
+
address@hidden graphics
address@hidden graphics with @command{gnuplot}
address@hidden graphics with @command{PAW}
+
address@hidden The format of the @samp{.data} files are coherent with GNU
graphics, that is
address@hidden the data are simply separated with spaces.
+Since the data are simply separated with spaces, and comment lines
+begin with @samp{#}, the
+files can be vizualised with many programs.
+With @command{gnuplot}, for example, to plot @code{eta(@var{n})},
+the @command{gnuplot} statement could be:
+
address@hidden
+plot "res.data" using 1:(@var{n}+1)
address@hidden example
+
+The similar one for @code{ff(@var{n})}:
address@hidden
+plot "tr.data" using 1:(@var{n}+1)
address@hidden example
+
+For people using @command{PAW}, the CERN graphical computer code,
+Miniker prepares
+kumacs that allow to read process the @samp{.data} files in the form of
address@hidden (see the @cite{PAW manual} for more information).
+In that cas, the flag @code{sel paw} has to be gievn in the
@file{selsequ.kumac}.
+The generated n-tuples are ready to use only
+for vector dimension of at most 10 (including the variable @code{time}).
+These kumacs are overwritten each time the model is run. Usaually, gnuplot has
+to be preferred, but when using surfaces and histograms, PAW is better.
+The @file{gains.f} (and @file{go.xqt} is provided as an example in the
+Miniker files.
+
address@hidden Controlling the run
address@hidden Controlling the run
+
address@hidden controlling the run
+
+It is possible to add code that will be executed at the end of each time
+step. It is also possible to specify which time step leads to a printout on
+standard output. For maximal control, the code running te model may be
+turned into a subroutine to be called from another fortran (or C)
+program, this possibility is covered in @ref{Calling the model code}.
+
address@hidden
+* End of time step::
+* Controlling the printout and data output::
address@hidden menu
+
address@hidden End of time step
address@hidden Executing code at the end of each time step
+
address@hidden @file{zsteer}
address@hidden @file{zsteer.inc}
+
+The code in the sequence @file{zsteer} is executed at the end of each time
+step. It is possible to change the time step length (variable @code{dt})
+verify that the non linearity are not too big, or perform
+discontinuous modifications of the states. One available variable @code{res}
+might be usefull for time step monitoring. At the end of the time step,
+as soon as @math{\varphi} has been computed, a numerical test is applied
+on a pseudo relative quadratic residual between
address@hidden(\eta(t-dt)+d\varphi} (@code{ ffl}), where @math{d\varphi}
+is given by the system resolution in @code{ker},and
address@hidden(\eta),\varphi)}, Fortran variable (@code{ff}):
+
address@hidden
+! ========================================================
+! test linearite ffl - ff
+! ========================================================
+if (istep.gt.1)
+< res=0.; <io=1,m; res = res +(ffl(io)-ff(io))**2/max(one,ff(io)*ff(io)); >;
+ if (res .gt. TOL_FFL)
+ < print*,'*** pb linearite : res > TOL_FFL a istep',istep,res,' > ',TOL_FFL;
+ do io=1,m < z_pr: io,ff(io),ff(io)-ffl(io); >;
+ >;
+>;
address@hidden verbatim
+
+This test hence applies only for non linearities in tranfer models.
Nevertheless,
address@hidden might be usefull to monitor the time step @code{dt} in
@code{ZSTEER}
+and eventually go backward one step (@code{goto :ReDoStep:}).
+This can more appropriatly be coded in the (empty in default case)
+sequence @code{zstep}, inserted just before time-advancing
+states and @code{time} variables in @file{principal}.
address@hidden ffl(.)
address@hidden @code{ffl} (linearity test)
address@hidden linearity test
+
+It is also possible to fix the value of the criterium @code{TOL_FFL} in
address@hidden different from its default value of @math{10^{-3}} --
+independent of the Fortran precision.
+
+
+Many other variables are available, including
address@hidden @code
address@hidden istep
+The step number;
address@hidden couplage(.)
+The @acronym{TEF} coupling matrix between transfers;
address@hidden H
+The Jacobian matrix corresponding with:
address@hidden \varphi(t) &= f(\eta(t),\varphi(t))\cr
address@hidden \frac{\partial g(\eta(t),\varphi(t))}{\partial \eta(t)}
address@hidden
+$$\partial_{\eta} g(\eta(t),\varphi(t));
+$$
address@hidden tex
+g_1(eta,phi);
address@hidden Bb
+The Jacobian matrix corresponding with:
address@hidden
+$$\partial_{\varphi} g(\eta(t),\varphi(t));
+$$
address@hidden tex
+g_2(eta,phi);
address@hidden Bt
+The Jacobian matrix corresponding with:
address@hidden
+$$\partial_{\eta} f(\eta(t),\varphi(t));
+$$
address@hidden tex
+f_1(eta,phi);
address@hidden D
+The Jacobian matrix corresponding with:
address@hidden
+$$\partial_{\varphi} f(\eta(t),\varphi(t));
+$$
address@hidden tex
+f_2(eta,phi);
+
address@hidden aspha
+The state advance matrix;
address@hidden dneta
address@hidden dphi
+the variable increments;
address@hidden vtable
+One should be aware of that the linearity test concerns the preceding step.
+We have yet no example of managing the time-step.
+
address@hidden
address@hidden Controlling the printout and data output
address@hidden Controlling the printout and data output
+
address@hidden printing
address@hidden zprint
address@hidden modzprint
+
+The printout on standard output is performed if the variable @code{zprint}
+of type @code{logical} is true. Therefore it is possible to control this
+printout by setting @code{zprint} false or true. For example the following
+code, in sequence @file{zsteer}, triggers printing for every
address@hidden time step and the two following time steps:
+
address@hidden
+ZPRINT = mod(istep+1,modzprint).eq.0;
+Zprint = zprint .or. mod(istep+1,modzprint).eq.1;
+Zprint = zprint .or. mod(istep+1,modzprint).eq.2;
address@hidden example
+
+The data output to @file{.data} files described in @ref{Simulation and output,,
+Running a simulation and using the output} is performed if the
address@hidden variable @code{zout} is true. For example the following
+code, in @file{zsteer}, triggers output to @file{.data} files every
address@hidden step.
+
address@hidden
+Zout = mod(istep,modzout).eq.0;
address@hidden example
+
address@hidden Advanced programming
address@hidden Advanced Miniker programming
+
address@hidden
+* Selecting features::
+* Calling the model code::
+* 1D gridded model::
+* Double precision::
+* Partial Derivatives::
+* Rule of programming non continuous models::
+* Parameters::
+* Observations and data::
+* Explicit model size::
+* Programming with cmz directives::
address@hidden menu
+
address@hidden Selecting features
address@hidden Overview of additional features setting
+
address@hidden feature setting
address@hidden select flag
address@hidden logical flags
address@hidden @file{selseq.kumac}
+
+It is possible to enable some features by selecting which code should
+be part of the principal program. Each of these optionnal features are
+associated with a @dfn{select flag}.
+For example
address@hidden the optimisation with minuit is associated with the select
address@hidden flag @samp{minuik},
+double precision is used instead of simple precision with
+the @samp{double} select flag,
+the model is a subroutine with the select flag @samp{monitor},
+the Kalman filter code is set with @samp{kalman} and the 1D gridded
+model capabilities are associated with @samp{grid1d}.
address@hidden Currently it is only possible
address@hidden to select features in cmz.
+To select a given feature the cmz statement @code{sel @var{select_flag}} should
+be written down in the @file{selseq.kumac} found in the model directory.
+With make either the corresponding variable should be set to 1 or it
+should be added to the @code{SEL} make variable, depending on the feature.
+
+Other features don't need different or additional code to be used.
+Most of the features are enabled by setting specific logical variables to
address@hidden This is the case for
address@hidden for the adjoint model, @code{zcommand} if the command is in a
file
+and @code{zlaw} if it is a function and @code{zkalman} for the Kalman filter.
+These select and logical flags are described in the corresponding sections.
+
+In cmz an alternative of writing select flags to @file{selseq.kumac} is to
+drive the compilation with @code{smod @var{sel_flag}}. In that case the
address@hidden is selected and the files and executable goes to a directory
+named @file{sel_flag}.
+
+The select flags are taken into account during cmz directives preprocessing.
+Therefore you have the possibility to use these flags to conditionnaly
+include pieces of code. In most cases you don't need to include code
conditionally
+yourself though, but if you want to, this is covered in
address@hidden with cmz directives}.
+
address@hidden Calling the model code
address@hidden Calling the model code
+
+When the model code is a subroutine, it can be called from another fortran
+program unit (or another program), and the model will be
+run each time the subroutine is called.
+This technique could be used, for example to perform optimization
+(@pxref{Adjoint model and optimisation,,Adjoint model and optimisation
+with Miniker}), or to run the model with different parameters.
+
address@hidden
+* Turning the model into a subroutine::
+* The model subroutine::
address@hidden menu
+
address@hidden Turning the model into a subroutine
address@hidden Turning the model into a subroutine
+
address@hidden This feature is allready enabled with @command{make}, and to
address@hidden override the default program a file called @file{monitor.f} has
to be created
address@hidden in the working directory. The default program simple calls the
model
address@hidden subroutine.
+
+With cmz, one has to do a
address@hidden
+sel monitor
address@hidden example
+in the @file{selseq.kumac} file and create the KEEP that call the
+model code. @xref{Selecting features, Overview of additional features
+setting}.
+
+With make @samp{monitor} should be added to the @code{SEL} variable in
+the @file{Makefile}, for example:
+
address@hidden
+SEL = monitor
address@hidden example
+
+A file that call the principal subroutine should also be written, using
+the prefered language of the user. The additional object files should
+then be linked with the Miniker objects. To that aim they may be added
+to the @code{miniker_user_objects} variable.
+
address@hidden The model subroutine
address@hidden Calling the model subroutine
+
+The model subroutine is called @samp{principal} and is called with the
+following arguments:
+
address@hidden Subroutine principal (Cost, ncall, integer_flag, file_suffix,
info, idxerror)
+Where @var{Cost} is a real number, @code{real} or @code{double precision},
+and is set by the @code{principal}
+subroutine. It holds the value of the cost function if such function has been
+defined (the use and setting of a cost function is covered later,
+see @ref{Cost function coding and adjoint modeling}).
address@hidden is an integer which corresponds with the number of
+call to @code{principal} done so far, it should be initialized to 0 and
+its value should not be changed, as it is changed in the @code{principal}
+subroutine.
address@hidden is an integer that can be set by the user to be accessed
+in the @code{principal} subroutine. For example its value could be used to
+set some flags in the @file{zinit} sequence.
address@hidden is a character string, that is suffixed to the output files
+names instead of @samp{.data}. If the first character is the null character
address@hidden(0)}, the default suffix, @samp{.data} is appended.
address@hidden and @var{idxerror} are integer used for error reporting.
address@hidden value is 0 if there was no error. It is negative for
+an alert, positive for a very serious error. The precise value determines
+where the error occured.
address@hidden is an integer holding more precise information about the
+error. It is usually the information value from lapack.
+The precise meaning of these error codes is in @ref{tab:error_codes}.
address@hidden deffn
+
address@hidden table, tab:error_codes
address@hidden {kalman analysis state matrix advance in phase space,
@math{(I-D)} inversion} {inversion} address@hidden
address@hidden Source of error or warning @tab @code{info} @tab @code{idxerror}
address@hidden @item @code{} @tab @file{.data} @tab @tab
address@hidden state matrix inversion in ker @tab inversion @tab 1
address@hidden time advance system resolution in ker @tab system @tab 2
address@hidden transfer propagator, @math{(I-D)} inversion @tab inversion @tab 3
address@hidden kalman analysis state matrix advance in phase space,
@math{(I-D)} inversion @tab inversion @tab 21
address@hidden kalman analysis variance covariance matrix non positive @tab
Choleski @tab 22
address@hidden kalman analysis error matrix inversion @tab inversion @tab 23
address@hidden kalman error matrix advance @tab system @tab 24
address@hidden transfers determination linearity problem for transfers @tab
@tab -1
address@hidden transerts determination Newton D_loop does not converge @tab
@tab -2
address@hidden multitable
address@hidden of error codes returned by principal.}
address@hidden float
+
+In general more information than the provided arguments has to be passed
+to the @code{principal} subroutine, in that case a @code{common} block,
+to be written in the @file{zinit} sequence can be used.
+
address@hidden
address@hidden 1D gridded model
address@hidden Describing 1D gridded model
+
+Specific macros have been built that allow generic description of 1D gridded
models.
+Because of the necessity of defining left and right limiting conditions, the
models
+are partitionned in three groups for cell and transfer components. In the
following example,
+a chain of masselottes linked by springs and dumps is bounded to a wall on the
left,
+and open at right. The @acronym{TEF} formulation of the problem is written in
the phase space (position-shift, velocity)
+for node @math{k}, with bounding conditions:
address@hidden
+$$\left\{\eqalign{\partial_t \eta _{k} ^{pos} &= \eta _{k} ^{vel} \cr
+\partial_t \eta _{k} ^{vel} &= ( \varphi_k ^{spr} -\varphi _{k+1} ^{spr} +
\varphi _{k} ^{dmp}-\varphi _{k+1} ^{dmp})\,/m_k \cr}\right.$$
+$$\left\{\eqalign{
+\varphi_k ^{spr} &= -k_k (\eta _{k} ^{pos}- \eta _{k-1} ^{pos})\cr
+\varphi_k ^{spr} &= -d_k (\eta _{k} ^{vel}- \eta _{k-1} ^{vel})
+\cr}\right.$$
+$$\left\{\eqalign{\eta ^{pos}_{0} &= 0\cr
+\eta ^{vel}_{0} &= 0\cr
+\varphi ^{spr}_{N+1} &= 0\cr
+\varphi ^{dmp}_{N+1} &= 0\cr}\right.$$
address@hidden tex
+
+States:@*
address@hidden @math{d position(t,k)/d t = velocity(t,k)@*
+d velocity (t,k)/d t =(spring(t,k) - spring(t,k+1)+ dump(t,k)-
dump(t,k+1))/m_k}
+
+Transfers:@*
address@hidden @math{spring(t,k) = -k_k (position(t,k)- position(t,k-1))@*
+dump(k,t) &= -d_k (velocity(t,k)- velocity(t,k-1))}
+
+Bounding conditions:@*
address@hidden @math{position(t,0) = address@hidden
+velocity(t,0) = address@hidden
+spring(t,N+1) = address@hidden
+dump(t,N+1) =0}
+
+
address@hidden down node
address@hidden up node
+
+where @math{m_k} is the mass of node @math{k}, @math{r_k} and @math{d_k}
+the rigidity of springs and dumping coefficients. There are @math{N} nodes
+in the grid, from 1 to @math{N}, and two nodes outside of the grid,
+a limiting node 0, and a limiting node @math{N+1}. The limiting node
+corresponding with node 0 is called the @dfn{down} node, while the limiting
+node corresponding with node @math{N+1} is called the @dfn{up} node.
+Other models not part of the 1D grid may be added if any.
+
+To enable 1D gridded models, one should set the select flag @samp{grid1d}.
+In cmz it is achieved setting the select flag in
address@hidden, like
+
address@hidden
+sel grid1d
address@hidden example
+
+With make, the @code{SEL} variable should contain @code{grid1d}. For example
+to select @code{grid1d} and @code{monitor}, it could be
address@hidden
+SEL = grid1d,monitor
address@hidden example
+
+
address@hidden
+* 1D gridded Model size::
+* 1D gridded model code::
address@hidden menu
+
address@hidden 1D gridded Model size
address@hidden Setting dimensions for 1D gridded model
+
address@hidden FIXME grid1d sans dimetaphi?
+In that case the number of nodes, the number of states and tranferts
+per node, and the number of limiting transfers and states are required.
+These dimensions has to be entered in the
address@hidden sequence. The parameters for cells are
address@hidden @code
address@hidden n_node
+Number of cell nodes in the 1D grid.
address@hidden n_dwn
+Number of limiting cells with index -1, @i{i.e.} number of cells in the
+limiting down node.
address@hidden n_up
+Number of limiting cells with index +1, @i{i.e.} number of cells in the
+limiting up node.
address@hidden n_mult
+Number of cells in each node (multiplicity).
address@hidden vtable
+
address@hidden m_node
address@hidden m_dwn
address@hidden m_up
address@hidden m_mult
+The parameters for transfers, are similarly
address@hidden, @code{m_dwn}, @code{m_up}, @code{m_mult}.
+The layout of their declaration should be respected as
+the precompiler matches the line. Also this procedure is tedious, it
+should be selected for debuging processes (use the flag @code{sel dimetaphi}
+in ``selsequ.kumac''. Otherwise, the dimensioning sequence will be automaticaly
+generated, which is smart but can lead to diffculty in interpreting syntax
errors.
+Once a model is correctly entred, turn off the sel flag and further
modifications
+will automatically generate the proper dimensions. The correctness of
dimensionning
+should nevertheless always be checked in @code{principal.f}, where you can also
+check that null valued parameters as @code{lp, mobs, nxp} will suppress parts
+of the code - this is signaled as Fortran comment cards.
+
+In our example, there are three grids of cell and
+transfer variables (@code{n_node=m_node=3}).
+There are two cells and two transfers in each node
+(@code{n_mult=2} and @code{m_mult=2}). There is no limiting condition
+for the states in the down node therefore @code{n_up=0}.
+There is no transfer for the first limiting node, and
+therefore @code{m_dwn=0}.
+There are two states in the limiting node 0, the down node,
address@hidden, and two transfers in the limiting last node the node up,
+and @code{m_up=2}:
+
address@hidden
+! ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+! nodes parameters, and Limiting Conditions (Low and High)
+! ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+ parameter (n_node=3,n_dwn=2,n_up=0,n_mult=2);
+ parameter (m_node=3,m_dwn=0,m_up=2,m_mult=2);
+! ________________________________________________________
address@hidden example
+
+
address@hidden 1D gridded model code
address@hidden 1D gridded Model coding
+
+The model code and parameters go in the @file{zinit} sequence.
+
address@hidden Parameters
+
+A value for the Miniker parameters and the model parameters should be given in
address@hidden, in our example we have
+
address@hidden
+!%%%%%%%%%%%%%%%%%%%%%%
+! Parameters
+!%%%%%%%%%%%%%%%%%%%%%%
+real rk(n_node),rd(n_node),rmassm1(n_node);
+
+data rk/n_node*1./;
+data rd/n_node*0.1/;
+data rmassm1/n_node*1./;
+ dt=.01;
+ nstep=5 000;
+ modzprint = 1000;
+ time=0.;
address@hidden example
+
address@hidden Limiting conditions
+
address@hidden limiting conditions
+
address@hidden The limiting states and transfer variables and the corresponding
equations are
address@hidden declared using
address@hidden the symbolic model description
address@hidden (@pxref{Symbolic model description}).
+There are four mortran blocks for @code{node} and @code{up} and @code{down},
both
+for states and transfers:
+
address@hidden set_dwn_eta
address@hidden set_dwn_phi
address@hidden set_up_eta
address@hidden set_up_phi
+
address@hidden @code
address@hidden set_dwn_eta
+down node cells
address@hidden set_up_eta
+up node cells
address@hidden set_dwn_phi
+down node transfers
address@hidden set_up_phi
+up node transfers
address@hidden table
+
+The following scheme illustrates the example:
address@hidden
+!%%%%%%%%%%%%%%%%%%%%%%%%%%================================================
+! Maillage convention inode
+!%%%%%%%%%%%%%%%%%%%%%%%%%% Open ended
+!(2 Down Phi Eta (n_node)
+! Eta) \| .-----. .-----. .-----. /
+! wall \|-\/\/\-| |-\/\/\-| | . . . -| |-\/\/\- |dummy
+! pos \|--***--| 1 |--***--| 2 | . . . -| n |--***-- |Phis
+! speed \| 1 |_____| 2 |_____| n |_____| n+1 \(2 Up Phi)
+!
address@hidden smallexample
+
+Two states are associated with the down node, they correspond to the position
+and speed of the wall. As the wall don't move these states are initialized to
+be 0, and the cells are stationnary cells, therefore these values remain 0.
+
address@hidden
+! Down cells (wall)
+! -----------------
+eta_pos_wall = 0; eta_speed_wall = 0.;
+
+set_dwn_eta
+< var: eta_pos_wall, fun: deta_pos_wall = 0.;
+ var: eta_speed_wall, fun: deta_speed_wall= 0.;
+>;
address@hidden example
+
+There are 2 limiting transfers in the up node. They correspond with an open
+end and are therefore set to 0.
+
address@hidden
+! limiting Transfers : dummy ones
+! -------------------------------
+set_Up_Phi
+< var:ff_dummy_1, fun: f_dummy_1=0.;
+ var:ff_dummy_2, fun: f_dummy_2=0.;
+>;
address@hidden example
+
address@hidden Starting points
+
+The cell node state values are initialized. They are in an array
+indexed by the @code{inode} variable. In the example the variable
+corresponding with position is @code{eta_move} and the variable corresponding
+with speed is @code{eta_speed}. Their initial values are set with the
+following mortran code
+
address@hidden
+!---------------
+! Initialisation
+!---------------
+;
+do inode=1,n_node <eta_move(inode)=0.01; eta_speed(inode)=0.0;>;
address@hidden example
+
+If any transfer needs to be given a first-guess value, this is also done
+using @code{inode} as the node index.
+
address@hidden Grid node equations
+
address@hidden set_node_Phi
address@hidden set_node_eta
address@hidden equations, grid
+
+Each node is associated with an index @code{inode}. It allows to refer to the
+preceding node, with @code{inode-1} and the following node @code{inode+1}.
+The node states are declared in @code{set_node_Eta} block and the transfers are
+in @code{set_node_Phi} blocks.
+
+In the example, the cells are declared with
+
address@hidden
+! node cells
+! ----------
+;
+set_node_Eta
+< var: eta_move(inode), fun: deta_move(inode) = eta_speed(inode);
+ var: eta_speed(inode),
+ fun: deta_speed(inode) = rmassm1(inode)
+ *( - ff_spring(inode+1) + ff_spring(inode)
+ - ff_dump(inode+1) + ff_dump(inode)
+ );
+>;
address@hidden example
+Note that the @code{inode} is dummy in the @code{var:} definition and can as
+well be written as: @code{var: eta_move(.)}.
+
+
+The transfers are (@code{ff_spring} corresponds with springs and
address@hidden with dumps):
+
address@hidden
+!%%%%%%%%%%%%%%%%%%%%%%
+! Transfer definition
+!%%%%%%%%%%%%%%%%%%%%%%
+! node transfers
+! --------------
+! convention de signe spring : comprime:= +
+set_node_Phi
+< var: ff_spring(.),
+ fun:
+ f_spring(inode)= -rk(inode)*(eta_move(inode) - eta_move(inode-1));
+ var: ff_dump(.),
+ fun:
+ f_dump(inode) = -rd(inode)*(eta_speed(inode) - eta_speed(inode-1));
+>;
address@hidden example
+
+The limiting states and transfers are associated with the states or transfers
+with index @code{inode+1} or @code{inode-1} appearing in node cell and
+transfer equations (@code{inode-1} for down limiting conditions and
address@hidden for up limiting conditions) in their order of appearance.
+In our example, in the @code{eta_speed} state node equation
address@hidden(inode+1)} appears before @code{ff_dump(inode+1)} and is
+therefore associated with @code{ff_dummy_1} while @code{ff_dump(inode+1)} is
+associated with the @code{ff_dummy_2} limiting transfer, as @code{ff_dummy_1}
+appears before @code{ff_dummy_2} in the limiting up transfers definitions.
+Verification of the grid index coherence should be eased with the following
+help printed in the listing header:
+
address@hidden
+
+
+
+
+ --------------- Informing on Dwn Eta definition ---------------
+ Var-name, Function-name, index in eta vector
+ eta_pos_wall deta_pos_wall 1 [
+ eta_speed_wall deta_speed_wall 2 [
+
+ -------------- Informing on Eta Nodes definition --------------
+ Var-name, Function, k2index of (inode: 0 [ 1,...n_node ] n_node+1)
+ eta_move deta_move 1 [ 3 ... 7 ] 9
+ eta_speed deta_speed 2 [ 4 ... 8 ] 10
+
+ ---------------- Informing on Up Phi definition -------------
+ Var-name, Function-name, index in ff vector
+ ff_dummy_1 f_dummy_1 ] 7
+ ff_dummy_2 f_dummy_2 ] 8
+ ff_move_sum f_move_sum ] 9
+ ff_speed_sum f_speed_sum ] 10
+ ----------------------------------------------------
+
+ -------------- Informing on Phi Nodes definition ---------------
+ Var-name, Function, k2index of (inode: 0 [ 1,...m_node ] m_node+1)
+ ff_spring f_spring -1 [ 1 ... 5 ] 7
+ ff_dump f_dump 0 [ 2 ... 6 ] 8
+ ----------------------------------------------------
address@hidden example
+
+All variable names and functions are free but has to be
+different.
+Any particular node-attached variable @math{k} is referred to as:
@samp{(inode:k)},
+where @math{k} has to be a Fortran expression allowed in arguments. The symbol
address@hidden is
+reserved. As usual other Fortran instructions can be written within the
+Mortran block @samp{< >} of each @code{set_} block.
+
address@hidden Double precision
address@hidden Double precision
+
+The default for real variables is the @code{real} Fortran type. It is possible
to
+use double precision instead. In that case all the occurences of @samp{real@ }
+in mortran code is substituted with @samp{double precision@ } at
+precompilation stage,
+and the Lapack subroutine names are replaced by the double precision names.
+Eventual users'declaration of @code{complex@ } Fortran variables is also
+changed to @code{double complex@ }.
+
+This feature is turned on by @code{sel double} in @file{selseq.kumac} with cmz
+and @code{double = 1} in the @file{Makefile} with make.
+
+In order for the model to run as well in double as in simple precision,
+some care should be taken to use the generic intrinsic functions, like
address@hidden and not @code{dsin}. No numerical constant should be passed
directly
+to subroutines or functions, but instead a variable with the right type should
+be used to hold the constant value, taking advantage of the implicit casts
+to the variable type.
+
address@hidden Partial Derivatives
address@hidden Partial Derivatives
+
+The partial derivative rules are included in a @code{Mortran} macro series
+in @file{Derive_mac} of Miniker files. When using an anusual function,
+one should verify that the corersponding rules are in that file.
+It is easy to understand and add new rules in analogy with the already
existing ones.
+
+For instance, suppose one wants to use the intrinsic Fortran function @code{
abs()}.
+Its derivatives uses the other function @code{sign()} this way:
+
address@hidden
+ &'(ABS(#))(/#)' = '((#1)(/#2)*SIGN(1.,#1))'
address@hidden example
+
+In such cases when one is adding a new rule, it is important to use the
generic function names
+only (i.e. @code{sin} not @code{dsin}), because when compilating Miniker in
the double precision
+version, or complex version, the generic names will correctly handle the
different variable
+types - which is not the case when coding with specific function names.
+
address@hidden
+* Derivating a power function::
address@hidden menu
+
address@hidden Derivating a power function
address@hidden Derivating a power function
+
+Partial derivative of a function in exponent is not secure in its Fortran form
address@hidden(x,y)**(f(y))}. It should be replaced by @code{power(g,f)} of
+the Miniker @file{mathlib},
+or by the explicit form @code{exp(f(y)*log(g(x,y)))}.
+
+Its derivative will have the following form:
+
+
address@hidden
+$$\eqalign{\partial_x f^g &= g f^{g-1}\partial_x f + f^g \log f\partial_x g\cr
+ &= f^{g-1}(g\partial_x f + f\partial_x g)\cr}$$
address@hidden tex
+
+and is in the macros list already defined in: @file{DERIVE_MAC}.
+
address@hidden Rule of programming non continuous models
address@hidden Rule of programming non continuous models
+
+Some models may originally be non continuous, as the ones using a Fortran
instruction @code{IF}.
+Some may use implicitly a step function on a variable. In such cases, the
model has to be
+set in a derivable form, and use a ``smooth step'' instead.
+ One should be aware of that this apparently mathematical treatment currently
+indeed leads to a physical question about the macroscopic form of a physical
law.
+At a macroscipic level, a step function is usually a nonsense.
address@hidden Heaviside function
+Taking
+the example of phase-change, a fluid volume does not change phase at once, and
a ``smooth
+change of state'' is a correct macroscopic model.
+
+Miniker provides with the smooth step function
address@hidden@footnote{This naming is a joke
+for ``Inert'' Heaviside function.} in the Miniker @file{mathlib}:
+
address@hidden
+ Delta = -1."K";
+ A_Ice = heavyside("in:" (T_K-Tf), Delta, "out:" dAIce_dT);
address@hidden example
+
+in this example, @code{Tf} is the ice fusion-temperature, @code{A_ice}
+gives the ice-fraction
+of the mesh-volume of water at temperature @code{T_k}.
+The smooth-step function is a quasi
+hyperbolic tangent function of @math{x/\Delta},
+normalised from 0 to 1, with a maximum slope
+of 2.5, see figure @ref{heavy}.
+
address@hidden Figure, heavy
address@hidden
address@hidden function and derivative}
address@hidden float
+
+For @code{Mortran} to be able to symbolicaly compute the partial derivarives,
the rule
+is in the table of macros as:
+
address@hidden
+&'(HEAVYSIDE(#,#,#))(/#)' = '((#1)(/#4)*HEAVYDELTA(#1,#2,#3))'
address@hidden example
+
+which uses the Foratn entry point @code{HeavyDelta} in the Fortrsan function
@code{heavyside}.
+
+Another type of problem arises when coding a
address@hidden(f(x),g(x))} Fortran instruction.
+In such a case one does not want a derivative and one will code:
+
address@hidden
+var = HeavySide(f(x)-g(x),Delta,dum)*g(x) +
(1.-HeavySide(f(x)-g(x),Delta,dum)*f(x);
address@hidden example
+
+or equivalently:
+
address@hidden
+var = HeavySide(f(x)-g(x),Delta,dum)*g(x) +
HeavySide(g(x)-f(x),-Delta,dum)*f(x);
address@hidden example
+
address@hidden: the value of the argument @var{Delta} is important because
+it will fix the maximum
+slope of the function that will appear as a coefficient in the
+Jacbian matrices.
+
address@hidden Parameters
address@hidden Parameters
+
+It is possible to specify some Fortran variables as specific model parameters.
+Model parameters
+may be used in sensitivity studies (@pxref{Sensitivity to a parameter})
+and in the adjoint model (@pxref{Sensitivity of cost function to parameters}).
+Nothing special is done with parameters with Kalman filtering.
+
+
address@hidden Free_parameter
+
+The parameters are fortran variables that should be initialized somewhere
+in @file{zinit}. For a variable to be considered as a parameter, it should
+be passed as an
+argument to the @code{Free_parameters} macro. For example if
address@hidden and @code{cpar} (from the predator example) are to be considered
+as parameters, @code{Free_parameters} should be called with:
+
address@hidden
+Free_parameter: apar, cpar;
address@hidden example
+
address@hidden Forward sensitivities are explained later (@pxref{Sensitivity to
a parameter}),
address@hidden the syntax only is described here.
+
+
+When used with grid1d models (@pxref{1D gridded model,,
+Describing 1D gridded model}) the @code{inode} number may appear in
+parenthesis:
+
address@hidden
+Free_parameter: rd(1), rk(2);
address@hidden example
+
address@hidden Observations and data
address@hidden Observations and data
+
+Some support for observations and interactions with data is available.
+The observations are functions of the model variables. They don't have
+any action on the model result, but they may (in theory) be observed
+and measured. The natural use of these observations is to be compared
+with data that correspond with the values from real measurements.
+They are used in the Kalman filter (@pxref{Kalman filter}).
+
+The (model) observation vector is noted @math{\omega}
address@hidden FIXME is seems untrue?
address@hidden in this section ($\mu$ elsewhere,
+and the observation function is noted @math{h}:
+
address@hidden
+$$
+\omega = h ( \eta , \varphi)
+$$
address@hidden tex
+
address@hidden @math{omega(t) = h(eta(t), phi(t))}
+
+
address@hidden
+* Observations::
+* Data::
address@hidden menu
+
address@hidden Observations
address@hidden Observations
+
address@hidden mobs
+
+The observation functions are set in a @code{set_probe} block in
+the @file{zinit} sequence.
+
address@hidden observation function
+
address@hidden FIXME doesn't exist anymore
address@hidden @defmac eqn: Obs_tef(@var{i}) = f(eta(.),ff(.))
address@hidden This macro defines the observation equation as usual in a
@code{set_block<}.
address@hidden @code{f} is a fortran
address@hidden expression which may be function of cell state variables,
address@hidden @samp{eta(1)address@hidden@samp{eta(np)} and transfers
address@hidden @samp{ff(1)address@hidden@samp{ff(mp)}, or of course their
symbolic names.
address@hidden @end defmac
+
+For example suppose that, in the predator-prey model, we only
+have access to the total population of preys and predators, we would have:
+
address@hidden
+set_probe
+< eqn: pop = eta_pred + eta_pray;
+>;
address@hidden example
+
address@hidden it is always turned on, now
address@hidden The corresponding code is used with @code{sel obs} in
@file{selseq.kumac}
address@hidden with cmz and @code{obs = 1} in @file{Makefile} with make. And
the feature
address@hidden is turned on and off at run time with the logical flag
@code{zobs} corresponding
address@hidden to an available data from measurement
+
address@hidden @vindex etaobs(.)
address@hidden @file{obs.data}
+
+The number of observations is put in the integer variable @code{mobs}.
+The observation vector corresponds with the part of the @code{ff(.)}
+array situated past the regular transferts, @code{ff(mp+.)}, and is output
+in the file @file{obs.data}.
+
address@hidden @vindex obetad(.,.)
address@hidden @vindex obephid(.,.)
address@hidden @vindex obspha(.,.)
+
address@hidden Data
address@hidden Data
+
address@hidden zgetobs
address@hidden vobs(.)
address@hidden @file{data.data}
+
+Currently this code is only used if the Kalman code is activated. This
+may be changed in the future.
+
+The convention for data is that whenever some data are available, the
+logical variable @code{zgetobs} should be set to @samp{.true.}. And the
address@hidden(.)} vector should be filled with the data values. This
+vector has the same dimension than the observation
+vector and each coordinate is meant to correspond with one
+coordinate of the observation vector.
+
+This feature is turned on by setting the logical variable @code{zdata}
+to @samp{.true.}, and the @code{zgetobs} flag is typically set in the
address@hidden sequence (@pxref{End of time step,,Executing code at
+the end of each time step}).
+Every instant data are available (@code{zgetobs} is true) the observations
+are written to the file @file{data.data}. With the Kalman filter more
+informations are output to the @file{data.data} file,
+see @ref{Kalman filter results}.
+
+
address@hidden Explicit model size
address@hidden Entering model size explicitely
+
+It is possible to enter the model dimensions explicitely, instead of
+generating them automatically, as it was done previously.
+This feature is turned on by @code{sel dimetaphi}
+in @file{selseq.kumac} with cmz
+and @code{dimetaphi} added to the @code{SEL} variable in
+the @file{Makefile} with make.
+
address@hidden
+* Size sequence::
+* Model with explicit size::
address@hidden menu
+
address@hidden Size sequence
address@hidden The explicit size sequence
+
address@hidden dimetaphi
address@hidden model size
address@hidden np
address@hidden mp
address@hidden maxstep
address@hidden @file{dimetaphi}
+
+The dimension of the model is entered in the sequence @file{dimetaphi},
+using the fortran @code{parameter np} for @code{eta(.)} and
address@hidden for @code{ff(.)}.
+For the Lotka-Volterra model, we have two cell components and only one
transfer.
+
address@hidden
+parameter (np=2,mp=1);
address@hidden example
+
+You should not change the layout of the parameter statement as the
+mortran preprocessor matches the line.
+
+You also have to provide other parameters even if you don't have any
+use for them. If you don't it will trigger fortran errors.
+It includes the @code{maxstep} parameter that can have any value but 0,
address@hidden and @code{mobs} that should be 0 in the example, and @code{nxp},
address@hidden and @code{nzp} that should also be 0.
+The layout is the following:
+
address@hidden
+parameter (np=2,mp=1);
+parameter (mobs=0);
+
+parameter (nxp=0,nyp=0,nzp=0);
+parameter (lp=0);
+parameter (maxstep=1);
address@hidden example
+
+If there are observations, (@pxref{Observations}), the
+size of the observation vector is set in the @file{dimetaphi} sequence
+by the @code{mobs} parameter. For example if there is one observation:
+
address@hidden
+parameter (mobs=1);
address@hidden example
+
+To specify parameters (@pxref{Parameters}), the number of such parameters
+has to be declared in @file{dimetaphi} with the parameter @code{lp}.
+Then, if there are two parameters, they are first declared with
+
address@hidden
+parameter (lp=2);
address@hidden example
+
address@hidden Model with explicit size
address@hidden Entering the model equations, with explicit sizes
+
address@hidden model equations
address@hidden Phi_tef(.)
address@hidden deta_tef(.)
address@hidden eta(.), explicit sizes
address@hidden ff(.), explicit sizes
+
+When sizes are explicit, another possibility exists for entering
+the model equations. The use of symbolic names, as described in
address@hidden equations} is still possible, and it also becomes possible to
+set directly the equations associated with the @code{eta(.)}
+and @code{ff(.)} vectors.
+
+In case the symbolic names are not used,
+the model equations for cells and transfers are entered using a mortran macro,
address@hidden@address@hidden, or equivalently @code{f_set}, is a
+general mortran macro associating a symbol with a fortran expression.
+Here, it is the name of the symbol (@code{eta}) that has a particular meaning
+for the building of the model.}, setting the @code{eta(.)} evolution with
address@hidden(.)}
+and the transfer definitions @code{ff(.)} with @code{Phi_tef(.)}.
+
address@hidden f_set Phi_tef(@var{i}) = f(eta(.),ff(.))
+This macro defines the transfer @var{i} static equation.
address@hidden is a fortran
+expression which may be function of cell state variables,
address@hidden(1)address@hidden@samp{eta(np)} and transfers
address@hidden(1)address@hidden@samp{ff(mp)}.
address@hidden defmac
+
+In the case of the predator-prey model, the transfer definition for
address@hidden is:
address@hidden
+f_set Phi_tef(1) = eta(1)*eta(2);
address@hidden example
+
address@hidden f_set deta_tef(@var{i}) = g(eta(@var{i}),ff(.))
+This macro defines the cell state component @var{i} time evolution model.
address@hidden is a expression which may be function of cell state variables,
address@hidden(1)address@hidden@samp{eta(np)} and transfers
address@hidden(1)address@hidden@samp{ff(mp)}.
address@hidden defmac
+
+The two cell equations of the predator-prey model are, with index 1 for the
+prey (@math{\eta_{prey}}) and index 2 for the predator (@math{\eta_{pred}}):
+
address@hidden
+f_set deta_tef(1) = apar*eta(1)-apar*ff(1);
+f_set deta_tef(2) = - cpar*eta(2) + cpar*ff(1);
address@hidden example
+
+The whole model is:
+
address@hidden
+!%%%%%%%%%%%%%%%%%%%%%%
+! Transfer definition
+!%%%%%%%%%%%%%%%%%%%%%%
+! rencontres (meeting)
+ f_set Phi_tef(1) = eta(1)*eta(2);
+
+!%%%%%%%%%%%%%%%%%%%%%%
+! Cell definition
+!%%%%%%%%%%%%%%%%%%%%%%
+! eta(1) : prey
+! eta(2) : predator
+
+ f_set deta_tef(1) = apar*eta(1)-apar*ff(1);
+ f_set deta_tef(2) = - cpar*eta(2) + cpar*ff(1);
address@hidden example
+
+The starting points for cells are entered like:
address@hidden
+! initial state
+! -------------
+ eta(1) = 1.;
+ eta(2) = 1.;
address@hidden example
+
+If there are observations, they are entered as special transferts with
+index above @code{mp}, for example:
+
address@hidden
+f_set Phi_tef(mp+1) = ff(1) ;
address@hidden example
+
address@hidden Programming with cmz directives
address@hidden Programming with cmz directives
+
address@hidden
+* Cmz directives used with Miniker::
+* Using cmz directives in Miniker::
address@hidden menu
+
address@hidden Cmz directives used with Miniker
address@hidden Cmz directives used with Miniker
+
+The main feature of cmz directive is to use code conditionnaly for a given
+select flag. For example when the double precision is selected
+(@pxref{Double precision}) the use of the conditionnal
address@hidden flag may be required in case there is a different subroutine
+name for different types. If, for example, the user use the subroutine
address@hidden for simple precision and @code{dmysub} for double
+precision the following code is an example of what could appear in the
+user code:
+
address@hidden
++IF,double
+ call dmysub(eta);
++ELSE
+ call smysub(eta);
++ENDIF
address@hidden verbatim
+
+For a complete reference on cmz directives see the appendix
address@hidden directives reference}.
+
address@hidden Using cmz directives in Miniker
address@hidden Using cmz directives in Miniker
+
+In cmz the KEEP and DECK have their cmz directives preprocessed as part
+of the source files extraction. And the +KEEP and +DECK
+directives are automatically
+set when creating the KEEP or DECK. With make, files with these directives
+has to be created within the files that are to be preprocessed by the
+cmz directives preprocessor.
+
+To be processed by make, a file that contains cmz directives
+should have a file suffix corresponding
+with the language of the resulting file and with the normal file suffix of
+that language. More precisely @samp{cm} should be added before the normal
+file suffix and after the @samp{.}. Therefore if the resulting file language
+is associated with a suffix @address@hidden, the file with cmz directives
+should have a @address@hidden suffix. The tradition is to have
+a different suffix for main files and include files.
+To add directories searched for @dfn{cmfiles} (files with cmz directives)
+they should be added to the @code{CMFDIRS} makefile variable, separated
+by @samp{:}.
+
+Rules for preprocessing of the files are defined in the file
address@hidden for the file types described in
address@hidden:cmfile_suffix}:
+
address@hidden table, tab:cmfile_suffix
address@hidden {fortran preprocessed} {include/keep} {cmfile suffix} {suffix}
{language}
address@hidden language @tab file type @tab cmfile suffix @tab suffix @tab
language
address@hidden fortran @tab main/deck @tab .cmf @tab .f @tab ftn
address@hidden fortran preprocessed @tab main/deck @tab .cmF @tab .F @tab f77
address@hidden fortran preprocessed @tab include/keep @tab .cminc @tab .inc
@tab f77
address@hidden mortran @tab main/deck @tab .cmmtn @tab .mtn @tab mtn
address@hidden mortran @tab include/keep @tab .cmmti @tab .mti @tab mtn
address@hidden multitable
address@hidden between file language, file type, file suffixes and
+language identifier in cmz directives. A main file is called a @dfn{deck}
+in cmz and an include file is called a @dfn{keep}.}
address@hidden float
+
address@hidden Dynamic system analysis
address@hidden Dynamic analysis of systems in Miniker
+
address@hidden
+* Sensitivities::
+* Adjoint model and optimisation::
+* Kalman filter::
+* Feedback gain::
+* Stability of fastest modes::
+* Generalized TLS::
address@hidden menu
+
address@hidden Sensitivities
address@hidden Automatic sensitivity computation
+
address@hidden sensitivities
+
+An obvious advantage of having acces to the Jacobian matrices along the
+system trajectory concerns automatic sensitivity analyses, as either:
address@hidden @bullet
address@hidden the sensitivity of all variables to perturbation in the initial
condition
+ of one state variable;
address@hidden the same sensitivities to an initial pulse (or step) on a
transfer;
address@hidden the same sensitivities to a series of pulses (or steps) on a
transfer;
address@hidden the same for a change in a parameter, eventually during the run;
address@hidden the sensitivity of the matrix of advance in state space to a
change
+ in a parameter.
address@hidden itemize
+
+This is declared in Zinit as:
+
address@hidden
+! -------------
+! Sensitivities
+! -------------
+Sensy_to_var
+< var: eta_pray, pert: INIT;
+ var: eta_pred, pert: INIT;
+>;
address@hidden example
+
+Each variable at origin of a perturbation is declared as @code{var:},
+and the type of perturbation in @code{pert:}. Here, INIT conditions are
+only allowed because the two variables are states variables. For transfers,
address@hidden: pulse} corresponds to an initial pulse, @code{pert: step_resp}
+and @code{pert: step_eff} to initial steps, the difference between
address@hidden (response form)
+and @code{_eff} (effect form) concerns the
+diagonal only of the sensitivity matrix
+(see Feedback gains in non-linear models).
+
+Non initial perturbation can also be asked for:
+
address@hidden
+ Sensy_to_var
+ <
+!* var: eta_courant_L, pert: init at 100;
+!* var: ff_T_czcx, pert: pulse at 100 every 20;
+!* var: ff_Psi_Tczcx, pert: step_eff;
+!* var: ff_Psi_Tczcx, pert: step_Resp at 10 every 100;
+! *** premiers tests identiques a lorhcl.ref
+ var: ff_courant_L , pert: step_eff;
+ var: ff_T_czcx , pert: step_eff;
+ var: ff_Psi_Tczcx , pert: step_eff;
+ var: ff_Psi_Tsz , pert: pulse at 100 every 50;
+ >;
address@hidden example
+
+In this example taken from @file{lorhcl}, a sensitivity can increase so as to
+trespass the Fortran capacity, so that each sensitivity vector (matrix column)
+can be reset at some time-increment @code{at III every JJJ;}
+
+It is noteworthy that these sensitivity analyses are not based
+on difference between two runs with different initial states or
+parameter values, but on the formal derivatives of the model. This method
+is not only numerically robust, but is also rigorously funded as based on
+the TLS of the address@hidden a short introduction to automatic
+sensitivity analysis, see the document:@*
address@hidden://lmd.jussieu.fr/zoom/doc/sensibilite.ps}, in French,
+or ask for the more complete research document to a member of the TEF-ZOOM
+collaboration}.
+
+If the @code{dimetaphi} sequence is built by the users, he should declare
+the number of perturbing variables as @code{nxp=}:
+
address@hidden
+ parameter (nxp=np,nyp=0,nzp=0);
address@hidden example
+here, all state variables are considered as perturbing variables.
+
address@hidden sensitivity, output
address@hidden output, sensitivity
address@hidden @file{sens.data}
address@hidden @file{sigma.data}
+
+The sensitivity vectors are output in the result files @file{sens.data} for
+cells and @file{sigma.data} for transfers. In those files the first column
+corresponds again with time, and the other columns are relative sensitivities
of the cell
+states (in @file{sens.data}) and transfers (in @file{sigma.data})
+with respect to the initial value of the perturbed state.
+
+In our predator-prey example, the second column of @file{sens.data} will
contain
+the derivative of @math{\eta_1(t)} with respect to @math{\eta_1(t=0)}.
+Drawing the
+second column of @file{sens.data} against the first one
+gives the time evolution of the sensitivity of @code{eta-pred}
+to a change in the initial value of @code{eta-pray}. One can check
+in that it is set to 1 at @math{t=0}:
+
address@hidden
+# Sensy_to: eta_pray 3 eta_pred 5
+# time \\ of: eta_pray eta_pred eta_pray eta_pred
+ 0.00000E+00 1.00000E+00 0.00000E+00 0.00000E+00 1.00000E+00
+ 1.00000E-02 9.90868E-01 1.11905E-02 -1.26414E-02 9.98859E-01
address@hidden example
+The two last columns are the state sensitivity to a change in initial
conditions
+of the number of predators.
+
+In the same way, the @var{j+1}th column of @file{sigma.data} will be the
+derivative of @math{\phi_{j}(t)} with respect to @math{\eta_i(t=0)}. Here:
address@hidden
+# Sensy_to: eta_pray eta_pred
+# time \\ of: ff_interact ff_interact
+ 0.00000E+00 1.60683E+00 8.47076E-01
+ 1.00000E-02 1.59980E+00 8.18164E-01
address@hidden example
+
+the unique transfer variable gives rise to two sensitivity columns.
+
+Sensitivity studies are usefull to assess the
+predictability properties of the corresponding system.
+
address@hidden
address@hidden * Initial state sensitivity::
address@hidden * Sensitivity to a pulse or a step on transfer::
address@hidden * Extended Sensitivity studies::
+* Sensitivity to a parameter::
+* Advance matrix sensitivity::
address@hidden menu
+
+
+
address@hidden Sensitivity to a parameter
address@hidden Sensitivity to a parameter
+
+A forward sensitivity to a parameter will be computed when specified as
+described in @ref{Parameters}. For example, suppose that
+the sensitivity to an initial change in the @code{apar} parameter of
+the predator model is of interest.
address@hidden In that case the number of
address@hidden parameters should be set to 1 in @file{dimetaphi}:
address@hidden
address@hidden @example
address@hidden parameter (lp=2);
address@hidden @end example
+
+The sensitivity calculs is turned on as a forward
+parameter specified on the @code{Free_parameter} list:
+
address@hidden
+Free_parameter: [fwd: apar, cpar];
address@hidden example
+
+The result are in @file{sensp.data} for cells and @file{sigmap.data}
+for transfers.
+
address@hidden
+# Sensy_to: pi_prandtl 3 4 pi_rayleigh_ 6
+# time \\ of: eta_courant_ eta_T_czcx eta_T_sz eta_courant_ eta_T
+ 0.00000E+00 0.00000E+00 0.00000E+00 0.00000E+00 0.00000E+00 0.000
+ 2.00000E-03 -4.77172E-03 -3.99170E-05 3.55971E-05 -9.94770E-05 -1.004
address@hidden example
+In the above example from @file{lorhcl} sensitivity of the three states with
respect
+to an initial change in two parameters are independantly given (first line
also numbers
+the column to easy gnuplot using).
+
address@hidden Advance matrix sensitivity
address@hidden Advance matrix sensitivity
+
+
+It is possible to look at the sensitivity of the matrix of advance in
+states space (the matrix @code{aspha}) with regard to a parameter.
+The parameter must be accounted for in the parameter number and be in the
+parameter list, flagged as the matrix @code{mx} parameter, like in
address@hidden
+Free_parameter: [mx: apar], cpar;
address@hidden example
+
address@hidden d_pi_aspha(.,.)
+
+This feature is associated with a selecting flag, @samp{dPi_aspha}. One gets
+the result in the matrix @code{d_pi_aspha(.,.)} of dimension
+(@code{np},@code{np}).
+
+This matrix may be used to compute other quantities, for example
+it may be used to compute the sensitivity of the eigenvalues of
+the state-advance matrix with regard to the @code{[fwd]} parameter.
+These additional computations have to be programmed by the user in
address@hidden with matrices declared and initialized in
address@hidden An example is given in the example @file{lorhcl}
+provided with the Miniker installation files, following a method proposed
+by Stephane Blanco.
+
address@hidden Adjoint model and optimisation
address@hidden Adjoint model and optimisation with Miniker
+
+In the following a possible use of Miniker for optimisation is discussed.
+More precisely the use of adjoint and control laws in Miniker are presented.
+Optimisation isn't the only application of these tools, but it is the most
+common one. In that case the adjoint may be used to determine the gradient of a
+functional to perturbations in the control laws, and an optimisation process
+can use this
+information to search for the optimum.
+Another application of the adjoint is to compute the sensitivity of a
+cost function to parameters (the ones declared in the @code{free_parameters:}'
list.
+Note that the cost function can be sensitive to probe's variables, even if
these are
+uncoupled with standard variables in the forward calculations; this is the case
+when minimizing a quadratic distance function between probes (from the model)
+and the corresponding measurements.
+
+The code is close transcription of the mathematical calculus described
address@hidden @url{http://www.lmd.jussieu.fr/ZOOM/doc/Adjoint.pdf} . It
essentialy reverse time and
+transpose the four Jacobian matrices: states and transfers are saved in array
dimensionned
+with @code{maxstep} Fortran parameter.
address@hidden
+* Overview of optimisation with Miniker::
+* Control laws::
+* Cost function coding and adjoint modeling::
+* Sensitivity of cost function to parameters::
address@hidden menu
+
address@hidden Overview of optimisation with Miniker
address@hidden Overview of optimisation with Miniker
+
address@hidden adjoint
address@hidden optimisation
+
+In the proposed method, Miniker is run twice, one time forward and then
+backward to determine the trajectory and the adjoint model. After that the
+control laws are modified by a program external to Miniker. The same steps
+are repeated until convergence. More pecisely,
+
address@hidden @strong
address@hidden forward
+The command law @math{h(t)} is given (by an explicit law or taken from a file).
+The trajectory is computed in a classical way, with the additionnal computation
+of the functional to be optimised, @math{J}, prescribed with specific
address@hidden macros. The states, transfers and control laws are stored.
address@hidden backward
+The adjoint variable is computed from the last time @math{T} backward. The
+time increment is re-read as it could have changed during the forward
+simulation. The system is solved by using the same technics as in the forward
+simulation, but with a negative time step.
address@hidden external phase
+Now the command should be corrected. This step isn't covered here, but, for
+example, minuit the optimisation tool from the CERN could be used.
+In order to ease such a use of Miniker, the principal program has to be
+compiled as a subroutine to be driven by an external program
+(@pxref{Calling the model code}).
address@hidden table
+
+The functionnal @math{J} to be optimised is defined as
+
address@hidden
+$$
+J = \psi[\eta(T),\varphi(T) ,h(T)] + \int_0 ^T
{l[\eta(\tau),\varphi(\tau),h(\tau)]}\, d\tau
+$$
address@hidden tex
address@hidden @math{J = psi(eta(T),phi(T),h(T)) + int_0^T
l(eta(tau),phi(tau),h(tau)) d tau}
+
address@hidden final cost
address@hidden integrand cost
+
+Where @math{\psi} is the final cost function, @math{l} is the integrand
+cost function and @math{h} represents the control laws variations.
+
+The general use of the adjoint model of a system is the determination of the
+gradient of this @math{J} functional to be optimised, with respect to
perturbations
+of the original conditions of the reference trajectory, that is, along its
address@hidden Tangent Linear System, i.e. the TLS circulating along a
trajectory.
+See the explanation in the document
address@hidden://www.lmd.jussieu.fr/Zoom/doc/Adjoint.pdf} (in French).}.
+
address@hidden Control laws
address@hidden Control laws
+
address@hidden zcommand
address@hidden command law
+
+Each control law is associated with one cell or transfer equation, meaning
that a command
+associated with an equation does not appear in any other equation.
+It is still possible
+to add commands acting anywhere by defining a transfer equal to that command.
+
+
+The control laws associated with states are in the @code{ux_com(.)} array,
+control laws associated with transfers are in the @code{uy_com(.)} array.
+The control laws may be prescribed even when there is no adjoint computed,
+nor any optimisation, and they are used during simulation, in which case they
will
+act as external sources. To enable
+the use of commands, the logical flag @code{Zcommand} should be @code{.true.}.
+
address@hidden @file{uxcom.data}
address@hidden @file{uycom.data}
+
+The command can be given either as:
address@hidden
address@hidden a table of numerical
+values in the files @file{uxcom.data} and @file{uycom.data}.
address@hidden a function
address@hidden zlaw
address@hidden @file{zcmd_law}
address@hidden @file{zcmd_law.inc}
+of the problem variables. To turn that feature on the logical flag
address@hidden should be set to @code{.true.} in @file{zinit}. The sequence
address@hidden should hold
+the code filling the @code{ux_com(.)} and @code{uy_com(.)} arrays, as the code
+from that sequence is used whenever the control laws are needed.
+In that case the files @file{uxcom.data} and @file{uycom.data} will
+be filled by the command values generated by the function along the trajectory.
address@hidden enumerate
+
+For example in the Lotka-Volterra model, the parameter @code{apar} could
+be a control variable.
+In that case, @code{apar} would be defined as the variable @code{ux_com(1)},
+and either entered as a law
+in the sequence @file{zcmd_law} , either written in the file @file{uxcom.data}
+step by step. In that case, there must be a perfect corresponodence between
time
+of the commands and time of the run.
+
address@hidden Cost function coding and adjoint modeling
address@hidden Cost function coding and adjoint modeling
+
address@hidden zback
address@hidden cout_Psi
address@hidden cout_l
+
+First of all the flag @code{zback} should be set to @code{.true.} in order to
+allow adjoint model computation:
+
address@hidden
+Zback=.true.;
address@hidden example
+
+The two functions @code{cout_Psi} corresponding with the final cost and
address@hidden corresponding with the integrand cost are set up with the
address@hidden macros.
+
address@hidden f_set cout_Psi = f(eta(.),ff(.),ux_com(.),uy_com(.))
+This macro defines the final cost function.
address@hidden is a fortran
+expression which may be function of cell state variables,
address@hidden(1)address@hidden@samp{eta(np)}, transfers
address@hidden(1)address@hidden@samp{ff(mp)},
+state control laws
address@hidden(1)address@hidden@samp{ux_com(np)}, and transfer control laws
address@hidden(1)address@hidden@samp{uy_com(mp)}.
address@hidden defmac
+
address@hidden f_set cout_l = f(eta(.),ff(.),ux_com(.),uy_com(.))
+This macro defines the integrand cost function.
address@hidden is a fortran
+expression which may be function of cell state variables,
address@hidden(1)address@hidden@samp{eta(np)}, transfers
address@hidden(1)address@hidden@samp{ff(mp)},
+state control laws
address@hidden(1)address@hidden@samp{ux_com(np)}, and transfer control laws
address@hidden(1)address@hidden@samp{uy_com(mp)}.
address@hidden defmac
+
+For example, the following code sets a cost function for the masselottes
+model:
+
address@hidden
+! Initialisation
+ F_set cout_Psi = eta_move(inode:1);
+!and f_set cout_l integrand in the functionnal
+ F_set cout_l = 0.;
address@hidden example
+
+In that example the functional is reduced to the final value
+of the first state component.
+Here, the adjoint vector will correspond to the final sensitivity
+(at @math{t=0}) of
+that component (here the first masselotte position) to a perturbation in
+all initial address@hidden detailed explanation of the adjoint model,
+see the document in
address@hidden://www.lmd.jussieu.fr/@/ZOOM/doc/Adjoint.pdf,pdf}
+or @uref{http://www.lmd.jussieu.fr/@/ZOOM/doc/Adjoint.pdf,.ps.gz}}.
+
address@hidden In the code, the variables @code{v_adj(.)} and @code{w_adj(.)}
address@hidden are respectively adjoint to @code{eta(.)} and @code{ff(.)}. They
are written in the
address@hidden two files: @file{vadj.data} and @file{wadj.data}.
+The following variables are set during the backward phase, and output
+in the associated files:
+
+
address@hidden address@hidden(.)}} address@hidden {time increment, hamiltonian,
cost function increment}
address@hidden var @tab file @tab explanation
address@hidden @item @code{} @tab @file{.data} @tab @tab
address@hidden @code{v_adj(.)} @tab @file{vadj.data} @tab adjoint to
@code{eta(.)}
address@hidden @code{w_adj(.)} @tab @file{wadj.data} @tab adjoint to
@code{ff(.)}
address@hidden @code{wadj(mp+.)} @tab @file{gradmuj.data} @tab adjoint to
@code{ff(mp+.)}
address@hidden @code{graduej(.)} @tab @file{gradxj.data} @tab adjoint to
@code{ux_com(.)}
address@hidden @code{gradufj(.)} @tab @file{gradyj.data} @tab adjoint to
@code{uy_com(.)}
address@hidden @code{hamilton} @tab @file{hamilton.data} @tab time increment,
hamiltonian, cost function increment
address@hidden multitable
+
address@hidden Sensitivity of cost function to parameters
address@hidden Sensitivity of cost function to parameters
+
address@hidden @file{gradpj.data}
+
+The sensitivity of the cost function to all the parameters given as
+arguments of @code{Free_parameters} is computed. For the
+predator model the sensitivity of a cost function consisting in
+the integral of the predator population with respect with
address@hidden an @code{cpar} is obtained with a number of parameters
+set to 2 in @file{dimetaphi}:
+
address@hidden
+parameter (lp=2);
address@hidden example
+
+And the cost function and @code{Free_parameters} list in @file{zinit}:
+
address@hidden
+f_set cout_Psi = eta(2);
+f_set cout_l = eta(2);
+Free_parameters: apar,cpar;
address@hidden example
+
address@hidden and @code{cpar} also have to be given a value.
+The result is output in @file{gradpj.data}.
+
address@hidden Kalman filter
address@hidden Kalman filter
+
address@hidden Kalman filter
address@hidden variance-covariance matrices, general
address@hidden observations, general
+
+The Kalman filter allows for data assimilation along the model run. In
+that case it is assumed that there is a real-world model with stochastic
+perturbations on the states, and that noisy observations are available.
+The situation implemented in Miniker corresponds to a continuous
+stochastic perturbation on the state, and discrete noisy observations.
+In the @acronym{TEF} this leads to:
+
address@hidden
+$$\eqalign{
+\partial_t \eta (t) &= g(\eta(t),\varphi(t)) + W(t) \mu\cr
+\varphi(t) &= f(\eta(t),\varphi(t))\cr
+\omega(t) &= h ( \eta(t) , \varphi(t)) + \nu\cr
+}$$
address@hidden tex
+
address@hidden @math{d eta(t)/d t = g(eta(t),phi(t)) + W(t) address@hidden
+phi(i) = f(eta(t),phi(t))@*
+omega(t) = h(eta(t), phi(t)) + nu }
+
+
address@hidden FIXME partout omega
address@hidden (notice that in this paragraph, $\omega$ stands for the probe
vector $\mu$ elsewhere,
address@hidden and $\mu$ is here a noise source.
+
+The observations @math{\omega} are available at discrete time steps
@math{t=s_i}. The
+stochastic perturbation on state, @math{\mu} is characterized by a
+variance-covariance matrix @math{Q} and the noise on the observation,
address@hidden has a variance-covariance matrix @math{R}. @math{W} relates
states
+with stochastic perturbations. At each time step the Kalman filter recomputes
+an estimation of the state and the variance-covariance matrix of the state.
+
+In the following we use the example of a linear model with perturbation
+on state and observation of state. The model has 3 states and 3 corresponding
+transfers (equal to the states), but the error on the state is of dimension
+2. The 3 states are observed. The corresponding equations read:
+
address@hidden
+$$\left\{\eqalign{
+\partial_t \eta_1 &= a_{11} \eta_1 + a_{12} \varphi_2 + a_{13} \varphi_3 +
W_{11} \mu_1 + W_{12} \mu_2\cr
+\partial_t \eta_2 &= a_{21} \varphi_1 + a_{22} \eta_2 + a_{23} \varphi_3 +
W_{21} \mu_1 + W_{22} \mu_2\cr
+\partial_t \eta_3 &= a_{31} \varphi_1 + a_{32} \varphi_2 + a_{33} \eta_3 +
W_{31} \mu_1 + W_{32} \mu_2
+}\right.$$
+$$\left\{\eqalign{
+\varphi _1 &= \eta _1\cr
+\varphi _2 &= \eta _2\cr
+\varphi _3 &= \eta _3
+}\right.$$
+$$\left\{\eqalign{
+\omega _1 &= \varphi _1 + \nu_1\cr
+\omega _2 &= \eta _2 + \nu_2 \cr
+\omega _3 &= \eta _3 + \nu_3
+}\right.$$
address@hidden tex
+
+
+Cells:@*
address@hidden @math{d eta_1/dt = a_11 eta_1 + a_12 phi_2 + a_13 phi_3 + W_11
mu_1 + W_12 address@hidden
+d eta_2/dt = a_21 phi_1 + a_22 eta_2 + a_23 phi_3 + W_21 mu_1 + W_22
address@hidden
+d eta_3/dt = a_31 phi_1 + a_32 phi_2 + a_33 eta_3 + W_31 mu_1 + W_32 mu_2}
+
+Transfers:@*
address@hidden @math{phi_1 = address@hidden
+phi_2 = address@hidden
+phi_3 = eta_3}
+
+Observations:@*
address@hidden @math{omega_1 = phi_1 + address@hidden
+omega_2 = eta_2 + address@hidden
+omega_3 = eta_3 + nu_3}
+
+
address@hidden
+* Coding the Kalman filter::
+* Kalman filter run and output::
+* Executing code after the analysis::
address@hidden menu
+
address@hidden Coding the Kalman filter
address@hidden Coding the Kalman filter
+
address@hidden zkalman
+
+First of all the Kalman filter code should be activated. The observations
+code is also required (@pxref{Observations}).
+If cmz is used the code
+should be selected with the select flag kalman
+in the @file{selseq.kumac}:
+
address@hidden
+sel kalman
address@hidden example
+
+With make the @code{kalman} variable should be set to 1:
+
address@hidden
+kalman = 1
address@hidden example
+
+The kalman code is actually used by setting the flag
address@hidden to @code{.true.}, for example in the @file{zinit}:
+
address@hidden
+zkalman = .True.;
address@hidden example
+
address@hidden This will set the @code{zobs} and @code{zdata} flags to
@code{.true.}
address@hidden (@pxref{Observations and data}).
+
+With the Kalman filter the dimension of estimated states, of the error
+on the state and of the
+observation, the @math{W} matrix, the observation function,
+the initial
+variance-covariance matrices on the state and the variance-covariance matrices
+of errors have to be given.
+
address@hidden
+* Kalman filter vectors dimensions::
+* Error and observation matrices::
address@hidden menu
+
address@hidden Kalman filter vectors dimensions
address@hidden Kalman filter vectors dimensions
+
address@hidden error vector dimension
address@hidden @file{dimetaphi}, Kalman filter
+
+These dimensions should be set in the @file{zinit} sequence.
+The size of the estimated states is given by the parameter @code{nkp}.
+You can set this to @code{np} if all the states are estimated, but in case
+there are some deterministic state variables, @code{nkp} may be less than
address@hidden In that case the first @code{nkp} elements of @code{eta(.)}
+will be estimated using the Kalman filter.
+
+The error on state dimension is associated with the parameter @code{nerrp}
+and the size of the observations vector is @code{mobs}
+(@pxref{Observations}). In our example the dimensions are set with:
+
address@hidden
+parameter (nkp=np);
+parameter (mobs=3);
+parameter (nerrp=2);
address@hidden example
+
+All the states are estimated,
+there are 3 observation functions and the error on the state vector is of
+dimension 2.
+
+If the sizes are set explicitely, the parameters should be set in
address@hidden
+
address@hidden Error and observation matrices
address@hidden Error and observation matrices
+
address@hidden variance-covariance matrices
address@hidden observations
address@hidden @file{zinit}, Kalman filter
+
address@hidden Initial variance-covariance matrix on the state
+
address@hidden initial variance-covariance on states
address@hidden covfor(.,.)
+
+The variance-covariance on the state matrix is @code{covfor(.,.)}. The initial
+values have to be given for this matrix, as in our example:
+
address@hidden
+covfor(1,1) = 1000.; covfor(1,2) = 10.; covfor(1,3) = 10.;
+covfor(2,1) = 10.; covfor(2,2) = 5000.; covfor(2,3) = 5.;
+covfor(3,1) = 10.; covfor(3,2) = 5.; covfor(3,3) = 2000.;
address@hidden example
+
+This matrix is updated by the filter at each time step because the states
+are pertubated by some noise, and when assimilation takes place as new
+information reduce the error.
+
address@hidden Observations and error on state matrix
+
address@hidden variance-covariance matrix on state
address@hidden mereta(.,.)
+
+The matrix that relates errors on states vector components to states,
+corresponding with @math{W} is @code{mereta(.,.)}. In our example it is
+set by:
+
address@hidden
+mereta(1,1) = 1.; mereta(1,2) = 0.;
+mereta(2,1) = 0.; mereta(2,2) = 1.;
+mereta(3,1) = 0.5; mereta(3,2) = 0.5;
address@hidden example
+
+The observation functions are set by a @code{f_set} macro with
address@hidden(.)} as described in @ref{Observations}.
+In our example the observation functions are set by:
+
address@hidden
+f_set Obs_tef(1) = ff(1) ;
+f_set Obs_tef(2) = eta(2);
+f_set Obs_tef(3) = eta(3);
address@hidden example
+
address@hidden Error variance-covariance matrices
+
address@hidden variance-covariance error
address@hidden covobs(.,.)
+
+The variance-covariance matrix on observation noise is @code{covobs(.,.)}
+set, in our example, by:
+
address@hidden
+covobs(1,1) = 0.3; covobs(1,2) = 0.; covobs(1,3) = 0.;
+covobs(2,1) = 0.; covobs(2,2) = 0.1; covobs(2,3) = 0.;
+covobs(3,1) = 0.; covobs(3,2) = 0.; covobs(3,3) = 0.2;
address@hidden example
+
address@hidden coveta(.,.)
+The variance-covariance matrix on state noise is @code{coveta(.,.)}
+set, in our example, by:
+
address@hidden
+coveta(1,1) = 0.2; coveta(1,2) = 0.001;
+coveta(2,1) = 0.001; coveta(2,2) = 0.1;
address@hidden example
+
+These matrices are not changed during the run of the model as part
+of the filtering process. They may be changed by the user in @file{zsteer}.
+
address@hidden Kalman filter run and output
address@hidden Kalman filter run and output
+
address@hidden
+* Feeding the observations::
+* Kalman filter results::
address@hidden menu
+
address@hidden Feeding the observations
address@hidden Feeding the observations to the model
+
address@hidden vobs(.)
address@hidden zgetobs
address@hidden @file{zsteer}, Kalman filter
+
+The observations must be made available to the model during the run. These
+observations are set in the @code{vobs(.)} array, and the assimilation
+(also called the analysis step of the filter) takes
+place if the logical variable @code{zgetobs} is @code{.true.}
+(@pxref{Data}).
+
+These steps are
+typically performed in the @file{zsteer} sequence. In this sequence there
should
+be some code such that when there are data ready to
+be assimilated, @code{zgetobs} is set to @code{.true.} and the data is
+stored in @code{vobs(.)}, ready for the next step processing.
+
address@hidden Kalman filter results
address@hidden Kalman filter results
+
address@hidden results, Kalman filter
address@hidden Kalman filter results
address@hidden output, Kalman filter
address@hidden Kalman filter output
address@hidden @file{data.data}
+
+The estimated states and transfers are still in the same @samp{.data} files,
address@hidden and @file{tr.data} and there is the additional file with
+observations, called @file{obs.data} (@pxref{Observations}).
+Each time @code{zgetobs} is @code{.true.} the data, and the optimally
+weighted innovations are output
+in the file associated with data, @file{data.data} (@pxref{Data}).
+
address@hidden Executing code after the analysis
address@hidden Executing code after the analysis
+
+The analysis takes place before the time step advance when @code{zgetobs}
+is @code{.true.}. It may be usefull to add some code after the analysis
+and before the time step advance. For example the analysis may lead to
+absurd values for some states or parameters, it could be usefull to correct
+them in that case. The sequence included after the analysis is called
address@hidden At this point, in addition to the usual variables
+the following variables could be usefull:
+
address@hidden @code
address@hidden etafor(.)
+The state before the analysis.
address@hidden kgain(.)
+The Kalman gain.
address@hidden innobs(.)
+The innovation vector (observations coherent with the states minus data
+values).
address@hidden covana(.,.)
+The variance-covariance error matrix after the analysis.
address@hidden vtable
+
+At each time step the derivative of the observation function with respect
+to transfer and cells variables are recomputed. The elimination of
+transfers is also performed to get the partial derivative of the observation
+function of the equivalent model, with states only, with respect to the
+states. In other words, the Kalman filter does not follow the TEF formalism,
because
+the advance of the var-covar matrix could not yet be set in the TEF form.
address@hidden There is a corresponding additional matrix:
+
address@hidden @code
address@hidden @item obetad(.,.)
address@hidden derivative of observation function with respect to transfers.
address@hidden @item obphid(.,.)
address@hidden derivative of observation function with respect to cell
variables.
address@hidden obspha(.,.)
+derivative of observation function in state space with respect to
+cell variables.
address@hidden vtable
+
+
address@hidden Feedback gain
address@hidden Feedback gain
+
+
address@hidden Borel sweep
address@hidden Feedback gain
+
+The feedback dynamic gain associated with a feedback loop
+can be expressed as the inverse Borel
+transform of the coefficient of the reduced scalar
+coupling matrix, @math{g(\tau)},
+associated with a transfer.
+A Borel sweep provides this @math{g(\tau)}. Therefore it is
+an interesting tool for the characterization of the feedback address@hidden
+More generally, the Borel sweep allows
+the numerical study of the dependency in @math{\tau} of the Borel transform
+of various coefficients in the system coupling matrix.}.
+
+As explained in the
+ZOOM web page document
address@hidden://www.lmd.jussieu.fr/@/ZOOM/doc/@/Feedback_Gain.pdf},
+this allows for the calculation of the
+dynamic gain and factor of any feedback that goes through a unique
+transfer variable. An example of the conclusions that can be drawn from such
+an analysis is provided in the same document.
+
+
+
+For linear systems -- whose GTLS are autonomous along the whole trajectory --
+the @math{\tau} function of the
+feedback gain is independent of the position on the system trajectory.
+But in general it is dependant, and one can analyse the function
address@hidden(\tau;t)} defined on a segment @math{t} of the trajectory.
+
+The document introducing the TEF-ZOOM technique explains how a Crank-Nicolson
+scheme for the time discretisation
+symbolically gives the solution of the Borel transform of the system. One can
+identify the @code{dt} variable with the Borel @math{\tau} within a
+factor @math{2}. Hence, to numerically study the @math{\tau} dependency of
+the transform of various coefficients in the system coupling matrix at one
+point in time, one can calculate the Borel transform of the TLS solutions
+by making a time-step sweep.
+
+The function @math{g(\tau;t)} is simply output for the feedback gain
+attached to a unique @code{ff(k)} transfer variable.
+All the relevant informations should be entered in the @file{zinit} sequence.
+
address@hidden
+* Specifying the Borel sweep::
+* Borel sweep results::
address@hidden menu
+
address@hidden Specifying the Borel sweep
address@hidden Specifying the Borel sweep
+
address@hidden ZBorel
+
+First of all the logical flag @code{ZBorel} should be raised:
+
address@hidden
+ZBorel=.true.;
address@hidden example
+
address@hidden index_ff_gain
+The index of the studied transfer is given in the @code{index_ff_gain}
+variable
address@hidden
+index_ff_gain=7;
address@hidden example
+
+At each time step a Borel sweep may be performed. The time steps of interest
+are
+specified with three variables, one for the first step, one for the last step
+and one for the number of steps between two Borel sweeps:
+
address@hidden @code
address@hidden istep_B_deb
+First time step for the Borel sweep.
address@hidden istep_B_fin
+Last time step for the Borel sweep.
address@hidden istep_B_inc
+Number of time steps between Borel sweeps.
address@hidden vtable
+
+In the following examples Borel sweeps are performed from the
+time step 1000 up to the time step 1200, with a sweep at each time step:
address@hidden
+istep_B_deb=1000;
+istep_B_fin=1200;
+istep_B_inc=1;
address@hidden example
+
+
+For each Borel sweep, the range of the @math{\tau} variable should be
+set. As this is a multiplicative variable the initial value, a multiplicative
+factor and the number of values are to be given.
+
address@hidden @code
address@hidden tau_B_ini
+Initial value for @math{\tau}.
address@hidden tau_B_mult
+Multiplicative factor for sweep in @math{tau}.
address@hidden itau_max
+Number of @math{\tau} values.
address@hidden vtable
+
+For example, in the following, at each time step, the Borel
+transform will be computed for @math{\tau} values
+starting at @math{0.2} and then multiplied a hundred times by
@math{\sqrt{\sqrt{2}}}
+
address@hidden
+tau_B_ini=0.2;
+tau_B_mult=sqrt(sqrt(2.));
+itau_max=100;
address@hidden example
+
+When the initial value of @math{\tau} is set to a negative value
+(@i{i.e.} @code{tau_B_ini=-0.2;}),
+the Borel sweep will first be applied with @code{itau_max} negative values
+for @code{-0.2}, @code{tau_B_mult*(-0.2)},..., then for the zero value,
+and finally for the symetric positive values, resulting in @code{2*itau_max+1}
+values for @math{\tau}.
+
+The whole example reads
+
address@hidden
+! -------------------
+! Feedback gain
+! Borel
+! -------------------
+ZBorel=.true.;
+if ZBorel
+< istep_B_deb=1000;
+ istep_B_fin=1200;
+ istep_B_inc=1;
+;
+ index_ff_gain=7;
+ tau_B_ini=0.2;
+ tau_B_mult=sqrt(sqrt(2.));
+ itau_max=100;
+ z_pr/Borel/:tau_B_mult,tau_B_ini*(tau_B_mult)**itau_max;
+>;
address@hidden example
+
address@hidden zborel for
+
+Instead of using the index of the transfer in @code{index_ff_gain} it is
+possible to specify the name of the address@hidden , whenever
address@hidden the symbolic model description is used (@pxref{Symbolic model
description}).
+In that case the transfer is specified
+by the @code{zborel for} macro. For example if the transfer selected for the
+feedback gain computation is @var{b_transfer}, it can be selected
+with:
+
address@hidden
+zborel for: @var{b_transfer};
address@hidden example
+
address@hidden Borel sweep results
address@hidden Borel sweep results
+
address@hidden Borel sweep results
address@hidden results, Borel sweep
address@hidden Borel sweep graphics
address@hidden graphics, Borel sweep
+
+The file @file{tau_Borel.data} gives the @math{\tau} values of the @var{tau}
sweep,
+and the file @file{gains.data} records the feedback gain function values of
address@hidden(\tau)}, with
+one line for each sweep along the trajectory. In the 1.01 version, a new
+feature is also provided giving the poles and residuals of the Borel
+transform in the file @file{vpgains.data}. Consult the subroutine
address@hidden
+for (not definitive) output description.
+
+One can easily obtain the surface contours of @math{g(t,\tau)} using
+the Fortran program provided as @file{gains.f} and its compilation shell
address@hidden,
+that builds 2D histograms for PAW, in which one uses the
address@hidden provided kumac.
+
address@hidden Stability of fastest modes
address@hidden Stability analysis of fastest modes
+
address@hidden SVD
address@hidden Singular Value Decomposition
address@hidden state matrix
address@hidden @file{sltc.exe}
+
+The preceding analyses are done along with a simulation. One has also the
+possibility of using in a more classical fashion the state advance matrix
address@hidden, after the end of the simulation. Code to perform the
address@hidden, Singular Value Decomposition} of the state matrix @math{A_{st}}
+and also of @math{A_{st} + A_{st}^\dagger} is provided with Miniker.
+The singular elements of these two matrices correspond to the most
+rapid modes of instability of the perturbed system.
+
+The Singular value decomposition of a matrix is noted
+
address@hidden
+$$
+ U w V^\dagger
+$$
address@hidden tex
+
address@hidden @math{U w V^t}
+
+
+An executable file, @file{sltc.exe} is generated and running this file will
+produce the corresponding results.
+
address@hidden
+* SVD with cmz::
+* SVD with make::
+* SVD run and output::
address@hidden menu
+
address@hidden SVD with cmz
address@hidden Singular Value Decomposition with cmz
+
address@hidden @command{smod}
+
+The cmz macro @code{smod SLTC} prepares a main program
+(@file{circul} of +PATCH SLTC), provided as a base for user's own analysis,
+in the directory @file{sltc/}.
+
address@hidden SVD with make
address@hidden Singular Value Decomposition with make
+
address@hidden @file{Makefile.sltc}
+
+To compile the singular value decomposition executable with @command{make} you
+can do
address@hidden
+make sltc.exe
address@hidden example
+
+If you want to have a separate directory for the SVD, you should copy
+the sequence @file{dimetaphi.inc} (or make a link to that file) to the
+directory. You should also copy the file @file{Makefile.sltc} from the
address@hidden/} directory in this directory, rename it @file{Makefile}
+and set the Miniker directory path in the
address@hidden variable. For
+example, if the Miniker directory is in @file{/u/src/mini_ker}:
+
address@hidden
+miniker_dir = /u/src/mini_ker
address@hidden example
+
address@hidden SVD run and output
address@hidden Singular Value Decomposition run and output
+
address@hidden SVD run
address@hidden run, SVD
address@hidden SVD output
address@hidden output, SVD
address@hidden @file{sltc.exe}
address@hidden @file{title.tex}, SVD
address@hidden @file{aspha.data}, SVD
+
+As it is, the @file{sltc.exe} executable generated by the compilation
+determines the SVD. This program requires @file{title.tex} (@pxref{Title
file}) to
+transmit a title for output and graphics, and @file{aspha.data}
+(@pxref{Simulation and output,,Running a simulation and using the output})
+to access the
+state matrix. To get access to these files (in case they are not in the current
+directory) it is possible to make a link to
+the corresponding files in the model directory. Once it is done
+the program may be run:
+
address@hidden
+./sltc.exe
address@hidden example
+
+The files @file{u.data}, @file{w.data}, and @file{v.data} holds the singular
elements
+for @math{A_{st}} (@math{U}, @math{w} and @math{V}),
+and @file{us.data}, @file{ws.data}, and @file{vs.data}
+holds the singular elements of @math{A_{st} + A_{st}^\dagger}.
+The corresponding macros @samp{.kumac} for address@hidden in
+the research paper about SLTC (Al1 2003) available on request.}
+are also generated.
+
address@hidden Generalized TLS
address@hidden Generalized linear tangent system analysis
+
address@hidden Generalized linear tangent system
address@hidden GTLS
address@hidden propagator
address@hidden Lyapunov exponents
address@hidden @file{sltcirc.exe}
+
+The state matrix @math{A_{st}} may also be used to compute the
+GTLS propagator (or state transition matrix applied to perturbation), after
the simulation.
+The algorithm is a finite product of
+5th order development of
address@hidden(t+\delta t,t)=\exp{A_{st} \delta t}}.
+Numerous element of analysis are given, in particular the determination
+of the Lyapunov exponents of the system.
+
+An executable file, @file{sltcirc.exe} is generated and running this file will
+produce the corresponding results.
+
address@hidden
+* GTLS with cmz::
+* GTLS with make::
+* GTLS run and output::
address@hidden menu
+
address@hidden GTLS with cmz
address@hidden Generalized tangent linear system with cmz
+
address@hidden @command{smod}
+
+The cmz macro @code{smod SLTCIRC} prepares a main program
+(@file{circule} of +PATCH SLTCIRC), in the directory @file{sltcirc/}.
+
address@hidden GTLS with make
address@hidden Generalized tangent linear system with make
+
address@hidden @file{Makefile.sltcirc}
+
+To compile the GTLS analysis executable with @command{make} you
+can do
address@hidden
+make sltcirc.exe
address@hidden example
+
+If you want to have a separate directory for the GTLS analysis, you should
copy
+the sequence @file{dimetaphi.inc} (or make a link to that file) to the
+directory. You should also copy the file @file{Makefile.sltcirc} from the
address@hidden/} directory in this directory and rename it @file{Makefile}
+and set the Miniker directory path in the @code{miniker_dir} variable.
+
address@hidden GTLS run and output
address@hidden Generalized tangent linear system analysis run and output
+
address@hidden GTLS run
address@hidden run, GTLS
address@hidden GTLS output
address@hidden output, GTLS
address@hidden @file{sltcirc.exe}
address@hidden @file{title.tex}, GTLS
address@hidden @file{dres.data}, GTLS
address@hidden @file{aspha.data}, GTLS
+
+The @file{sltcirc.exe} executable generated by the compilation
+computes the elements of analysis of the system. This program requires
address@hidden to
+transmit a title for output and graphics (@pxref{Title file}),
address@hidden to access the
+state matrix and @file{dres.data}, because time-step can be changed along the
+simulation
+(@pxref{Simulation and output,,Running a simulation and using the output})
address@hidden our research texts about propagator analyses in
+SLTC, and ``les Gains sur champs (Al1 2003-2004)''}. To get access to these
files
+(in case they are not in the current
+directory) it is possible to make a link to
+the corresponding files in the model directory. Once it is done
+the program may be run:
+
address@hidden
+./sltcirc.exe
address@hidden example
+
+The following table gives the correspondence between variable name,
+result file and ntuple number, with a short explanation:
+
address@hidden address@hidden(.,.)}} address@hidden {ntuple} {eigen factors of
@math{w} in the SVD of @math{\Phi}}
address@hidden var @tab file @tab ntuple @tab explanation
address@hidden @code{p(.,.)} @tab @file{phit.data} @tab 55 @tab propagator from
0 to @math{t}, @math{\Phi(t,0)}
address@hidden @code{up(.,.)} @tab @file{uphit.data} @tab 50 @tab Left singular
vectors @math{U} in the SVD of @math{\Phi}
address@hidden @code{wp(.)} @tab @file{wphit.data} @tab 51 @tab singulat values
@math{w} in the SVD of @math{\Phi}
address@hidden @code{vp(.,.)} @tab @file{vphit.data} @tab 52 @tab Right
Singular Vectors @math{V} in the SVD of @math{\Phi}
address@hidden @code{wr(.)} @tab @file{wr.data} @tab 53 @tab real part of
eigen values of @math{\Phi(t,0)}
address@hidden @code{wi(.)} @tab @file{wi.data} @tab 54 @tab imaginary part of
eigen values of @math{\Phi(t,0)}
address@hidden @code{lwp(.)} @tab @file{lwphit.data} @tab 67 @tab Lyapunov
exponents
address@hidden @item @code{lwr(.,.)} @tab @file{lwr.data} @tab 68 @tab
address@hidden @item @code{lwi(.,.)} @tab @file{lwi.data} @tab 69 @tab
address@hidden @item @code{} @tab @file{.data} @tab @tab
address@hidden multitable
+
+
address@hidden Advanced use of Miniker with make
address@hidden Advanced use of Miniker with make
+
address@hidden
+* Make variables::
+* Rules::
+* Linking rule::
address@hidden menu
+
address@hidden Make variables
address@hidden Make variables
+
address@hidden @file{Makefile.miniker}
+
+The @file{Makefile.miniker} Makefile provided in the
+distribution should be included as it defines a lot of important
+variables and rules.
+
+The following make variables can be set by the user:
+
address@hidden @code
address@hidden miniker_dir
+that variable should hold the Miniker sources directory. If you installed
+Miniker that variable should be set to @file{$(includedir)/mini_ker}.
+If you use the sources right from the sources directory it should be set to
+the sources package directory.
address@hidden MTNDIRS
+This variable can hold a @samp{:} delimited list of directories that will
+be searched for mortran include files.
address@hidden CMFDIRS
+This variable can hold a @samp{:} delimited list of directories that will
+be searched for cmz directive include files.
address@hidden SEL
+This variable holds a @samp{,} delimited list of select flags, for example
address@hidden, @code{grid1d}, @code{debug}.
address@hidden LDADD
+This variable can be used to add libraries flags and files. It is used in
+the default linking command/rule.
address@hidden miniker_user_objects
+This variable should hold a space separated list of additional object files
+to be linked with the model and helper object files.
address@hidden CAR2TXTFLAGS
+cmz directives preprocessor flag.
address@hidden kalman
+This variable should be set to 1 if you want to use the kalman filter
+(@pxref{Kalman filter}).
address@hidden double
+This variable should be set to 1 if you want to have a double precision
+code (@pxref{Double precision}).
address@hidden table
+
+The following variables are allready set and may be used
+(some are set by ./configure see @ref{Configuration}):
+
address@hidden @code
address@hidden miniker_principal_objects
+The list of object files needed for the model build, together with some
+helper object files often used but not strictly required for the linking.
address@hidden DEPDIR
+The name of a hidden directory containing the dependencies computed
+for the main mortran files.
address@hidden F77
address@hidden FC
address@hidden FFLAGS
address@hidden LDFLAGS
+Compiler and linker related variables set by ./configure.
address@hidden LIBS
+This variable should hold the link flags and files required to build
+Miniker, set by ./configure.
address@hidden CAR2TXT
address@hidden MORTRAN
address@hidden MTNFLAGS
address@hidden MTNDEPEND
+Preprocessor and preprocessor flags, set by ./configure.
address@hidden table
+
address@hidden Rules
address@hidden Rules
+
+The following rules are defined in the @file{Makefile.miniker} file.
address@hidden @code
address@hidden miniker-clean
+remove the fortran files generated from the mortran files. Remove
+the object files.
address@hidden miniker-mtn-clean
+remove the mortran files generated from the files with cmz directives.
address@hidden
+Various rules to preprocess files with cmz directives and mortran files and
+to compile fortran files.
address@hidden table
+
+If the user needs a mortran main file, he may take advantage of the rule
+used to compute the dependencies of a mortran file. If the file is called,
+say, @file{mtnfile.mtn} leading to @file{mtnfile.f}, the following include
+should lead to the automatic creation, updating and inclusion of a
+file describing the dependencies of @file{mtnfile.mtn} in the
address@hidden:
+
address@hidden
+include $(DEPDIR)/mtnfile.Pf
address@hidden example
+
address@hidden Linking rule
address@hidden Linking rule
+
+The rule used for the linking of the model file is not in the
address@hidden file but
+should be provided in the user @file{Makefile} for more flexibility.
+The default rule
+uses the variables @code{miniker_user_objects} for additional object files
+and @code{LDADD} for additionnal linking flags and files, those
+variables are there to be changed by the user.
+
+The object files required by the Miniker code are in the make variable
address@hidden, this variable is also used.
+The value of the variables @code{FC}
+for the Fortran compiler, @code{FFLAGS} for the Fortran compiler
+flags and @code{LDFLAGS} for the linker flags should be set to right
+values; @code{LIBS} should also be right and hold the link flags and link
+files required to compile the Miniker model. These variables are
+set by by @command{./configure} during configuration (@pxref{Configuration})
+and used in the default rule:
+
address@hidden
+$(model_file): $(miniker_user_objects) $(miniker_principal_objects)
+ $(FC) $(FFLAGS) $(LDFLAGS) $^ $(LDADD) $(LIBS) -o $@
address@hidden verbatim
+
+In case this isn't right it may be freely changed. You should certainly
+refer to the @ref{Top,,Top,make,GNU Make Manual} manual to understand what
+that rule exactly means and make your own.
+
+
address@hidden Concepts index
address@hidden Concepts index
+
address@hidden cp
+
address@hidden Variables macros and functions index
address@hidden Variables, macros and functions index
+
address@hidden vr
+
address@hidden Installation
address@hidden Installation
+
address@hidden
+* Programming environments::
+* Common requisites::
+* Miniker with cmz::
+* Miniker with make::
address@hidden menu
+
address@hidden Programming environments
address@hidden Programming environments
address@hidden Programming environments
+
+Miniker is not a traditionnal software in that it isn't a library
+or an interpreter but rather a set of source and macro file that
+combines with the user model code and enable
+to build a binary program corresponding with the model. It
+requires a build environment with a preprocessor, a compiler
+and facilities that automate these steps.
+
+Two different environment are proposed. One use
address@hidden (@url{http://wwwcmz.web.cern.ch/@/wwwcmz/index.html}),
+while the other is based on @command{make}. Other libraries
+are needed, the CERN Program Library (cernlib) and lapack.
+
address@hidden Common requisites
address@hidden Common requisites
+
address@hidden cernlib
address@hidden lapack
+
+Whatever method is used a fortran 77 compiler is required. The compilers
+that have been used so far are g77, gfortran and the sun solaris compiler.
+
+When usng CMZ, the CERN Program Library, available at
address@hidden://wwwasd.web.cern.ch/@/wwwasd/cernlib/}, has to be installed.
+With make, internal source files copied from the cernlib may be used instead
+but then some examples won't be available, since they rely on some
+mathematical functions provided by the CERN library.
+On windows, in case you want to use the compiler from the GNU compiler
+collection with cygwin or MINGW/MSYS you can use the binaries provided at
address@hidden://zyao.home.cern.ch/@/zyao/cernlib.html}.
+On Mac OS X, the cernlib provided by fink (package @code{cernlib-devel})
+can be used.
+
+You should also have LAPACK, available at
@url{http://www.netlib.org/@/lapack/}.
+LAPACK can also be installed as part of the CERN Library or as part of
+the @uref{ATLAS,http://math-atlas.sourceforge.net/} implementation.
+On most linux distributions a lapack package is available.
+On Mac OS X, the ATLAS implementation provided by fink or the frameworks
+from Xcode can be used.
+
+
address@hidden Miniker with cmz
address@hidden Miniker with cmz
+
address@hidden @file{mini_ker.cmz}
address@hidden @file{selseq.kumac}
+
+First of all you have to get the cmz file @file{mini_ker.cmz} and put it
+in a directory. In that same directory you should create a directory for
+each of your models. In the model directory you should copy the file
address@hidden available with Miniker, and create your own cmz
+file for your model, called for example @file{mymodel.cmz}. You should also
+have installed the kumac macro files
+handling mortan compilation, the associated shell scripts and the mortran
+preprocessor.
+
address@hidden Miniker with make
address@hidden Miniker with make
+
address@hidden
+* Additional requirements::
+* Configuration::
+* Installation with make::
address@hidden menu
+
address@hidden Additional requirements
address@hidden Additional requirements for Miniker with make
+
address@hidden @command{mortran}, with make
address@hidden requirements, with make
+
+The package has been tested with GNU @command{make} and solaris
address@hidden
+
+Suitable preprocessors should also be installed. Two preprocessors are
+required, one that preprocess the cmz directives, and a mortran
+preprocessor. A cmz directives processor written in @command{perl},
+is distributed in the @command{car2txt} package available at
address@hidden://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}.
A @command{mortran}
+package with a command able to preprocess a mortran file given on
+the command line with a syntax similar with the @command{cpp} command line
+syntax is also required.
+Such a mortran is available at
@url{http://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}.
+
address@hidden All the @command{make} commands are not suitable, for example
the distribution
address@hidden doesn't work with solaris @command{make}. GNU @command{make}
works, however,
address@hidden and should be available on most platforms, often called
@command{gmake}.
+
+
address@hidden Configuration
address@hidden Configuration
+
address@hidden configuration of source
+
+The package is available at
@url{http://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}.
It is
+available as a compresssed tar archive. On UNIX, with GNU @command{tar} it
+may be unpacked using
+
address@hidden
+$ tar xzvf mini_ker-4.2.tar.gz
address@hidden example
+
+The detection of the compiler, the preprocessors (car2txt and mortran),
+and the libraries are performed by the configure script. This script
+sets the
+apropriate variables in makefiles. It can be run with:
+
address@hidden
+$ cd mini_ker-4.2
+$ ./configure
address@hidden example
+
+If the output of @command{./configure} doesn't show any error it means that
+all the components are here. It is possible to give @command{./configure}
+switches and also specify environment variables (see also
address@hidden/configure --help}):
+
address@hidden @code
address@hidden --disable-cernlib
+Use the internal cernlib source files, even if a cernlib is detected.
address@hidden --with-static-cernlib
+This command line switch forces a static linking with the cernlib (or a
dynamic linking
+if set to no).
address@hidden --with-cernlib
+This command line switch can be used to specify the cernlib location
+(if not detected or you want to use a specific cernlib).
address@hidden --with-blas
address@hidden --with-lapack
+With this command switch, you can specify the location of the blas and lapack
+libraries.
+
+For example, on mac OS X this can be used to specify the blas and lapack from
+the Apple frameworks:
+
address@hidden
+./configure \
+--with-blas=/System/Library/Frameworks/vecLib.framework/versions/A/vecLib \
+--with-lapack=/System/Library/Frameworks/vecLib.framework/versions/A/vecLib
address@hidden example
+
address@hidden F77
address@hidden FC
address@hidden FFLAGS
address@hidden LDFLAGS
+Classical compiler, compiler flags and linker flags.
address@hidden MORTRAN
+This environment variable holds the mortran preprocessor command
+(default is @command{mortran}).
address@hidden MTNFLAGS
+This environment variable holds command line arguments for the mortran
+preprocessor. It is empty in the default case.
address@hidden MTN
+This environment variable may be used to specify the mortran executable
+name and/or path, it should be used by the @command{mortran} commmand.
+(default is empty, which leads to a mortran executable called @command{mtn}).
address@hidden MTNDEPEND
+This environment variable may be used to specify the mortran dependencies
+checker executable. It should be used by the @command{mortran} commmand.
+(default is empty, which leads to a mortran dependencies checker
+called @command{mtndepend}).
address@hidden table
+
+After a proper configuration, if @command{make} is run then the example
+models should be build. You have to perform the configuration only once.
+
address@hidden Installation with make
address@hidden Installation with make
address@hidden installation with make
+
+Miniker can be installed by running
address@hidden
+make install
address@hidden example
+
+
+It should copy the sources
+and the @file{Makefile.miniker} file in
+a @file{mini_ker} directory in the @code{$(includedir)} directory, and
+copy the templates in @file{$(datadir)/mini_ker}. The default for
address@hidden(includedir)} is @file{/usr/local/include} and the default for
address@hidden(datadir)} is @file{/usr/local/share}, these defaults may be
+changed by @command{./configure} switches @samp{--prefix},
address@hidden and @samp{--datadir}. See @command{./configure --help}
+and the @file{INSTALL} file for more informations. The helper script
address@hidden should also be installed.
+
+
+
+The installation is not required to use comfortably Miniker. Indeed
+the only thing that changes with the sources and the @file{Makefile.miniker}
+directory location is the @code{miniker_dir} variable in a
+project @code{Makefile}.
+
+
address@hidden Cmz directives reference
address@hidden Cmz directives reference
+
+The cmz directives are described together with the other
+features of cmz in the cmz manual at
address@hidden://wwwcmz.web.cern.ch/wwwcmz/}, the important ones are
+nevertheless recalled here,
+especially for those that use make and don't need the whole
+features of cmz.
+
+After the description of the generic features, we turn
+to the cmz directive of interest.
+There are three kinds of cmz directives that are of use
+within Miniker: one kind
+that introduce files, the other for conditionnal compilation and
+the third for sequence inclusion.
+
+
address@hidden
+* Cmz directives general syntax::
+* Conditional expressions::
+* File introduction directives::
+* Conditional directives::
+* File inclusion directive::
+* The self directive::
address@hidden menu
+
address@hidden Cmz directives general syntax
address@hidden Cmz directives general syntax
+
+The cmz directives always begin with a @samp{+} in the first column,
+optionnaly followed by any number of @samp{_} that may be used for
+indentation, then the directive label, case insensitive, followed
+by the directive arguments separated by @samp{,}. The arguments
+are also case insensitive.
+Optional spaces may be around directive arguments.
+An optionnal @samp{.} ends the directive
+arguments and begin a comment, everything that follows that @samp{.} is
+ignored.
+
address@hidden Conditional expressions
address@hidden Conditional expressions
+
+A directive argument common to all the directives is the conditionnal
+expression. A conditionnal expression may be true or false, it is a
+combination of select flags. the select flags are combined with
+logical operators. A
+select flag itself is true if it was selected. A select flag @var{selflag}
+is selected by using the @code{sel @var{selflag}} instruction in cmz. It is
+selected by passing the @code{-D @var{selflag}} command line switch to
+the call of the cmz directives preprocessor when using make.
+
+
+A @samp{-} negates
+the expression that follows. Parenthesis @samp{(} and @samp{)} are used
+for the grouping of subexpressions. @samp{|} and @samp{,} are for the
+boolean or: an expression with a or is true
+if the expression on the left or the expression on the right of the or
+is true.
address@hidden&} is for the boolean and: an expression with an and is true if
+the expression on the left and the expression on the right are true.
+
+The grouping is left to right when there is no parenthesis, with or and
address@hidden&} having the same precedence. Therefore
+
address@hidden
+a&b|c @equiv{} (a&b)|c
+a|b&c @equiv{} (a|b)&c
+a|b&c is not a|(b&c)
+a&b|c is not a&(b|c)
address@hidden example
+
address@hidden File introduction directives
address@hidden File introduction directives
+
+A file (or sequence) introduction directive appears at the beginning
+of the file. There are two different directives, one is @code{DECK}
+for normal files, the other is @code{KEEP} for include files (sequences).
+The first argument is the name of the file. The file name may not be larger
+than 32 characters and is converted to lower case in the general case.
+The optionnal following arguments may be
+of 2 type (and may be mixed, separated by @samp{,}):
+
address@hidden @asis
address@hidden conditional
+A conditionnal is introduced by @code{IF=} followed by a conditionnal
+expression described in
address@hidden expressions}. The
+file is preprocessed if the conditionnal expression is true.
address@hidden language specification
+A language specification is introduced by a @code{T=}. The most
+common languages are @samp{mtn} for the mortran, @samp{ftn} for
+fortran not preprocessed, @samp{f77} for preprocessed fortran,
address@hidden for the c language and @samp{txt} for text files.
+In general the language of the file determines the name of files
+the preprocessed file is extracted to, the comment style and
+the command for inclusions.
address@hidden table
+
+It is a common practice to have wrong language type in @code{KEEP}
+as the language may be determined from the @code{DECK} that include
+them with cmz, or from their file name with make. This is not recommended
+and considered a bad practice.
+
+Such a directive will always appear in cmz, as it is built-in. It
+is recommended to have one when using make too, even though it is not
+required in most cases. Indeed make uses the file name directly
+and finds the language and file type by looking at the file extension.
+make should then pass the language type with a
address@hidden @var{lang}} command
+line switch when calling the cmz directives preprocessor.
+With make, the convention is to have @samp{cm} added before the normal
+file suffix and after the @samp{.}. The table @ref{tab:cmfile_suffix}
+shows the matching between suffixes, file type and file language.
+
+For example, a file beginning with
+
address@hidden
++Deck, subroutine_foo, If=monitor&-simple, T=f77.
address@hidden verbatim
+
+is a main preprocessed fortran file that will only be generated if
address@hidden is selected and @samp{simple} is not selected. The
+file to be preprocessed by make should have the @samp{.cmF} suffix,
+and be called @file{subroutine_foo.cmF}.
+
+A file beginning with
+
address@hidden
++KEEP,inc_common,If=monitor|interface,T=mtn
address@hidden verbatim
+
+is an mortran include file that should be processed only if @samp{monitor}
+or @samp{interface} is selected. The file to be preprocessed by make
+should have the @samp{cmmti} suffix and be called @file{inc_common.cmmti}.
+The resulting file when make is used will be called @file{inc_common.mti}.
+
address@hidden Conditional directives
address@hidden Conditional directives
+
+Conditional directives may be used to conditionnaly skip blocks of
+code. There are 4 conditional directives: @code{if}, @code{elseif},
address@hidden and @code{endif}. @code{+if} begins a conditional directives
+sequence, with argument a conditional expression. If the expression is
+true the block of code following the @code{+if} is output in the
+resulting file, up to another conditional directive, if it is false
+the code block is skipped. If the
+expression is false and the following conditional directive is
address@hidden, the same procedure is followed with the argument of
address@hidden
+which is also a conditionnal expression. More than one @code{+elseif}
+may follow a @code{+if}. If a @code{+if} or @code{+elseif} expression
+is true the following
+code block is output and all
+the following @code{+elseif} code blocks are skipped. If all the @code{+if}
+and @code{+elseif} expressions are false and
+the following coditionnal
+directive is @code{+else} then the block following the
address@hidden is output. If a previous expression was true the
+code block following the @code{+else} is skipped. The last code block
+is closed by @code{+endif}.
+
+Conditionnal directives may be nested, a @code{+if} begins a deeper
+conditionnal sequences directives that is ended by the corresponding
address@hidden
+
+The simplest example is:
+
address@hidden
+ some code;
++IF,monitor
+ code output only if monitor is true;
++ENDIF
address@hidden verbatim
+
+If @samp{monitor} is selected, the @code{+if} block is output, it leads to
+
address@hidden
+ some code;
+ code output only if monitor is true;
address@hidden verbatim
+
+If @samp{monitor} isn't selected the @code{+if} block is skipped, it leads to
+
address@hidden
+ some code;
address@hidden verbatim
+
+An example with @code{+else} may be:
+
address@hidden
++IF,double
+ call dmysub(eta);
++ELSE
+ call smysub(eta);
++ENDIF
address@hidden verbatim
+
+If @samp{double} is selected the code output is @code{call dmysub(eta);},
+if @samp{double} isn't selected the code output is @code{call dmysub(eta);}.
+
+Here is a self explanatory example of use of @code{+elseif}:
+
address@hidden
++IF,monitor
+ code used if monitor is selected;
++ELSEIF,kalman
+ code used if kalman is selected and monitor is not;
++ELSE
+ code used if kalman and monitor are not selected;
++ENDIF
address@hidden verbatim
+
+And last an example of nested conditional directives:
+
address@hidden
++IF,monitor
+ code used if monitor is selected;
++_IF,kalman. deep if
+ code used if monitor and kalman are selected;
++_ELSE. deep else
+ code used if monitor is selected and kalman is not;
++_ENDIF. end the deep conditionnals sequence
++ELSE
+ code used if monitor is not selected;
++_IF,kalman
+ code used if monitor is not selected but kalman is;
++_ELSE
+ code used if monitor and kalman are not selected;
++_ENDIF
+ other code used if monitor is not selected;
++ENDIF
address@hidden verbatim
+
address@hidden File inclusion directive
address@hidden File inclusion directive
+
+The file (sequence) inclusion directive is @code{seq}. The argument of
address@hidden is an include files @samp{,} separated list. The include
+files are @code{Keep} in cmz. The following optional arguments may be
+mixed:
+
address@hidden @asis
address@hidden conditional
+A conditionnal is introduced by @code{IF=} followed by a conditionnal
+expression described in
address@hidden expressions}. The
+directive is ignored if the conditionnal expression is false.
address@hidden T=noinclude
+When this argument is present the text of the sequence will
+always be included in the file where the @code{+seq} appears.
address@hidden table
+
+When there is no @code{T=noinclude} argument, the @code{+seq}
+directive may be replaced with an inclusion command suitable
+for the language of the file being processed, if such
+command has been specified.
+
+For example if we have the following sequence
address@hidden
++KEEP,inc,lang=C
+typedef struct incstr {char* msg};
address@hidden verbatim
+
+And the following code in the file being processed:
+
address@hidden
++DECK,mainf,lang=C
++SEQ,inc
+int main (int argc, char* argv) { exit(0); }
address@hidden verbatim
+
+the processing of @file{mainf} should lead to the file
address@hidden, containing
+an include command for @file{inc}:
+
address@hidden
+#include "inc.h"
+int main (int argc, char* argv) { exit(0); }
address@hidden verbatim
+
+In case the @code{+seq} has the @code{T=noinclude}:
+
address@hidden
++DECK,mainf,lang=C
++SEQ,inc,T=noinclude
+int main (int argc, char* argv) { exit(0); }
address@hidden verbatim
+
+The processing of @file{mainf} should lead to the file @file{mainf.c}
+containing the text of @file{inc}:
+
address@hidden
+typedef struct incstr {char* msg};
+int main (int argc, char* argv) { exit(0); }
address@hidden verbatim
+
address@hidden The self directive
address@hidden The @samp{self} directive
+
+The @code{self} directive is an obsolete directive that may be used for
+conditionnal skipping of code. For a better approach see
address@hidden directives}.
+The optionnal argument of @code{+SELF} is @code{If=} followed by
+a conditionnal expression. If the conditionnal expression is true the
+code following the directive is output, if it is false the code
+is skipped up to any directive (including another @code{+SELF})
+except @code{+seq}.
+
+
address@hidden Copying This Manual
address@hidden Copying This Manual
+
address@hidden
+* GNU Free Documentation License:: License for copying this manual.
address@hidden menu
+
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
+
address@hidden FDL, GNU Free Documentation License
address@hidden Version 1.1, March 2000
+
address@hidden
+Copyright @copyright{} 2000 Free Software Foundation, Inc.
+59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
address@hidden display
+
address@hidden 0
address@hidden
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+written document @dfn{free} in the sense of freedom: to assure everyone
+the effective freedom to copy and redistribute it, with or without
+modifying it, either commercially or noncommercially. Secondarily,
+this License preserves for the author and publisher a way to get
+credit for their work, while not being considered responsible for
+modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
address@hidden
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work that contains a
+notice placed by the copyright holder saying it can be distributed
+under the terms of this License. The ``Document'', below, refers to any
+such manual or work. Any member of the public is a licensee, and is
+addressed as ``you''.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (For example, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, whose contents can be viewed and edited directly and
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is
+not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
address@hidden without markup, Texinfo input format, address@hidden input
format,
address@hidden or @acronym{XML} using a publicly available
address@hidden, and standard-conforming simple @acronym{HTML} designed
+for human modification. Opaque formats include PostScript,
address@hidden, proprietary formats that can be read and edited only by
+proprietary word processors, @acronym{SGML} or @acronym{XML} for which
+the @acronym{DTD} and/or processing tools are not generally available,
+and the machine-generated @acronym{HTML} produced by some word
+processors for output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
address@hidden
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
address@hidden
+COPYING IN QUANTITY
+
+If you publish printed copies of the Document numbering more than 100,
+and the Document's license notice requires Cover Texts, you must enclose
+the copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols. If you use the latter
+option, you must take reasonably prudent steps, when you begin
+distribution of Opaque copies in quantity, to ensure that this
+Transparent copy will remain thus accessible at the stated location
+until at least one year after the last time you distribute an Opaque
+copy (directly or through your agents or retailers) of that edition to
+the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
address@hidden
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
address@hidden A
address@hidden
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
address@hidden
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has less than five).
+
address@hidden
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
address@hidden
+Preserve all the copyright notices of the Document.
+
address@hidden
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
address@hidden
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
address@hidden
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
address@hidden
+Include an unaltered copy of this License.
+
address@hidden
+Preserve the section entitled ``History'', and its title, and add to
+it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
address@hidden
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
address@hidden
+In any section entitled ``Acknowledgments'' or ``Dedications'',
+preserve the section's title, and preserve in the section all the
+substance and tone of each of the contributor acknowledgments
+and/or dedications given therein.
+
address@hidden
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
address@hidden
+Delete any section entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
address@hidden
+Do not retitle any existing section as ``Endorsements''
+or to conflict in title with any Invariant Section.
address@hidden enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
address@hidden
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections entitled ``History''
+in the various original documents, forming one section entitled
+``History''; likewise combine any sections entitled ``Acknowledgments'',
+and any sections entitled ``Dedications''. You must delete all sections
+entitled ``Endorsements.''
+
address@hidden
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
address@hidden
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, does not as a whole count as a Modified Version
+of the Document, provided no compilation copyright is claimed for the
+compilation. Such a compilation is called an ``aggregate'', and this
+License does not apply to the other self-contained works thus compiled
+with the Document, on account of their being thus compiled, if they
+are not themselves derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one quarter
+of the entire aggregate, the Document's Cover Texts may be placed on
+covers that surround only the Document within the aggregate.
+Otherwise they must appear on covers around the whole aggregate.
+
address@hidden
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License provided that you also include the
+original English version of this License. In case of a disagreement
+between the translation and the original English version of this
+License, the original English version will prevail.
+
address@hidden
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
address@hidden
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
address@hidden://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
address@hidden enumerate
+
address@hidden
address@hidden ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
address@hidden
address@hidden
+ Copyright (C) @var{year} @var{your name}.
+ 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 the Invariant Sections being @var{list their titles}, with the
+ Front-Cover Texts being @var{list}, and with the Back-Cover Texts being
@var{list}.
+ A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
address@hidden group
address@hidden smallexample
+
+If you have no Invariant Sections, write ``with no Invariant Sections''
+instead of saying which ones are invariant. If you have no
+Front-Cover Texts, write ``no Front-Cover Texts'' instead of
+``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
address@hidden Local Variables:
address@hidden ispell-local-pdict: "ispell-dict"
address@hidden End:
+
+
address@hidden
Index: res/texi_texinfo/texinfo.texi.first
===================================================================
RCS file: res/texi_texinfo/texinfo.texi.first
diff -N res/texi_texinfo/texinfo.texi.first
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ res/texi_texinfo/texinfo.texi.first 2 Aug 2009 13:11:00 -0000 1.1
@@ -0,0 +1,18090 @@
+\input texinfo.tex @c -*-texinfo-*-
address@hidden Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $
address@hidden Ordinarily Texinfo files have the extension .texi. But
texinfo.texi
address@hidden clashes with texinfo.tex on 8.3 filesystems, so we use
texinfo.txi.
+
address@hidden Everything between the start/end of header lines will be passed
by
address@hidden Emacs's {texinfo,makeinfo}-format region commands. See the
`start of
address@hidden header' node for more info.
address@hidden %**start of header
+
address@hidden makeinfo and texinfo.tex ignore all text before @setfilename.
address@hidden
address@hidden Ordinarily the setfilename argument ends with .info. But
address@hidden texinfo.info-13 is too long for 14-character filesystems.
address@hidden texinfo
+
address@hidden Automake automatically updates version.texi to @set VERSION and
address@hidden @set UPDATED to appropriate values.
address@hidden UPDATED 28 March 2002
address@hidden UPDATED-MONTH March 2002
address@hidden EDITION 4.2
address@hidden VERSION 4.2
address@hidden GNU Texinfo 4.2
+
address@hidden Define a new index for options.
address@hidden op
address@hidden Put everything except function (command, in this case) names in
one
address@hidden index (arbitrarily chosen to be the concept index).
address@hidden op cp
address@hidden vr cp
address@hidden pg cp
+
address@hidden separate
address@hidden 2
address@hidden finalout
+
address@hidden %**end of header
+
+
address@hidden Texinfo documentation system
address@hidden
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. Update info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
+* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
+* makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source.
address@hidden direntry
+
address@hidden Before release, run C-u C-c C-u C-a (texinfo-all-menus-update
with a
address@hidden prefix arg). This updates the node pointers, which texinfmt.el
needs.
+
address@hidden Set smallbook if printing in smallbook format so the example of
the
address@hidden smallbook font is actually written using smallbook; in bigbook,
a kludge
address@hidden is used for TeX output. Do this through the -t option to
texi2dvi,
address@hidden so this same source can be used for other paper sizes as well.
address@hidden smallbook
address@hidden set smallbook
address@hidden @@clear smallbook
+
address@hidden If you like blank pages, add through texi2dvi -t.
address@hidden setchapternewpage odd
+
address@hidden Currently undocumented command, 5 December 1993:
address@hidden nwnode (Same as node, but no warnings; for `makeinfo'.)
+
+
address@hidden Texinfo
+
+
+
address@hidden
address@hidden
+
+
address@hidden Top
address@hidden Texinfo
+
address@hidden
+
+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.
+
+
address@hidden
+* Copying Conditions:: Your rights.
+* Overview:: Texinfo in brief.
+* Texinfo Mode:: How to use Texinfo mode.
+* Beginning a File:: What is at the beginning of a Texinfo file?
+* Ending a File:: What is at the end of a Texinfo file?
+* Structuring:: How to create chapters, sections, subsections,
+ appendices, and other parts.
+* Nodes:: How to write nodes.
+* Menus:: How to write menus.
+* Cross References:: How to write cross references.
+* Marking Text:: How to mark words and phrases as code,
+ keyboard input, meta-syntactic
+ variables, and the like.
+* Quotations and Examples:: How to write quotations, examples, etc.
+* Lists and Tables:: How to write lists and tables.
+* Indices:: How to create indices.
+* Insertions:: How to insert @@-signs, braces, etc.
+* Breaks:: How to force and prevent line and page breaks.
+* Definition Commands:: How to describe functions and the like
+ in a uniform manner.
+* Conditionals:: How to specify text for either @TeX{} or Info.
+* Internationalization::
+* Defining New Texinfo Commands::
+* Hardcopy:: How to convert a Texinfo file to a file
+ for printing and how to print that file.
+* Creating and Installing Info Files::
+* Command List:: All the Texinfo @@-commands.
+* Tips:: Hints on how to write a Texinfo document.
+* Sample Texinfo Files:: Complete examples, including full texts.
+* Include Files:: How to incorporate other Texinfo files.
+* Headings:: How to write page headings and footings.
+* Catching Mistakes:: How to find formatting mistakes.
+* Refilling Paragraphs:: All about paragraph refilling.
+* Command Syntax:: A description of @@-Command syntax.
+* Obtaining TeX:: How to Obtain @TeX{}.
+* Copying This Manual:: The GNU Free Documentation License.
+* Command and Variable Index:: A menu containing commands and variables.
+* Concept Index:: A menu covering many topics.
+
address@hidden
+ --- The Detailed Node Listing ---
+
+Overview of Texinfo
+
+* Reporting Bugs:: Submitting effective bug reports.
+* Using Texinfo:: Create printed or online output.
+* Info Files:: What is an Info file?
+* Printed Books:: Characteristics of a printed book or manual.
+* Formatting Commands:: @@-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.
+* Six Parts:: Usually, a Texinfo file has six parts.
+* Short Sample:: A short sample Texinfo file.
+* History:: Acknowledgements, contributors and genesis.
+
+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.
+
+Beginning a Texinfo File
+
+* Sample Beginning:: A sample beginning for a Texinfo file.
+* Texinfo File Header::
+* Document Permissions::
+* Titlepage & Copyright Page:: Creating the title and copyright pages.
+* The Top Node:: Creating the `Top' node and master menu.
+* Global Document Commands::
+* Software Copying Permissions:: Ensure that you and others continue to
+ have the right to use and share software.
+
+Texinfo File Header
+
+* First Line:: The first line of a Texinfo file.
+* Start of Header:: Formatting a region requires this.
+* setfilename:: Tell Info the name of the Info file.
+* settitle:: Create a title for the printed work.
+* End of Header:: Formatting a region requires this.
+
+Document Permissions
+
+* copying:: Declare the document's copying permissions.
+* insertcopying:: Where to insert the permissions.
+
+Title and Copyright Pages
+
+* titlepage:: Create a title for the printed document.
+* titlefont center sp:: The @code{@@titlefont}, @code{@@center},
+ and @code{@@sp} commands.
+* title subtitle author:: The @code{@@title}, @code{@@subtitle},
+ and @code{@@author} commands.
+* Copyright:: How to write the copyright notice and
+ include copying permissions.
+* end titlepage:: Turn on page headings after the title and
+ copyright pages.
+* headings on off:: An option for turning headings on and off
+ and double or single sided printing.
+
+The `Top' Node and Master Menu
+
+* Top Node Example::
+* Master Menu Parts::
+
+Global Document Commands
+
+* documentdescription:: Document summary for the HTML output.
+* setchapternewpage:: Start chapters on right-hand pages.
+* paragraphindent:: Specify paragraph indentation.
+* exampleindent:: Specify environment indentation.
+
+Ending a Texinfo File
+
+* Printing Indices & Menus:: How to print an index in hardcopy and
+ generate index menus in Info.
+* Contents:: How to create a table of contents.
+* File End:: How to mark the end of a file.
+
+Chapter Structuring
+
+* Tree Structuring:: A manual is like an upside down tree @dots{}
+* Structuring Command Types:: How to divide a manual into parts.
+* makeinfo top:: The @code{@@top} command, part of the `Top'
node.
+* chapter::
+* unnumbered & appendix::
+* majorheading & chapheading::
+* section::
+* unnumberedsec appendixsec heading::
+* subsection::
+* unnumberedsubsec appendixsubsec subheading::
+* subsubsection:: Commands for the lowest level sections.
+* Raise/lower sections:: How to change commands' hierarchical level.
+
+Nodes
+
+* Two Paths:: Different commands to structure
+ Info output and printed output.
+* Node Menu Illustration:: A diagram, and sample nodes and menus.
+* node:: Creating nodes, in detail.
+* makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
+* anchor:: Defining arbitrary cross-reference targets.
+
+The @code{@@node} Command
+
+* Node Names:: How to choose node and pointer names.
+* Writing a Node:: How to write an @code{@@node} line.
+* Node Line Tips:: Keep names short.
+* Node Line Requirements:: Keep names unique, without @@-commands.
+* First Node:: How to write a `Top' node.
+* makeinfo top command:: How to use the @code{@@top} command.
+
+Menus
+
+* Menu Location:: Put a menu in a short node.
+* Writing a Menu:: What is a menu?
+* Menu Parts:: A menu entry has three parts.
+* Less Cluttered Menu Entry:: Two part menu entry.
+* Menu Example:: Two and three part menu entries.
+* Other Info Files:: How to refer to a different Info file.
+
+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.
+* xref:: Begin a reference with `See' @dots{}
+* Top Node Naming:: How to refer to the beginning of another file.
+* ref:: A reference for the last part of a sentence.
+* pxref:: How to write a parenthetical cross reference.
+* inforef:: How to refer to an Info-only file.
+* uref:: How to refer to a uniform resource locator.
+
address@hidden@@xref}
+
+* Reference Syntax:: What a reference looks like and requires.
+* 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.
+
+Marking 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:: Indicating program code.
+* kbd:: Showing keyboard input.
+* key:: Specifying keys.
+* samp:: A literal sequence of characters.
+* verb:: A verbatim sequence of characters.
+* var:: Indicating metasyntactic variables.
+* env:: Indicating environment variables.
+* file:: Indicating file names.
+* command:: Indicating command names.
+* option:: Indicating option names.
+* dfn:: Specifying definitions.
+* cite:: Referring to books not in the Info system.
+* acronym:: Indicating acronyms.
+* url:: Indicating a World Wide Web reference.
+* email:: Indicating an electronic mail address.
+
+Emphasizing Text
+
+* 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.
+* quotation:: Writing a quotation.
+* example:: Writing an example in a fixed-width font.
+* verbatim:: Writing a verbatim example.
+* verbatiminclude:: Including a file verbatim.
+* lisp:: Illustrating Lisp code.
+* small:: Forms for @code{@@smallbook}.
+* display:: Writing an example in the current font.
+* format:: Writing an example without narrowed margins.
+* exdent:: Undo indentation on a line.
+* flushleft & flushright:: Pushing text flush left or flush right.
+* noindent:: Preventing paragraph indentation.
+* cartouche:: Drawing rounded rectangles around examples.
+
+Lists and Tables
+
+* Introducing Lists:: Texinfo formats lists for you.
+* itemize:: How to construct a simple list.
+* 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
+
+* table:: How to construct a two-column table.
+* ftable vtable:: Automatic indexing for two-column tables.
+* itemx:: How to put more entries in the first column.
+
+Multi-column Tables
+
+* Multitable Column Widths:: Defining multitable column widths.
+* Multitable Rows:: Defining multitable rows, with examples.
+
+Indices
+
+* Index Entries:: Choose different words for index entries.
+* Predefined Indices:: Use different indices for different kinds
+ of entry.
+* Indexing Commands:: How to make an index entry.
+* Combining Indices:: How to combine indices.
+* New Indices:: How to define your own indices.
+
+Combining Indices
+
+* syncodeindex:: How to merge two indices, using @code{@@code}
+ font for the merged-from index.
+* synindex:: How to merge two indices, using the
+ default font of the merged-to index.
+
+Special Insertions
+
+* Braces Atsigns:: How to insert braces, @samp{@@}.
+* Inserting Space:: How to insert the right amount of space
+ within a sentence.
+* Inserting Accents:: How to insert accents and special characters.
+* Dots Bullets:: How to insert dots and bullets.
+* TeX and copyright:: How to insert the @TeX{} logo
+ and the copyright symbol.
+* pounds:: How to insert the pounds currency symbol.
+* minus:: How to insert a minus sign.
+* math:: How to format a mathematical expression.
+* Glyphs:: How to indicate results of evaluation,
+ expansion of macros, errors, etc.
+* Footnotes:: How to include footnotes.
+* Images:: How to include graphics.
+
+Inserting @@ and Braces
+
+* Inserting An Atsign:: How to insert @samp{@@}.
+* Inserting Braces:: How to insert @address@hidden and
@address@hidden
+
+Inserting Space
+
+* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
+* Ending a Sentence:: Sometimes it does.
+* Multiple Spaces:: Inserting multiple spaces.
+* dmn:: How to format a dimension.
+
+Inserting Ellipsis and Bullets
+
+* dots:: How to insert dots @dots{}
+* bullet:: How to insert a bullet.
+
+Inserting @TeX{} and the Copyright Symbol
+
+* tex:: How to insert the @TeX{} logo.
+* copyright symbol:: How to use @code{@@address@hidden@}.
+
+Glyphs for Examples
+
+* Glyphs Summary::
+* result:: How to show the result of expression.
+* expansion:: How to indicate an expansion.
+* Print Glyph:: How to indicate printed output.
+* Error Glyph:: How to indicate an error message.
+* Equivalence:: How to indicate equivalence.
+* Point Glyph:: How to indicate the location of point.
+
+Glyphs Summary
+
+* result::
+* expansion::
+* Print Glyph::
+* Error Glyph::
+* Equivalence::
+* Point Glyph::
+
+Footnotes
+
+* Footnote Commands:: How to write a footnote in Texinfo.
+* Footnote Styles:: Controlling how footnotes appear in Info.
+
+Making and Preventing Breaks
+
+* Break Commands:: Cause and prevent splits.
+* Line Breaks:: How to force a single line to use two lines.
+* - and hyphenation:: How to tell @TeX{} about hyphenation points.
+* w:: How to prevent unwanted line breaks.
+* sp:: How to insert blank lines.
+* page:: How to force the start of a new page.
+* group:: How to prevent unwanted page breaks.
+* need:: Another way to prevent unwanted page breaks.
+
+Definition Commands
+
+* Def Cmd Template:: How to structure a description using a
+ definition command.
+* Optional Arguments:: How to handle optional and repeated arguments.
+* deffnx:: How to group two or more `first' lines.
+* Def Cmds in Detail:: All the definition commands.
+* Def Cmd Conventions:: Conventions for writing definitions.
+* Sample Function Definition::
+
+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.
+* Abstract Objects:: Commands for object-oriented programming.
+* Data Types:: The definition command for data types.
+
+Conditionally Visible Text
+
+* Conditional Commands:: Specifying text for HTML, Info, or @TeX{}.
+* Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}.
+* Raw Formatter Commands:: Using raw @TeX{} or HTML commands.
+* set clear value:: Designating which text to format (for
+ all output formats); and how to set a
+ flag to a string that you can insert.
+
address@hidden@@set}, @code{@@clear}, and @code{@@value}
+
+* set value:: Expand a flag variable to a string.
+* ifset ifclear:: Format a region if a flag is set.
+* value Example:: An easy way to update edition information.
+
+Internationalization
+
+* documentlanguage:: Declaring the current language.
+* documentencoding:: Declaring the input encoding.
+
+Defining New Texinfo Commands
+
+* Defining Macros:: Defining and undefining new commands.
+* Invoking Macros:: Using a macro, once you've defined it.
+* Macro Details:: Beyond basic macro usage.
+* alias:: Command aliases.
+* definfoenclose:: Customized highlighting.
+
+Formatting and Printing Hardcopy
+
+* Use TeX:: Use @TeX{} to format for hardcopy.
+* Format with tex/texindex:: How to format with explicit shell commands.
+* Format with texi2dvi:: A simpler way to format.
+* Print with 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.
+* smallbook:: How to print small format books and manuals.
+* A4 Paper:: How to print on A4 or A5 paper.
+* 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.
+
+Creating and Installing Info Files
+
+* Creating an Info File::
+* Installing an Info File::
+
+Creating an Info File
+
+* makeinfo advantages:: @code{makeinfo} provides better error checking.
+* Invoking makeinfo:: How to run @code{makeinfo} from a shell.
+* makeinfo options:: Specify fill-column and other options.
+* Pointer Validation:: How to check that pointers point somewhere.
+* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs.
+* 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.
+* makeinfo html:: Generating HTML output.
+
+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 install-info:: @code{install-info} options.
+
+Sample Texinfo Files
+
+* Short Sample Texinfo File::
+* GNU Sample Texts::
+
+Include Files
+
+* Using Include Files:: How to use the @code{@@include} command.
+* texinfo-multiple-files-update:: How to create and update nodes and
+ menus when using included files.
+* Include File Requirements:: What @code{texinfo-multiple-files-update}
expects.
+* 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.
+
+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.
+
+Formatting Mistakes
+
+* 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 texinfo-show-structure:: How to use @code{texinfo-show-structure}.
+* Using occur:: How to list all lines containing a pattern.
+* Running Info-Validate:: How to find badly referenced nodes.
+
+Finding Badly Referenced Nodes
+
+* Using 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.
+
+Copying This Manual
+
+* GNU Free Documentation License:: License for copying this manual.
+
address@hidden detailmenu
address@hidden menu
+
address@hidden Reward readers for getting to the end of the menu :).
address@hidden Contributed by Arnold Robbins.
address@hidden
+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
address@hidden quotation
+
+
address@hidden Copying Conditions
address@hidden Texinfo Copying Conditions
address@hidden Copying conditions
address@hidden Conditions for copying Texinfo
+
+The programs currently being distributed that relate to Texinfo include
address@hidden, @code{info}, @code{texindex}, and @file{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. This manual specifically is covered by
+the GNU Free Documentation License (@pxref{GNU Free Documentation
+License}).
+
+
address@hidden Overview
address@hidden Overview of Texinfo
address@hidden Overview of Texinfo
address@hidden Texinfo overview
+
address@hidden@footnote{The first syllable of ``Texinfo'' is pronounced
+like ``speck'', not ``hex''. This odd pronunciation is derived from,
+but is not the same as, the pronunciation of @TeX{}. In the word
address@hidden, the @samp{X} is actually the Greek letter ``chi'' rather than
+the English letter ``ex''. Pronounce @TeX{} as if the @samp{X} were the
+last sound in the name `Bach'; but pronounce Texinfo as if the @samp{x}
+were a `k'. Spell ``Texinfo'' with a capital ``T'' and the other
+letters in lower case.} is a documentation system that uses a single
+source file to produce both online information and printed output. This
+means that instead of writing two different documents, one for the
+online information and the other for a printed work, you need write only
+one document. Therefore, when the work is revised, you need revise only
+that one document.
+
address@hidden
+* Reporting Bugs:: Submitting effective bug reports.
+* Using Texinfo:: Create printed or online output.
+* Info Files:: What is an Info file?
+* Printed Books:: Characteristics of a printed book or manual.
+* Formatting Commands:: @@-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.
+* Six Parts:: Usually, a Texinfo file has six parts.
+* Short Sample:: A short sample Texinfo file.
+* History:: Acknowledgements, contributors and genesis.
address@hidden menu
+
+
address@hidden Reporting Bugs
address@hidden Reporting Bugs
+
address@hidden Bugs, reporting
address@hidden Suggestions for Texinfo, making
address@hidden Reporting bugs
+We welcome bug reports and suggestions for any aspect of the Texinfo system,
+programs, documentation, installation, anything. Please email them to
address@hidden@@gnu.org}. You can get the latest version of Texinfo
+from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide.
+
address@hidden Checklist for bug reports
+For bug reports, please include enough information for the maintainers
+to reproduce the problem. Generally speaking, that means:
+
address@hidden @bullet
address@hidden the version number of Texinfo and the program(s) or manual(s)
involved.
address@hidden hardware and operating system names and versions.
address@hidden the contents of any input files necessary to reproduce the bug.
address@hidden a description of the problem and samples of any erroneous output.
address@hidden any unusual options you gave to @command{configure}.
address@hidden anything else that you think would be helpful.
address@hidden 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.
+
address@hidden Patches, contributing
+Patches are most welcome; if possible, please make them with
address@hidden@w{diff -c}} (@pxref{Top,, Overview, diffutils, Comparing and
+Merging Files}) and include @file{ChangeLog} entries (@pxref{Change
+Log,,, emacs, The GNU Emacs Manual}).
+
+When sending patches, if possible please do not encode or split them in
+any way; it's much easier to deal with one plain text message, however
+large, than many small ones. @uref{ftp://ftp.gnu.org/gnu/sharutils/,
+GNU shar} is a convenient way of packaging multiple and/or binary files
+for email.
+
+
address@hidden Using Texinfo
address@hidden Using Texinfo
+
address@hidden Using Texinfo in general
address@hidden Texinfo, introduction to
address@hidden Introduction to Texinfo
+
+Using Texinfo, you can create a printed document with the normal
+features of a book, including chapters, sections, cross references, and
+indices. From the same Texinfo source file, you can create a
+menu-driven, online Info file with nodes, menus, cross references, and
+indices. You can also create from that same source file an HTML output
+file suitable for use with a web browser, or an XML file. @cite{The GNU
+Emacs Manual} is a good example of a Texinfo file, as is this manual.
+
+To make a printed document, you process a Texinfo source file with the
address@hidden typesetting program (but the Texinfo language is very different
+and much stricter than @TeX{}'s usual language, plain @TeX{}). This
+creates a DVI file that you can typeset and print as a book or report
+(@pxref{Hardcopy}).
+
address@hidden makeinfo
+To output an Info file, process your Texinfo source with the
address@hidden utility or Emacs's @code{texinfo-format-buffer} command.
+You can install the result in your Info tree (@pxref{Installing an Info
+File}).
+
+To output an HTML file, run @code{makeinfo --html} on your Texinfo
+source. You can (for example) install the result on your web site.
+
address@hidden Docbook, converting to Texinfo
address@hidden Conversion, from Docbook to Texinfo
+To output an XML file, run @code{makeinfo --xml} on your Texinfo source.
+To output DocBook (a particular form of XML), run @code{makeinfo
+--docbook}. If you want to convert from Docbook @emph{to} Texinfo,
+please see @uref{http://docbook2X.sourceforge.net/}.
+
address@hidden Output formats, supporting more
address@hidden SGML-tools output format
+If you are a programmer and would like to contribute to the GNU project
+by implementing additional output formats for Texinfo, that would be
+excellent. But please do not write a separate translator texi2foo for
+your favorite format foo! That is the hard way to do the job, and makes
+extra work in subsequent maintenance, since the Texinfo language is
+continually being enhanced and updated. Instead, the best approach is
+modify @code{makeinfo} to generate the new format, as it does now for
+Info, plain text, HTML, XML, and DocBook.
+
address@hidden works with virtually all printers; Info works with virtually all
+computer terminals; the HTML output works with virtually all web
+browsers. Thus Texinfo can be used by almost any computer user.
+
address@hidden Source file
+A Texinfo source file is a plain @sc{ascii} file containing text and
address@hidden@@-commands} (words preceded by an @samp{@@}) that tell the
+typesetting and formatting programs what to do. You may 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}.)
+
+Before writing a Texinfo source file, you should learn about nodes,
+menus, cross references, and the rest, for example by reading this
+manual.
+
+You can use Texinfo to create both online help and printed manuals;
+moreover, Texinfo is freely redistributable. For these reasons, Texinfo
+is the official documentation format of the GNU project. More
+information is available at the @uref{http://www.gnu.org/doc/, GNU
+documentation web page}.
+
address@hidden Man page output, not supported
+From time to time, proposals are made to generate traditional Unix man
+pages from Texinfo source. This is not likely to ever be supported,
+because man pages have a very strict conventional format. Merely
+enhancing @command{makeinfo} to output troff format would be
+insufficient. Generating a good man page therefore requires a
+completely different source than the typical Texinfo applications of
+writing a good user tutorial or a good reference manual. This makes
+generating man pages incompatible with the Texinfo design goal of not
+having to document the same information in different ways for different
+output formats. You might as well just write the man page directly.
+
address@hidden help2man
address@hidden O'Dea, Brendan
+Man pages still have their place, and if you wish to support them, the
+program @command{help2man} may be useful; it generates a traditional man
+page from the @samp{--help} output of a program. In fact, this is
+currently used to generate man pages for the Texinfo programs
+themselves. It is GNU software written by Brendan O'Dea, available from
address@hidden://ftp.gnu.org/gnu/help2man/}.
+
+
address@hidden Info Files
address@hidden Info files
address@hidden Info files
+
+An Info file is a Texinfo file formatted so that the Info documentation
+reading program can operate on it. (@code{makeinfo}
+and @code{texinfo-format-buffer} are two commands that convert a Texinfo file
+into an Info file.)
+
+Info files are divided into pieces called @dfn{nodes}, each of which
+contains the discussion of one topic. Each node has a name, and
+contains both text for the user to read and pointers to other nodes,
+which are identified by their names. The Info program displays one node
+at a time, and provides commands with which the user can move to other
+related nodes.
+
address@hidden, info, info}, for more information about using Info.
+
+Each node of an Info file may have any number of child nodes that
+describe subtopics of the node's topic. The names of child
+nodes are listed in a @dfn{menu} within the parent node; this
+allows you to use certain Info commands to move to one of the child
+nodes. Generally, an Info file is organized like a book. If a node
+is at the logical level of a chapter, its child nodes are at the level
+of sections; likewise, the child nodes of sections are at the level
+of subsections.
+
+All the children of any one parent are linked together in a
+bidirectional chain of `Next' and `Previous' pointers. The `Next'
+pointer provides a link to the next section, and the `Previous' pointer
+provides a link to the previous section. This means that all the nodes
+that are at the level of sections within a chapter are linked together.
+Normally the order in this chain is the same as the order of the
+children in the parent's menu. Each child node records the parent node
+name as its `Up' pointer. The last child has no `Next' pointer, and the
+first child has the parent both as its `Previous' and as its `Up'
address@hidden some documents, the first child has no `Previous'
+pointer. Occasionally, the last child has the node name of the next
+following higher level node as its `Next' pointer.}
+
+The book-like structuring of an Info file into nodes that correspond
+to chapters, sections, and the like is a matter of convention, not a
+requirement. The `Up', `Previous', and `Next' pointers of a node can
+point to any other nodes, and a menu can contain any other nodes.
+Thus, the node structure can be any directed graph. But it is usually
+more comprehensible to follow a structure that corresponds to the
+structure of chapters and sections in a printed book or address@hidden
+
+In addition to menus and to `Next', `Previous', and `Up' pointers, Info
+provides pointers of another kind, called references, that can be
+sprinkled throughout the text. This is usually the best way to
+represent links that do not fit a hierarchical address@hidden
+
+Usually, you will design a document so that its nodes match the
+structure of chapters and sections in the printed output. But
+occasionally there are times when this is not right for the material
+being discussed. Therefore, Texinfo uses separate commands to specify
+the node structure for the Info file and the section structure for the
+printed address@hidden
+
+Generally, you enter an Info file through a node that by convention is
+named `Top'. This node normally contains just a brief summary of the
+file's purpose, and a large menu through which the rest of the file is
+reached. From this node, you can either traverse the file
+systematically by going from node to node, or you can go to a specific
+node listed in the main menu, or you can search the index menus and then
+go directly to the node that has the information you want. Alternatively,
+with the standalone Info program, you can specify specific menu items on
+the command line (@pxref{Top,,, info, Info}).
+
+If you want to read through an Info file in sequence, as if it were a
+printed manual, you can hit @key{SPC} repeatedly, or you get the whole
+file with the advanced Info command @kbd{g *}. (@inforef{Expert,
+Advanced Info commands, info}.)@refill
+
address@hidden !!! dir file may be located in one of many places:
address@hidden /usr/local/emacs/info mentioned in info.c
DEFAULT_INFOPATH
address@hidden /usr/local/lib/emacs/info mentioned in info.c
DEFAULT_INFOPATH
address@hidden /usr/gnu/info mentioned in info.c
DEFAULT_INFOPATH
address@hidden /usr/local/info
address@hidden /usr/local/lib/info
+The @file{dir} file in the @file{info} directory serves as the
+departure point for the whole Info system. From it, you can reach the
+`Top' nodes of each of the documents in a complete Info address@hidden
+
address@hidden URI syntax for Info
+If you wish to refer to an Info file in a URI, you can use the
+(unofficial) syntax exemplified in the following. This works with
+Emacs/W3, for example:
address@hidden
+info:///usr/info/emacs#Dissociated%20Press
+info:emacs#Dissociated%20Press
+info://localhost/usr/info/emacs#Dissociated%20Press
address@hidden example
+
+The @command{info} program itself does not follow URI's of any kind.
+
+
address@hidden Printed Books
address@hidden Printed Books
address@hidden Printed book and manual characteristics
address@hidden Manual characteristics, printed
address@hidden Book characteristics, printed
address@hidden Texinfo printed book characteristics
address@hidden Characteristics, printed books or manuals
+
address@hidden Knuth, Donald
+A Texinfo file can be formatted and typeset as a printed book or manual.
+To do this, you need @TeX{}, a powerful, sophisticated typesetting
+program written by Donald address@hidden can also use the
address@hidden address@hidden, unsupported software}
address@hidden://tug.org/texi2roff.tar.gz, @code{texi2roff}} program if you
+do not have @TeX{}; since Texinfo is designed for use with @TeX{},
address@hidden is not described here. @code{texi2roff} is not part of
+the standard GNU distribution and is not maintained or up-to-date with
+all the Texinfo features described in this manual.}
+
+A Texinfo-based book is similar to any other typeset, printed work: it
+can have a title page, copyright page, table of contents, and preface,
+as well as chapters, numbered or unnumbered sections and subsections,
+page headers, cross references, footnotes, and address@hidden
+
+You can use Texinfo to write a book without ever having the intention
+of converting it into online information. You can use Texinfo for
+writing a printed novel, and even to write a printed memo, although
+this latter application is not recommended since electronic mail is so
+much address@hidden
+
address@hidden is a general purpose typesetting program. Texinfo provides a
+file @file{texinfo.tex} that contains information (definitions or
address@hidden) that @TeX{} uses when it typesets a Texinfo file.
+(@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands
+to @TeX{} commands, which @TeX{} can then process to create the typeset
+document.) @file{texinfo.tex} contains the specifications for printing
+a document. You can get the latest version of @file{texinfo.tex} from
address@hidden://ftp.gnu.org/gnu/texinfo.tex}.
+
+In the United States, documents are most often printed on 8.5 inch by 11
+inch pages (address@hidden by address@hidden); this is the default size. But
+you can also print for 7 inch by 9.25 inch pages (address@hidden by
address@hidden, the @code{@@smallbook} size; or on A4 or A5 size paper
+(@code{@@afourpaper}, @code{@@afivepaper}). (@xref{smallbook, ,
+Printing ``Small'' Books}. Also, see @ref{A4 Paper, ,Printing on A4
+Paper}.)
+
+By changing the parameters in @file{texinfo.tex}, you can change the
+size of the printed document. In addition, you can change the style in
+which the printed document is formatted; for example, you can change the
+sizes and fonts used, the amount of indentation for each paragraph, the
+degree to which words are hyphenated, and the like. By changing the
+specifications, you can make a book look dignified, old and serious, or
+light-hearted, young and cheery.
+
address@hidden is freely distributable. It is written in a superset 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.
+(@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information
+about @TeX{}.)@refill
+
address@hidden is very powerful and has a great many features. Because a
+Texinfo file must be able to present information both on a
+character-only terminal in Info form and in a typeset book, the
+formatting commands that Texinfo supports are necessarily limited.
+
+To get a copy of @TeX{}, see
address@hidden TeX, , How to Obtain @TeX{}}.
+
+
address@hidden Formatting Commands
address@hidden @@-commands
address@hidden @@-commands
address@hidden Formatting commands
+
+In a Texinfo file, the commands that tell @TeX{} how to typeset the
+printed manual and tell @code{makeinfo} and
address@hidden how to create an Info file are preceded
+by @samp{@@}; they are called @dfn{@@-commands}. For example,
address@hidden@@node} is the command to indicate a node and @code{@@chapter}
+is the command to indicate the start of a address@hidden
+
address@hidden
address@hidden note:} All the @@-commands, with the exception of the
address@hidden@@address@hidden@}} command, must be written entirely in lower
case.
address@hidden quotation
+
+The Texinfo @@-commands are a strictly limited set of constructs. The
+strict limits make it possible for Texinfo files to be understood both
+by @TeX{} and by the code that converts them into Info files. You can
+display Info files on any terminal that displays alphabetic and
+numeric characters. Similarly, you can print the output generated by
address@hidden on a wide variety of address@hidden
+
+Depending on what they do or what address@hidden word
address@hidden comes from the way it is used in mathematics and does not
+refer to a dispute between two people; it refers to the information
+presented to the command. According to the @cite{Oxford English
+Dictionary}, the word derives from the Latin for @dfn{to make clear,
+prove}; thus it came to mean `the evidence offered as proof', which is
+to say, `the information offered', which led to its mathematical
+meaning. In its other thread of derivation, the word came to mean `to
+assert in a manner against which others may make counter assertions',
+which led to the meaning of `argument' as a dispute.} they take, you
+need to write @@-commands on lines of their own or as part of
+sentences:
+
address@hidden @bullet
address@hidden
+Write a command such as @code{@@noindent} at the beginning of a line as
+the only text on the line. (@code{@@noindent} prevents the beginning of
+the next line from being indented as the beginning of a
+paragraph.)@refill
+
address@hidden
+Write a command such as @code{@@chapter} at the beginning of a line
+followed by the command's arguments, in this case the chapter title, on
+the rest of the line. (@code{@@chapter} creates chapter titles.)@refill
+
address@hidden
+Write a command such as @code{@@address@hidden@}} wherever you wish but usually
+within a sentence. (@code{@@address@hidden@}} creates dots @dots{})@refill
+
address@hidden
+Write a command such as @code{@@address@hidden@address@hidden wherever you
+wish (but usually within a sentence) with its argument,
address@hidden in this example, between the braces. (@code{@@code}
+marks text as being code.)@refill
+
address@hidden
+Write a command such as @code{@@example} on a line of its own; write the
+body-text on following lines; and write the matching @code{@@end}
+command, @code{@@end example} in this case, at the on a line of its own
+after the body-text. (@code{@@example} @dots{} @code{@@end example}
+indents and typesets body-text as an example.) It's usually ok to
+indent environment commands like this, but in complicated and
+hard-to-define circumstances the extra spaces cause extra space to
+appear in the output, so beware.
address@hidden itemize
+
address@hidden
address@hidden Braces, when to use
+As a general rule, a command requires braces if it mingles among other
+text; but it does not need braces if it starts a line of its own. The
+non-alphabetic commands, such as @code{@@:}, are exceptions to the rule;
+they do not need address@hidden
+
+As you gain experience with Texinfo, you will rapidly learn how to
+write the different commands: the different ways to write commands
+make it easier to write and read Texinfo files than if all commands
+followed exactly the same syntax. (For details about @@-command
+syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill
+
+
address@hidden Conventions
address@hidden General Syntactic Conventions
address@hidden General syntactic conventions
address@hidden Syntactic conventions
address@hidden Conventions, syntactic
+
+This section describes the general conventions used in all Texinfo documents.
+
address@hidden @bullet
address@hidden
+All printable @sc{ascii} characters except @samp{@@}, @address@hidden and
address@hidden@}} can appear in a Texinfo file and stand for themselves.
address@hidden@@} is the escape character which introduces commands, while
address@hidden@{} and @address@hidden are used to surround arguments to certain
+commands. To put one of these special characters into the document, put
+an @samp{@@} character in front of it, like this: @samp{@@@@},
address@hidden@@@{}, and @samp{@@@}}.
+
address@hidden
+It is customary in @TeX{} to use doubled single-quote characters to
+begin and end quotations: @address@hidden@address@hidden'@w{}'}}. This
+convention should be followed in Texinfo files. @TeX{} converts
+two single quotes to left- and right-hand doubled
+quotation marks,
address@hidden this comes out as "like this" in Info, of course, which is just
confusing.
+and Info converts doubled single-quote characters to @sc{ascii}
+double-quotes: @address@hidden@address@hidden'@w{}'}} becomes
@address@hidden"@dots{}"}}.
+
address@hidden
+Use three hyphens in a row, @samp{---}, for a dash---like this. In
address@hidden, a single or double hyphen produces a printed dash that is
+shorter than the usual typeset dash. Info reduces three hyphens to two
+for display on the screen.
+
address@hidden
+To prevent a paragraph from being indented in the printed manual, put
+the command @code{@@noindent} on a line by itself before the
+paragraph.
+
address@hidden
+If you mark off a region of the Texinfo file with the @code{@@iftex}
+and @address@hidden@@end iftex}} commands, that region will appear only in
+the printed copy; in that region, you can use certain commands
+borrowed from plain @TeX{} that you cannot use in Info. Conversely,
+text surrounded by @code{@@ifnottex} and @code{@@end ifnottex} will
+appear in all output formats @emph{except} @TeX{}.
+
+Each of the other output formats (@code{html}, @code{info},
address@hidden) have an analogous pair of commands. @xref{Conditionals}.
address@hidden itemize
+
address@hidden Tabs; don't use!
address@hidden
address@hidden:} Do not use tab characters in a Texinfo file (except in
+verbatim modes)! @TeX{} uses variable-width fonts, which means that it
+is impractical at best to define a tab to work in all circumstances.
+Consequently, @TeX{} treats tabs like single spaces, and that is not
+what they look like. Furthermore, @code{makeinfo} does nothing special
+with tabs, and thus a tab character in your input file may appear
+differently in the output, for example, in indented text.
+
address@hidden
+To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple
+spaces when you press the @key{TAB} key.
+
address@hidden
+Also, you can run @code{untabify} in Emacs to convert tabs in a region
+to multiple spaces.
address@hidden quotation
+
+
address@hidden Comments
address@hidden Comments
+
address@hidden Comments
address@hidden comment
address@hidden c @r{(comment)}
+
+You can write comments in a Texinfo file that will not appear in
+either the Info file or the printed manual by using the
address@hidden@@comment} command (which may be abbreviated to @code{@@c}).
+Such comments are for the person who revises the Texinfo file. All the
+text on a line that follows either @code{@@comment} or @code{@@c} is a
+comment; the rest of the line does not appear in either the Info file
+or the printed manual.
+
+Often, you can write the @code{@@comment} or @code{@@c} in the middle of
+a line, and only the text that follows after the @code{@@comment} or
address@hidden@@c} command does not appear; but some commands, such as
address@hidden@@settitle} and @code{@@setfilename}, work on a whole line. You
+cannot use @code{@@comment} or @code{@@c} in a line beginning with such
+a command.
+
address@hidden Ignored text
address@hidden Unprocessed text
address@hidden ignore
+You can write long stretches of text that will not appear in either
+the Info file or the printed manual by using the @code{@@ignore} and
address@hidden@@end ignore} commands. Write each of these commands on a line
+of its own, starting each command at the beginning of the line. Text
+between these two commands does not appear in the processed output.
+You can use @code{@@ignore} and @code{@@end ignore} for writing
+comments.
+
+Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or
address@hidden@@ifclear} conditions is ignored in the sense that it will not
+contribute to the formatted output. However, @TeX{} and makeinfo must
+still parse the ignored text, in order to understand when to @emph{stop}
+ignoring text from the source file; that means that you may still get
+error messages if you have invalid Texinfo commands within ignored text.
+
+
address@hidden Minimum
address@hidden What a Texinfo File Must Have
address@hidden Minimal Texinfo file (requirements)
address@hidden Must have in Texinfo file
address@hidden Required in Texinfo file
address@hidden Texinfo file minimum
+
+By convention, the namea of a Texinfo file ends with (in order of
+preference) one of the extensions @file{.texinfo}, @file{.texi},
address@hidden, or @file{.tex}. The longer extensions are preferred since
+they describe more clearly to a human reader the nature of the file.
+The shorter extensions are for operating systems that cannot handle long
+file names.
+
+In order to be made into a printed manual and an Info file, a Texinfo
+file @strong{must} begin with lines like this:
+
address@hidden
address@hidden
+\input texinfo
+@@setfilename @var{info-file-name}
+@@settitle @var{name-of-manual}
address@hidden group
address@hidden example
+
address@hidden
+The contents of the file follow this beginning, and then you
address@hidden end a Texinfo file with a line like this:
+
address@hidden
+@@bye
address@hidden example
+
address@hidden \input @r{(raw @TeX{} startup)}
address@hidden
+Here's an explanation:
+
address@hidden @bullet
address@hidden
+The @samp{\input texinfo} line tells @TeX{} to use the
address@hidden file, which tells @TeX{} how to translate the Texinfo
+@@-commands into @TeX{} typesetting commands. (Note the use of the
+backslash, @samp{\}; this is correct for @TeX{}.)
+
address@hidden
+The @code{@@setfilename} line provides a name for the Info file and
+tells @TeX{} to open auxiliary files. @strong{All text before
address@hidden@@setfilename} is ignored!}
+
address@hidden
+The @code{@@settitle} line specifies a title for the page headers (or
+footers) of the printed manual, and the default document description for
+the @samp{<head>} in HTML format. Strictly speaking, @code{@@settitle}
+is optional---if you don't mind your document being titled `Untitled'.
+
address@hidden
+The @code{@@bye} line at the end of the file on a line of its own tells
+the formatters that the file is ended and to stop formatting.
+
address@hidden itemize
+
+Typically, you will not use quite such a spare format, but will include
+mode setting and start-of-header and end-of-header lines at the
+beginning of a Texinfo file, like this:
+
address@hidden
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename @var{info-file-name}
+@@settitle @var{name-of-manual}
+@@c %**end of header
address@hidden group
address@hidden example
+
address@hidden
+In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into
+Texinfo mode when you edit the file.
+
+The @code{@@c} lines which surround the @code{@@setfilename} and
address@hidden@@settitle} lines are optional, but you need them in order to
+run @TeX{} or Info on just part of the file. (@xref{Start of Header}.)
+
+Furthermore, you will usually provide a Texinfo file with a title page,
+indices, and the like, all of which are explained in this manual. But
+the minimum, which can be useful for short documents, is just the three
+lines at the beginning and the one line at the end.
+
+
address@hidden Six Parts
address@hidden Six Parts of a Texinfo File
+
+Generally, a Texinfo file contains more than the minimal beginning and
+end described in the previous section---it usually contains the six
+parts listed below. These are described fully in the following sections.
+
address@hidden @r
address@hidden 1. Header
+The @dfn{Header} names the file, tells @TeX{} which definitions file to
+use, and other such housekeeping tasks.
+
address@hidden 2. Summary and Copyright
+The @dfn{Summary and Copyright} segment describes the document and
+contains the copyright notice and copying permissions. This is done
+with the @code{@@copying} command.
+
address@hidden 3. Title and Copyright
+The @dfn{Title and Copyright} segment contains the title and copyright
+pages for the printed manual. The segment must be enclosed between
address@hidden@@titlepage} and @code{@@end titlepage} commands. The title and
+copyright page appear only in the printed manual.
+
address@hidden 4. `Top' Node and Master Menu
+The `Top' node starts off the online output; it does not appear in the
+printed manual. We recommend including the copying permissions here as
+well as the segments above. And it contains at least a top-level menu
+listing the chapters, and possibly a @dfn{Master Menu} listing all the
+nodes in the entire document.
+
address@hidden 5. Body
+The @dfn{Body} of the document is typically structured like a
+traditional book or encyclopedia, but it may be free form.
+
address@hidden 6. End
+The @dfn{End} segment contains commands for printing indices and
+generating the table of contents, and the @code{@@bye} command on a line
+of its own.
address@hidden table
+
+
address@hidden Short Sample
address@hidden A Short Sample Texinfo File
address@hidden Sample Texinfo file, with comments
+
+Here is a very short but complete Texinfo file, in the six conventional
+parts enumerated in the previous section, so you can see how Texinfo
+source appears in practice. The first three parts of the file, from
address@hidden texinfo} through to @samp{@@end titlepage}, look more
+intimidating than they are: most of the material is standard
+boilerplate; when writing a manual, you simply change the names as
+appropriate.
+
address@hidden a File}, for full documentation on the commands listed
+here. @xref{GNU Sample Texts}, for the full texts to be used in GNU manuals.
+
+In the following, the sample text is @emph{indented}; comments on it are
+not. The complete file, without interspersed comments, is shown in
address@hidden Sample Texinfo File}.
+
address@hidden Part 1: Header
+
address@hidden
+The header does not appear in either the Info file or the
+printed output. It sets various parameters, including the
+name of the Info file and the title used in the header.
+
address@hidden
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename sample.info
+@@settitle Sample Manual 1.0
+@@c %**end of header
address@hidden group
address@hidden example
+
address@hidden Part 2: Summary Description and Copyright
+
address@hidden
+A real manual includes more text here, according to the license under
+which it is distributed. @xref{GNU Sample Texts}.
+
address@hidden
address@hidden
+@@copying
+This is a short example of a complete Texinfo file, version 1.0.
+
+Copyright @@address@hidden@} 2002 Free Software Foundation, Inc.
+@@end copying
address@hidden group
address@hidden example
+
address@hidden Part 3: Titlepage, Contents, Copyright
+
address@hidden
+The titlepage segment does not appear in the online output, only in the
+printed manual. We use the @code{@@insertcopying} command to
+include the permission text from the previous section, instead of
+writing it out again; it is output on the back of the title page. The
address@hidden@@contents} command generates a table of contents.
+
address@hidden
address@hidden
+@@titlepage
+@@title Sample Title
address@hidden group
+
address@hidden
+@@c The following two commands start the copyright page.
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
+@@end titlepage
address@hidden group
+
+@@c Output the table of contents at the beginning.
+@@contents
address@hidden example
+
address@hidden Part 4: `Top' Node and Master Menu
+
address@hidden
+The `Top' node contains the master menu for the Info file. Since a
+printed manual uses a table of contents rather than a menu, the master
+menu appears only in online output. We also include the copying text
+again for the benefit of online readers. And since the copying text
+begins with a brief description of the manual, no other text is needed.
+
address@hidden
address@hidden
+@@ifnottex
+@@node Top
+@@end ifnottex
address@hidden group
address@hidden example
+
address@hidden
address@hidden
+@@insertcopying
+
+@@menu
+* First Chapter:: The first chapter is the
+ only chapter in this sample.
+* Index:: Complete index.
+@@end menu
address@hidden group
address@hidden example
+
+
address@hidden Part 5: The Body of the Document
+
address@hidden
+The body segment contains all the text of the document, but not the
+indices or table of contents. This example illustrates a node and a
+chapter containing an enumerated list.
+
address@hidden
address@hidden
+@@node First Chapter
+@@chapter First Chapter
+
+@@cindex chapter, first
address@hidden group
+
address@hidden
+This is the first chapter.
+@@cindex index entry, another
address@hidden group
+
address@hidden
+Here is a numbered list.
+
+@@enumerate
+@@item
+This is the first item.
+
+@@item
+This is the second item.
+@@end enumerate
address@hidden group
address@hidden example
+
+
address@hidden Part 6: The End of the Document
+
address@hidden
+The end segment contains commands for generating an index in a node and
+unnumbered chapter of its own, and the @code{@@bye} command that marks
+the end of the document.
+
address@hidden
address@hidden
+@@node Index
+@@unnumbered Index
address@hidden group
+
address@hidden
+@@printindex cp
+
+@@bye
address@hidden group
address@hidden example
+
+
address@hidden Some Results
+
+Here is what the contents of the first chapter of the sample look like:
+
address@hidden 1
address@hidden 700
address@hidden
+This is the first chapter.
+
+Here is a numbered list.
+
address@hidden
address@hidden
+This is the first item.
+
address@hidden
+This is the second item.
address@hidden enumerate
address@hidden quotation
+
+
address@hidden History
address@hidden History
+
address@hidden Stallman, Richard M.
address@hidden Chassell, Robert J.
address@hidden Fox, Brian
address@hidden Berry, Karl
+Richard M.@: Stallman invented the Texinfo format, wrote the initial
+processors, and created Edition 1.0 of this manual. @w{Robert J.@:}
+Chassell greatly revised and extended the manual, starting with Edition
+1.1. Brian Fox was responsible for the standalone Texinfo distribution
+until version 3.8, and wrote the standalone @command{makeinfo} and
address@hidden programs. Karl Berry has continued maintenance since
+Texinfo 3.8 (manual edition 2.22).
+
address@hidden Pinard, Fran@,{c}ois
address@hidden Zuhn, David D.
address@hidden Weisshaus, Melissa
address@hidden Zaretskii, Eli
address@hidden Schwab, Andreas
address@hidden Weinberg, Zack
+Our thanks go out to all who helped improve this work, particularly the
+indefatigable Eli Zaretskii and Andreas Schwab, who have provided
+patches beyond counting. Fran@,{c}ois Pinard and @w{David D.@: Zuhn},
+tirelessly recorded and reported mistakes and obscurities. Zack
+Weinberg did the impossible by implementing the macro syntax in
address@hidden Special thanks go to Melissa Weisshaus for her
+frequent reviews of nearly similar editions. Dozens of others have
+contributed patches and suggestions, they are gratefully acknowledged in
+the @file{ChangeLog} file. Our mistakes are our own.
+
address@hidden Scribe
address@hidden Reid, Brian
address@hidden History of Texinfo
address@hidden Texinfo history
+A bit of history: in the 1970's at CMU, Brian Reid developed a program
+and format named Scribe to mark up documents for printing. It used the
address@hidden@@} character to introduce commands, as Texinfo does. Much more
+consequentially, it strived to describe document contents rather than
+formatting, an idea wholeheartedly adopted by Texinfo.
+
address@hidden Bolio
address@hidden address@hidden
+Meanwhile, people at MIT developed another, not too dissimilar format
+called Bolio. This then was converted to using @TeX{} as its typesetting
+language: address@hidden The earliest address@hidden version seems to have
been
+0.02 on October 31, 1984.
+
address@hidden could only be used as a markup language for documents to be
+printed, not for online documents. Richard Stallman (RMS) worked on
+both Bolio and address@hidden He also developed a nifty on-line help format
+called Info, and then combined address@hidden and Info to create Texinfo, a
+mark up language for text that is intended to be read both online and
+as printed hard copy.
+
+
address@hidden Texinfo Mode
address@hidden Using Texinfo Mode
address@hidden Texinfo mode
address@hidden Mode, using Texinfo
address@hidden GNU Emacs
address@hidden Emacs
+
+You may edit a Texinfo file with any text editor you choose. A Texinfo
+file is no different from any other @sc{ascii} file. However, GNU Emacs
+comes with a special mode, called Texinfo mode, that provides Emacs
+commands and tools to help ease your work.
+
+This chapter describes features of GNU Emacs' Texinfo mode but not any
+features of the Texinfo formatting language. So if you are reading this
+manual straight through from the beginning, you may want to skim through
+this chapter briefly and come back to it after reading succeeding
+chapters which describe the Texinfo formatting language in detail.
+
address@hidden
+* 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.
address@hidden menu
+
address@hidden Texinfo Mode Overview, Emacs Editing, Texinfo Mode, Texinfo Mode
address@hidden Texinfo Mode Overview
+
+Texinfo mode provides special features for working with Texinfo
+files.
+You can:@refill
+
address@hidden @bullet
address@hidden
+Insert frequently used @@-commands. @refill
+
address@hidden
+Automatically create @code{@@node} lines.
+
address@hidden
+Show the structure of a Texinfo source address@hidden
+
address@hidden
+Automatically create or update the `Next',
+`Previous', and `Up' pointers of a node.
+
address@hidden
+Automatically create or update address@hidden
+
address@hidden
+Automatically create a master address@hidden
+
address@hidden
+Format a part or all of a file for address@hidden
+
address@hidden
+Typeset and print part or all of a address@hidden
address@hidden itemize
+
+Perhaps the two most helpful features are those for inserting frequently
+used @@-commands and for creating node pointers and address@hidden
+
address@hidden Emacs Editing, Inserting, Texinfo Mode Overview, Texinfo Mode
address@hidden The Usual GNU Emacs Editing Commands
+
+In most cases, the usual Text mode commands work the same in Texinfo
+mode as they do in Text mode. Texinfo mode adds new editing commands
+and tools to GNU Emacs' general purpose editing features. The major
+difference concerns filling. In Texinfo mode, the paragraph
+separation variable and syntax table are redefined so that Texinfo
+commands that should be on lines of their own are not inadvertently
+included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph})
+command will refill a paragraph but not mix an indexing command on a
+line adjacent to it into the address@hidden
+
+In addition, Texinfo mode sets the @code{page-delimiter} variable to
+the value of @code{texinfo-chapter-level-regexp}; by default, this is
+a regular expression matching the commands for chapters and their
+equivalents, such as appendices. With this value for the page
+delimiter, you can jump from chapter title to chapter title with the
address@hidden ]} (@code{forward-page}) and @kbd{C-x [}
+(@code{backward-page}) commands and narrow to a chapter with the
address@hidden p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs,
+The GNU Emacs Manual}, for details about the page commands.)@refill
+
+You may name a Texinfo file however you wish, but the convention is to
+end a Texinfo file name with one of the extensions
address@hidden, @file{.texi}, @file{.txi}, or @file{.tex}. A longer
+extension is preferred, since it is explicit, but a shorter extension
+may be necessary for operating systems that limit the length of file
+names. GNU Emacs automatically enters Texinfo mode when you visit a
+file with a @file{.texinfo}, @file{.texi} or @file{.txi}
+extension. Also, Emacs switches to Texinfo mode
+when you visit a
+file that has @samp{-*-texinfo-*-} in its first line. If ever you are
+in another mode and wish to switch to Texinfo mode, type @code{M-x
address@hidden
+
+Like all other Emacs features, you can customize or enhance Texinfo
+mode as you wish. In particular, the keybindings are very easy to
+change. The keybindings described here are the default or standard
address@hidden
+
address@hidden Inserting, Showing the Structure, Emacs Editing, Texinfo Mode
address@hidden node-name, next, previous, up
address@hidden Inserting Frequently Used Commands
address@hidden Inserting frequently used commands
address@hidden Frequently used commands, inserting
address@hidden Commands, inserting them
+
+Texinfo mode provides commands to insert various frequently used
+@@-commands into the buffer. You can use these commands to save
address@hidden
+
+The insert commands are invoked by typing @kbd{C-c} twice and then the
+first letter of the @@-command:@refill
+
address@hidden @kbd
address@hidden C-c C-c c
address@hidden M-x texinfo-insert-@@code
address@hidden texinfo-insert-@@code
+Insert @code{@@address@hidden@}} and put the
+cursor between the address@hidden
+
address@hidden C-c C-c d
address@hidden M-x texinfo-insert-@@dfn
address@hidden texinfo-insert-@@dfn
+Insert @code{@@address@hidden@}} and put the
+cursor between the address@hidden
+
address@hidden C-c C-c e
address@hidden M-x texinfo-insert-@@end
address@hidden texinfo-insert-@@end
+Insert @code{@@end} and attempt to insert the correct following word,
+such as @samp{example} or @samp{table}. (This command does not handle
+nested lists correctly, but inserts the word appropriate to the
+immediately preceding list.)@refill
+
address@hidden C-c C-c i
address@hidden M-x texinfo-insert-@@item
address@hidden texinfo-insert-@@item
+Insert @code{@@item} and put the
+cursor at the beginning of the next address@hidden
+
address@hidden C-c C-c k
address@hidden M-x texinfo-insert-@@kbd
address@hidden texinfo-insert-@@kbd
+Insert @code{@@address@hidden@}} and put the
+cursor between the address@hidden
+
address@hidden C-c C-c n
address@hidden M-x texinfo-insert-@@node
address@hidden texinfo-insert-@@node
+Insert @code{@@node} and a comment line
+listing the sequence for the `Next',
+`Previous', and `Up' nodes.
+Leave point after the @code{@@address@hidden
+
address@hidden C-c C-c o
address@hidden M-x texinfo-insert-@@noindent
address@hidden texinfo-insert-@@noindent
+Insert @code{@@noindent} and put the
+cursor at the beginning of the next address@hidden
+
address@hidden C-c C-c s
address@hidden M-x texinfo-insert-@@samp
address@hidden texinfo-insert-@@samp
+Insert @code{@@address@hidden@}} and put the
+cursor between the address@hidden
+
address@hidden C-c C-c t
address@hidden M-x texinfo-insert-@@table
address@hidden texinfo-insert-@@table
+Insert @code{@@table} followed by a @key{SPC}
+and leave the cursor after the @address@hidden
+
address@hidden C-c C-c v
address@hidden M-x texinfo-insert-@@var
address@hidden texinfo-insert-@@var
+Insert @code{@@address@hidden@}} and put the
+cursor between the address@hidden
+
address@hidden C-c C-c x
address@hidden M-x texinfo-insert-@@example
address@hidden texinfo-insert-@@example
+Insert @code{@@example} and put the
+cursor at the beginning of the next address@hidden
+
address@hidden address@hidden was the binding for texinfo-insert-braces;
address@hidden in Emacs 19, backward-paragraph will take this binding.
address@hidden C-c C-c @{
address@hidden M-x texinfo-insert-braces
address@hidden texinfo-insert-braces
+Insert @address@hidden@}} and put the cursor between the address@hidden
+
address@hidden C-c C-c @}
address@hidden C-c C-c ]
address@hidden M-x up-list
address@hidden up-list
+Move from between a pair of braces forward past the closing brace.
+Typing @kbd{C-c C-c ]} is easier than typing @kbd{C-c C-c @}}, which
+is, however, more mnemonic; hence the two keybindings. (Also, you can
+move out from between braces by typing @kbd{C-f}.)@refill
address@hidden table
+
+To put a command such as @address@hidden@@address@hidden@address@hidden around
an
address@hidden word, position the cursor in front of the word and type
address@hidden 1 C-c C-c c}. This makes it easy to edit existing plain text.
+The value of the prefix argument tells Emacs how many words following
+point to include between address@hidden for one word, @samp{2} for
+two words, and so on. Use a negative argument to enclose the previous
+word or words. If you do not specify a prefix argument, Emacs inserts
+the @@-command string and positions the cursor between the braces. This
+feature works only for those @@-commands that operate on a word or words
+within one line, such as @code{@@kbd} and @code{@@address@hidden
+
+This set of insert commands was created after analyzing the frequency
+with which different @@-commands are 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 @address@hidden
+
address@hidden texinfo-start-menu-description
address@hidden Menu description, start
address@hidden Description for menu, start
address@hidden C-c C-d} (@code{texinfo-start-menu-description}) is an insert
+command that works differently from the other insert commands. It
+inserts a node's section or chapter title in the space for the
+description in a menu entry line. (A menu entry has three parts, the
+entry name, the node name, and the description. Only the node name is
+required, but a description helps explain what the node is about.
address@hidden Parts, , The Parts of a Menu}.)@refill
+
+To use @code{texinfo-start-menu-description}, position point in a menu
+entry line and type @kbd{C-c C-c C-d}. The command looks for and copies
+the title that goes with the node name, and inserts the title as a
+description; it positions point at beginning of the inserted text so you
+can edit it. The function does not insert the title if the menu entry
+line already contains a address@hidden
+
+This command is only an aid to writing descriptions; it does not do the
+whole job. You must edit the inserted text since a title tends to use
+the same words as a node name but a useful description uses different
address@hidden
+
address@hidden Showing the Structure, Updating Nodes and Menus, Inserting,
Texinfo Mode
address@hidden node-name, next, previous, up
address@hidden Showing the Section Structure of a File
address@hidden Showing the section structure of a file
address@hidden Section structure of a file, showing it
address@hidden Structure of a file, showing it
address@hidden Outline of file structure, showing it
address@hidden Contents-like outline of file structure
address@hidden File section structure, showing it
address@hidden Texinfo file section structure, showing it
+
+You can show the section structure of a Texinfo file by using the
address@hidden C-s} command (@code{texinfo-show-structure}). This command
+shows the section structure of a Texinfo file by listing the lines
+that begin with the @@-commands for @code{@@chapter},
address@hidden@@section}, and the like. It constructs what amounts
+to a table of contents. These lines are displayed in another buffer
+called the @samp{*Occur*} buffer. In that buffer, 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 address@hidden
+
address@hidden @kbd
address@hidden C-c C-s
address@hidden M-x texinfo-show-structure
address@hidden texinfo-show-structure
+Show the @code{@@chapter}, @code{@@section}, and such lines of a
+Texinfo address@hidden
+
address@hidden C-c C-c
address@hidden M-x occur-mode-goto-occurrence
address@hidden occur-mode-goto-occurrence
+Go to the line in the Texinfo file corresponding to the line under the
+cursor in the @file{*Occur*} address@hidden
address@hidden table
+
+If you call @code{texinfo-show-structure} with a prefix argument by
+typing @address@hidden C-c C-s}}, it will list not only those lines with the
+@@-commands for @code{@@chapter}, @code{@@section}, and the like, but
+also the @code{@@node} lines. You can use @code{texinfo-show-structure}
+with a prefix argument to check whether the `Next', `Previous', and `Up'
+pointers of an @code{@@node} line are correct.
+
+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 by using the
address@hidden n n} (@code{narrow-to-region}) command and
address@hidden will work on only that region. To see
+the whole buffer again, use @address@hidden n w}} (@code{widen}).
+(@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more
+information about the narrowing commands.)@refill
+
address@hidden page-delimiter
address@hidden Page delimiter in Texinfo mode
+In addition to providing the @code{texinfo-show-structure} command,
+Texinfo mode sets the value of the page delimiter variable to match
+the chapter-level @@-commands. This enables you to use the @kbd{C-x
+]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page})
+commands to move forward and backward by chapter, and to use the
address@hidden p} (@code{narrow-to-page}) command to narrow to a chapter.
address@hidden, , , emacs, The GNU Emacs Manual}, for more information
+about the page address@hidden
+
address@hidden Updating Nodes and Menus, Info Formatting, Showing the
Structure, Texinfo Mode
address@hidden node-name, next, previous, up
address@hidden Updating Nodes and Menus
address@hidden Updating nodes and menus
address@hidden Create nodes, menus automatically
address@hidden Insert nodes, menus automatically
address@hidden Automatically insert nodes, menus
+
+Texinfo mode provides commands for automatically creating or updating
+menus and node pointers. The commands are called ``update'' commands
+because their most frequent use is for updating a Texinfo file after you
+have worked on it; but you can use them to insert the `Next',
+`Previous', and `Up' pointers into an @code{@@node} line that has none
+and to create menus in a file that has none.
+
+If you do not use the updating commands, you need to write menus and
+node pointers by hand, which is a tedious address@hidden
+
address@hidden
+* 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.
address@hidden menu
+
address@hidden Updating Commands, Updating Requirements, Updating Nodes and
Menus, Updating Nodes and Menus
address@hidden The Updating Commands
+
+You can use the updating commands to:@refill
+
address@hidden @bullet
address@hidden
+insert or update the `Next', `Previous', and `Up' pointers of a
+node,@refill
+
address@hidden
+insert or update the menu for a section, address@hidden
+
address@hidden
+create a master menu for a Texinfo source address@hidden
address@hidden itemize
+
+You can also use the commands to update all the nodes and menus in a
+region or in a whole Texinfo address@hidden
+
+The updating commands work only with conventional Texinfo files, which
+are structured hierarchically like books. In such files, a structuring
+command line must follow closely after each @code{@@node} line, except
+for the `Top' @code{@@node} line. (A @dfn{structuring command line} is
+a line beginning with @code{@@chapter}, @code{@@section}, or other
+similar command.)
+
+You can write the structuring command line on the line that follows
+immediately after an @code{@@node} line or else on the line that
+follows after a single @code{@@comment} line or a single
address@hidden@@ifinfo} line. You cannot interpose more than one line between
+the @code{@@node} line and the structuring command line; and you may
+interpose only an @code{@@comment} line or an @code{@@ifinfo} line.
+
+Commands which work on a whole buffer require that the `Top' node be
+followed by a node with an @code{@@chapter} or equivalent-level command.
+The menu updating commands will not create a main or master menu for a
+Texinfo file that has only @code{@@chapter}-level nodes! The menu
+updating commands only create menus @emph{within} nodes for lower level
+nodes. To create a menu of chapters, you must provide a `Top'
+node.
+
+The menu updating commands remove menu entries that refer to other Info
+files since they do not refer to nodes within the current buffer. This
+is a deficiency. Rather than use menu entries, you can use cross
+references to refer to other Info files. None of the updating commands
+affect cross address@hidden
+
+Texinfo mode has five updating commands that are used most often: two
+are for updating the node pointers or menu of a single node (or a
+region); two are for updating every node pointer and menu in a file;
+and one, the @code{texinfo-master-menu} command, is for creating a
+master menu for a complete file, and optionally, for updating every
+node and menu in the whole Texinfo address@hidden
+
+The @code{texinfo-master-menu} command is the primary command:@refill
+
address@hidden @kbd
address@hidden C-c C-u m
address@hidden M-x texinfo-master-menu
address@hidden texinfo-master-menu
+Create or update a master menu that includes all the other menus
+(incorporating the descriptions from pre-existing menus, if
+any)address@hidden
+
+With an argument (prefix argument, @kbd{C-u,} if interactive), first create or
+update all the nodes and all the regular menus in the buffer before
+constructing the master menu. (@xref{The Top Node, , The Top Node and
+Master Menu}, for more about a master menu.)@refill
+
+For @code{texinfo-master-menu} to work, the Texinfo file must have a
+`Top' node and at least one subsequent address@hidden
+
+After extensively editing a Texinfo file, you can type the following:
+
address@hidden
+C-u M-x texinfo-master-menu
address@hidden or
+C-u C-c C-u m
address@hidden example
+
address@hidden
+This updates all the nodes and menus completely and all at address@hidden
address@hidden table
+
+The other major updating commands do smaller jobs and are designed for
+the person who updates nodes and menus as he or she writes a Texinfo
address@hidden
+
address@hidden 1000
+The commands are:@refill
+
address@hidden @kbd
address@hidden C-c C-u C-n
address@hidden M-x texinfo-update-node
address@hidden texinfo-update-node
+Insert the `Next', `Previous', and `Up' pointers for the node that point is
+within (i.e., for the @code{@@node} line preceding point). If the
address@hidden@@node} line has pre-existing `Next', `Previous', or `Up'
+pointers in it, the old pointers are removed and new ones inserted.
+With an argument (prefix argument, @kbd{C-u}, if interactive), this command
+updates all @code{@@node} lines in the region (which is the text
+between point and mark)address@hidden
+
address@hidden C-c C-u C-m
address@hidden M-x texinfo-make-menu
address@hidden texinfo-make-menu
+Create or update the menu in the node that point is within.
+With an argument (@kbd{C-u} as prefix argument, if
+interactive), the command makes or updates menus for the
+nodes which are either within or a part of the
address@hidden
+
+Whenever @code{texinfo-make-menu} updates an existing menu, the
+descriptions from that menu are incorporated into the new menu. This
+is done by copying descriptions from the existing menu to the entries
+in the new menu that have the same node names. If the node names are
+different, the descriptions are not copied to the new address@hidden
+
address@hidden C-c C-u C-e
address@hidden M-x texinfo-every-node-update
address@hidden texinfo-every-node-update
+Insert or update the `Next', `Previous', and `Up' pointers for every
+node in the address@hidden
+
address@hidden C-c C-u C-a
address@hidden M-x texinfo-all-menus-update
address@hidden texinfo-all-menus-update
+Create or update all the menus in the buffer. With an argument
+(@kbd{C-u} as prefix argument, if interactive), first insert
+or update all the node
+pointers before working on the address@hidden
+
+If a master menu exists, the @code{texinfo-all-menus-update} command
+updates it; but the command does not create a new master menu if none
+already exists. (Use the @code{texinfo-master-menu} command for
+that.)@refill
+
+When working on a document that does not merit a master menu, you can
+type the following:
+
address@hidden
+C-u C-c C-u C-a
address@hidden or
+C-u M-x texinfo-all-menus-update
address@hidden example
+
address@hidden
+This updates all the nodes and address@hidden
address@hidden table
+
+The @code{texinfo-column-for-description} variable specifies the
+column to which menu descriptions are indented. By default, the value
+is 32 although it is often useful to reduce it to as low as 24. You
+can set the variable with the @kbd{M-x edit-options} command
+(@pxref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs
+Manual}) or with the @kbd{M-x set-variable} command (@pxref{Examining,
+, Examining and Setting Variables, emacs, The GNU Emacs
+Manual})address@hidden
+
+Also, the @code{texinfo-indent-menu-description} command may be used to
+indent existing menu descriptions to a specified column. Finally, if
+you wish, you can use the @code{texinfo-insert-node-lines} command to
+insert missing @code{@@node} lines into a file. (@xref{Other Updating
+Commands}, for more information.)@refill
+
address@hidden Updating Requirements
address@hidden Updating Requirements
address@hidden Updating requirements
address@hidden Requirements for updating commands
+
+To use the updating commands, you must organize the Texinfo file
+hierarchically with chapters, sections, subsections, and the like.
+When you construct the hierarchy of the manual, do not `jump down'
+more than one level at a time: you can follow the `Top' node with a
+chapter, but not with a section; you can follow a chapter with a
+section, but not with a subsection. However, you may `jump up' any
+number of levels at one time---for example, from a subsection to a
address@hidden
+
+Each @code{@@node} line, with the exception of the line for the `Top'
+node, must be followed by a line with a structuring command such as
address@hidden@@chapter}, @code{@@section}, or
address@hidden@@address@hidden
+
+Each @code{@@node} line/structuring-command line combination
+must look either like this:
+
address@hidden
address@hidden
+@@node Comments, Minimum, Conventions, Overview
+@@comment node-name, next, previous, up
+@@section Comments
address@hidden group
address@hidden example
+
+or like this (without the @code{@@comment} line):
+
address@hidden
address@hidden
+@@node Comments, Minimum, Conventions, Overview
+@@section Comments
address@hidden group
address@hidden example
+
+or like this (without the explicit node pointers):
+
address@hidden
address@hidden
+@@node Comments
+@@section Comments
address@hidden group
address@hidden example
+
address@hidden
+In this example, `Comments' is the name of both the node and the
+section. The next node is called `Minimum' and the previous node is
+called `Conventions'. The `Comments' section is within the `Overview'
+node, which is specified by the `Up' pointer. (Instead of an
address@hidden@@comment} line, you may also write an @code{@@ifinfo} line.)
+
+If a file has a `Top' node, it must be called @samp{top} or @samp{Top}
+and be the first node in the file.
+
+The menu updating commands create a menu of sections within a chapter,
+a menu of subsections within a section, and so on. This means that
+you must have a `Top' node if you want a menu of address@hidden
+
+Incidentally, the @code{makeinfo} command will create an Info file for a
+hierarchically organized Texinfo file that lacks `Next', `Previous' and
+`Up' pointers. Thus, if you can be sure that your Texinfo file will be
+formatted with @code{makeinfo}, you have no need for the update node
+commands. (@xref{Creating an Info File}, for more information about
address@hidden) However, both @code{makeinfo} and the
address@hidden@dots{}} commands require that you insert menus in
+the file.
+
+
address@hidden Other Updating Commands
address@hidden Other Updating Commands
+
+In addition to the five major updating commands, Texinfo mode
+possesses several less frequently used updating commands:@refill
+
address@hidden @kbd
address@hidden M-x texinfo-insert-node-lines
address@hidden texinfo-insert-node-lines
+Insert @code{@@node} lines before the @code{@@chapter},
address@hidden@@section}, and other sectioning commands wherever they are
+missing throughout a region in a Texinfo address@hidden
+
+With an argument (@kbd{C-u} as prefix argument, if interactive), the
address@hidden command not only inserts
address@hidden@@node} lines but also inserts the chapter or section titles as
+the names of the corresponding nodes. In addition, it inserts the
+titles as node names in pre-existing @code{@@node} lines that lack
+names. Since node names should be more concise than section or
+chapter titles, you must manually edit node names so address@hidden
+
+For example, the following marks a whole buffer as a region and inserts
address@hidden@@node} lines and titles throughout:@refill
+
address@hidden
+C-x h C-u M-x texinfo-insert-node-lines
address@hidden example
+
+This command inserts titles as node names in @code{@@node} lines; the
address@hidden command (@pxref{Inserting,
+Inserting Frequently Used Commands}) inserts titles as descriptions in
+menu entries, a different action. However, in both cases, you need to
+edit the inserted text.
+
address@hidden M-x texinfo-multiple-files-update
address@hidden texinfo-multiple-files-update @r{(in brief)}
+Update nodes and menus in a document built from several separate files.
+With @kbd{C-u} as a prefix argument, create and insert a master menu in
+the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first
+update all the menus and all the `Next', `Previous', and `Up' pointers
+of all the included files before creating and inserting a master menu in
+the outer file. The @code{texinfo-multiple-files-update} command is
+described in the appendix on @code{@@include} files.
address@hidden@refill
+
address@hidden M-x texinfo-indent-menu-description
address@hidden texinfo-indent-menu-description
+Indent every description in the menu following point to the specified
+column. You can use this command to give yourself more space for
+descriptions. With an argument (@kbd{C-u} as prefix argument, if
+interactive), the @code{texinfo-indent-menu-description} command indents
+every description in every menu in the region. However, this command
+does not indent the second and subsequent lines of a multi-line
address@hidden
+
address@hidden M-x texinfo-sequential-node-update
address@hidden texinfo-sequential-node-update
+Insert the names of the nodes immediately following and preceding the
+current node as the `Next' or `Previous' pointers regardless of those
+nodes' hierarchical level. This means that the `Next' node of a
+subsection may well be the next chapter. Sequentially ordered nodes are
+useful for novels and other documents that you read through
+sequentially. (However, in Info, the @kbd{g *} command lets
+you look through the file sequentially, so sequentially ordered nodes
+are not strictly necessary.) With an argument (prefix argument, if
+interactive), the @code{texinfo-sequential-node-update} command
+sequentially updates all the nodes in the address@hidden
address@hidden table
+
address@hidden Info Formatting, Printing, Updating Nodes and Menus, Texinfo Mode
address@hidden node-name, next, previous, up
address@hidden Formatting for Info
address@hidden Formatting for Info
address@hidden Running an Info formatter
address@hidden Info formatting
+
+Texinfo mode provides several commands for formatting part or all of a
+Texinfo file for Info. Often, when you are writing a document, you
+want to format only part of a file---that is, a address@hidden
+
+You can use either the @code{texinfo-format-region} or the
address@hidden command to format a region:@refill
+
address@hidden @kbd
address@hidden texinfo-format-region
address@hidden C-c C-e C-r
address@hidden M-x texinfo-format-region
address@hidden C-c C-m C-r
address@hidden M-x makeinfo-region
+Format the current region for address@hidden
address@hidden table
+
+You can use either the @code{texinfo-format-buffer} or the
address@hidden command to format a whole buffer:@refill
+
address@hidden @kbd
address@hidden texinfo-format-buffer
address@hidden C-c C-e C-b
address@hidden M-x texinfo-format-buffer
address@hidden C-c C-m C-b
address@hidden M-x makeinfo-buffer
+Format the current buffer for address@hidden
address@hidden table
+
address@hidden 1000
+For example, after writing a Texinfo file, you can type the following:
+
address@hidden
+C-u C-c C-u m
address@hidden or
+C-u M-x texinfo-master-menu
address@hidden example
+
address@hidden
+This updates all the nodes and menus. Then type the following to create
+an Info file:
+
address@hidden
+C-c C-m C-b
address@hidden or
+M-x makeinfo-buffer
address@hidden example
+
+For @TeX{} or the Info formatting commands to work, the file @emph{must}
+include a line that has @code{@@setfilename} in its header.
+
address@hidden an Info File}, for details about Info address@hidden
+
address@hidden Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode
address@hidden node-name, next, previous, up
address@hidden Formatting and Printing
address@hidden Formatting for printing
address@hidden Printing a region or buffer
address@hidden Region formatting and printing
address@hidden Buffer formatting and printing
address@hidden Part of file formatting and printing
+
+Typesetting and printing a Texinfo file is a multi-step process in which
+you first create a file for printing (called a DVI file), and then
+print the file. Optionally, you may also create indices. To do this,
+you must run the @code{texindex} command after first running the
address@hidden typesetting command; and then you must run the @code{tex}
+command again. Or else run the @code{texi2dvi} command which
+automatically creates indices as needed (@pxref{Format with texi2dvi}).
+
+Often, when you are writing a document, you want to typeset and print
+only part of a file to see what it will look like. You can use the
address@hidden and related commands for this purpose. Use
+the @code{texinfo-tex-buffer} command to format all of a
address@hidden
+
address@hidden @kbd
address@hidden C-c C-t C-b
address@hidden M-x texinfo-tex-buffer
address@hidden texinfo-tex-buffer
+Run @code{texi2dvi} on the buffer. In addition to running @TeX{} on the
+buffer, this command automatically creates or updates indices as
address@hidden
+
address@hidden C-c C-t C-r
address@hidden M-x texinfo-tex-region
address@hidden texinfo-tex-region
+Run @TeX{} on the address@hidden
+
address@hidden C-c C-t C-i
address@hidden M-x texinfo-texindex
+Run @code{texindex} to sort the indices of a Texinfo file formatted with
address@hidden The @code{texinfo-tex-region} command does
+not run @code{texindex} automatically; it only runs the @code{tex}
+typesetting command. You must run the @code{texinfo-tex-region} command
+a second time after sorting the raw index files with the @code{texindex}
+command. (Usually, you do not format an index when you format a region,
+only when you format a buffer. Now that the @code{texi2dvi} command
+exists, there is little or no need for this command.)@refill
+
address@hidden C-c C-t C-p
address@hidden M-x texinfo-tex-print
address@hidden texinfo-tex-print
+Print the file (or the part of the file) previously formatted with
address@hidden or @address@hidden
address@hidden table
+
+For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the
+file @emph{must} start with a @samp{\input texinfo} line and must
+include an @code{@@settitle} line. The file must end with @code{@@bye}
+on a line by itself. (When you use @code{texinfo-tex-region}, you must
+surround the @code{@@settitle} line with start-of-header and
+end-of-header lines.)@refill
+
address@hidden, for a description of the other @TeX{} related
+commands, such as @address@hidden
+
address@hidden Texinfo Mode Summary, , Printing, Texinfo Mode
address@hidden node-name, next, previous, up
address@hidden Texinfo Mode Summary
+
+In Texinfo mode, each set of commands has default keybindings that
+begin with the same keys. All the commands that are custom-created
+for Texinfo mode begin with @kbd{C-c}. The keys are somewhat
address@hidden
+
address@hidden Insert Commands
+
+The insert commands are invoked by typing @kbd{C-c} twice and then the
+first letter of the @@-command to be inserted. (It might make more
+sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but
address@hidden C-c} is quick to type.)@refill
+
address@hidden
+C-c C-c c @r{Insert} @samp{@@code}.
+C-c C-c d @r{Insert} @samp{@@dfn}.
+C-c C-c e @r{Insert} @samp{@@end}.
+C-c C-c i @r{Insert} @samp{@@item}.
+C-c C-c n @r{Insert} @samp{@@node}.
+C-c C-c s @r{Insert} @samp{@@samp}.
+C-c C-c v @r{Insert} @samp{@@var}.
+C-c C-c @{ @r{Insert braces.}
+C-c C-c ]
+C-c C-c @} @r{Move out of enclosing braces.}
+
address@hidden
+C-c C-c C-d @r{Insert a node's section title}
+ @r{in the space for the description}
+ @r{in a menu entry line.}
address@hidden group
address@hidden example
+
address@hidden Show Structure
+
+The @code{texinfo-show-structure} command is often used within a
+narrowed address@hidden
+
address@hidden
+C-c C-s @r{List all the headings.}
address@hidden example
+
address@hidden The Master Update Command
+
+The @code{texinfo-master-menu} command creates a master menu; and can
+be used to update every node and menu in a file as address@hidden
+
address@hidden Probably should use @tables in this section.
address@hidden
address@hidden
+C-c C-u m
+M-x texinfo-master-menu
+ @r{Create or update a master menu.}
address@hidden group
+
address@hidden
+C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first}
+ @r{create or update all nodes and regular}
+ @r{menus, and then create a master menu.}
address@hidden group
address@hidden example
+
address@hidden Update Pointers
+
+The update pointer commands are invoked by typing @kbd{C-c C-u} and
+then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for
address@hidden@refill
+
address@hidden
+C-c C-u C-n @r{Update a node.}
+C-c C-u C-e @r{Update every node in the buffer.}
address@hidden example
+
address@hidden Update Menus
+
+Invoke the update menu commands by typing @kbd{C-c C-u}
+and then either @kbd{C-m} for @code{texinfo-make-menu} or
address@hidden for @code{texinfo-all-menus-update}. To update
+both nodes and menus at the same time, precede @kbd{C-c C-u
+C-a} with @address@hidden
+
address@hidden
+C-c C-u C-m @r{Make or update a menu.}
+
address@hidden
+C-c C-u C-a @r{Make or update all}
+ @r{menus in a buffer.}
address@hidden group
+
address@hidden
+C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,}
+ @r{first create or update all nodes and}
+ @r{then create or update all menus.}
address@hidden group
address@hidden example
+
address@hidden Format for Info
+
+The Info formatting commands that are written in Emacs Lisp are
+invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region
+or @kbd{C-b} for the whole address@hidden
+
+The Info formatting commands that are written in C and based on the
address@hidden program are invoked by typing @kbd{C-c C-m} and then
+either @kbd{C-r} for a region or @kbd{C-b} for the whole address@hidden
+
address@hidden 800
address@hidden
+Use the @address@hidden commands:
+
address@hidden
address@hidden
+C-c C-e C-r @r{Format the region.}
+C-c C-e C-b @r{Format the buffer.}
address@hidden group
address@hidden example
+
address@hidden 750
address@hidden
+Use @code{makeinfo}:
+
address@hidden
+C-c C-m C-r @r{Format the region.}
+C-c C-m C-b @r{Format the buffer.}
+C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.}
+C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.}
address@hidden example
+
address@hidden Typeset and Print
+
+The @TeX{} typesetting and printing commands are invoked by typing
address@hidden C-t} and then another control command: @kbd{C-r} for
address@hidden, @kbd{C-b} for @code{texinfo-tex-buffer},
+and so address@hidden
+
address@hidden
+C-c C-t C-r @r{Run @TeX{} on the region.}
+C-c C-t C-b @r{Run} @code{texi2dvi} @r{on the buffer.}
+C-c C-t C-i @r{Run} @code{texindex}.
+C-c C-t C-p @r{Print the DVI file.}
+C-c C-t C-q @r{Show the print queue.}
+C-c C-t C-d @r{Delete a job from the print queue.}
+C-c C-t C-k @r{Kill the current @TeX{} formatting job.}
+C-c C-t C-x @r{Quit a currently stopped @TeX{} formatting job.}
+C-c C-t C-l @r{Recenter the output buffer.}
address@hidden example
+
address@hidden Other Updating Commands
+
+The remaining updating commands do not have standard keybindings because
+they are rarely used.
+
address@hidden
address@hidden
+M-x texinfo-insert-node-lines
+ @r{Insert missing @code{@@node} lines in region.}
+ @r{With @kbd{C-u} as a prefix argument,}
+ @r{use section titles as node names.}
address@hidden group
+
address@hidden
+M-x texinfo-multiple-files-update
+ @r{Update a multi-file document.}
+ @r{With @kbd{C-u 2} as a prefix argument,}
+ @r{create or update all nodes and menus}
+ @r{in all included files first.}
address@hidden group
+
address@hidden
+M-x texinfo-indent-menu-description
+ @r{Indent descriptions.}
address@hidden group
+
address@hidden
+M-x texinfo-sequential-node-update
+ @r{Insert node pointers in strict sequence.}
address@hidden group
address@hidden example
+
+
address@hidden Beginning a File
address@hidden Beginning a Texinfo File
address@hidden Beginning a Texinfo file
address@hidden Texinfo file beginning
address@hidden File beginning
+
+Certain pieces of information must be provided at the beginning of a
+Texinfo file, such as the name for the output file(s), the title of the
+document, and the Top node.
+
+This chapter expands on the minimal complete Texinfo source file
+previously given (@pxref{Six Parts}).
+
address@hidden
+* 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.
+* The Top Node:: Creating the `Top' node and master menu.
+* Global Document Commands:: Affecting formatting throughout.
+* Software Copying Permissions:: Ensure that you and others continue to
+ have the right to use and share software.
address@hidden menu
+
+
address@hidden Sample Beginning
address@hidden Sample Texinfo File Beginning
+
address@hidden Example beginning of Texinfo file
+
+The following sample shows what is needed. The elements given here are
+explained in more detail in the following sections. Other commands are
+often included at the beginning of Texinfo files, but the ones here are
+the most critical.
+
address@hidden Sample Texts}, for the full texts to be used in GNU manuals.
+
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename @var{infoname}.info
+@@settitle @var{name-of-manual} @var{version}
+@@c %**end of header
+
+@@copying
+This manual is for @var{program}, version @var{version}.
+
+Copyright @@address@hidden@} @var{years} @var{copyright-owner}.
+
address@hidden
+@@quotation
+Permission is granted to @dots{}
+@@end quotation
+@@end copying
address@hidden group
+
address@hidden
+@@titlepage
+@@title @var{name-of-manual-when-printed}
+@@subtitle @var{subtitle-if-any}
+@@subtitle @var{second-subtitle}
+@@author @var{author}
address@hidden group
+
address@hidden
+@@c The following two commands
+@@c start the copyright page.
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
address@hidden group
+
+Published by @dots{}
+@@end titlepage
+
+@@c So the toc is printed in the right place.
+@@contents
+
+@@ifnottex
+@@node Top
+@@top @var{title}
+
+@@insertcopying
+@@end ifnottex
+
address@hidden
+@@menu
+* First Chapter:: Getting started @dots{}
+* Second Chapter:: @dots{}
+ @dots{}
+* Copying:: Your rights and freedoms.
+@@end menu
address@hidden group
+
address@hidden
+@@node First Chapter
+@@chapter First Chapter
+
+@@cindex first chapter
+@@cindex chapter, first
address@hidden
address@hidden group
address@hidden example
+
+
address@hidden Texinfo File Header
address@hidden Texinfo File Header
address@hidden Header for Texinfo files
address@hidden Texinfo file header
+
+Texinfo files start with at least three lines that provide Info and
address@hidden with necessary information. These are the @code{\input texinfo}
+line, the @code{@@settitle} line, and the @code{@@setfilename} line.
+
+Also, if you want to format just part of the Texinfo file, you must
+write the @code{@@settitle} and @code{@@setfilename} lines between
+start-of-header and end-of-header lines. The start- and end-of-header
+lines are optional, but they do no harm, so you might as well always
+include them.
+
+Any command that affects document formatting as a whole makes sense to
+include in the header. @code{@@synindex} (@pxref{synindex}), for
+instance, is another command often included in the header. @xref{GNU
+Sample Texts}, for complete sample texts.
+
+Thus, the beginning of a Texinfo file generally looks like this:
+
address@hidden
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename sample.info
+@@settitle Sample Manual 1.0
+@@c %**end of header
address@hidden group
address@hidden example
+
address@hidden
+* First Line:: The first line of a Texinfo file.
+* Start of Header:: Formatting a region requires this.
+* setfilename:: Tell Info the name of the Info file.
+* settitle:: Create a title for the printed work.
+* End of Header:: Formatting a region requires this.
address@hidden menu
+
+
address@hidden First Line
address@hidden The First Line of a Texinfo File
address@hidden First line of a Texinfo file
address@hidden Beginning line of a Texinfo file
address@hidden Header 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:
+
address@hidden
+\input texinfo @@c -*-texinfo-*-
address@hidden example
+
address@hidden
+This line serves two functions:
+
address@hidden
address@hidden
+When the file is processed by @TeX{}, the @samp{\input texinfo} command
+tells @TeX{} to load the macros needed for processing a Texinfo file.
+These are in a file called @file{texinfo.tex}, which should have been
+installed on your system along with either the @TeX{} or Texinfo
+software. @TeX{} uses the backslash, @samp{\}, to mark the beginning of
+a command, exactly as Texinfo uses @samp{@@}. The @file{texinfo.tex}
+file causes the switch from @samp{\} to @samp{@@}; before the switch
+occurs, @TeX{} requires @samp{\}, which is why it appears at the
+beginning of the file.
+
address@hidden
+When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode
+specification tells Emacs to use Texinfo mode.
address@hidden enumerate
+
+
address@hidden Start of Header
address@hidden Start of Header
address@hidden Start of header line
+
+A start-of-header line is a Texinfo comment that looks like this:
+
address@hidden
+@@c %**start of header
address@hidden example
+
+Write the start-of-header line on the second line of a Texinfo file.
+Follow the start-of-header line with @code{@@setfilename} and
address@hidden@@settitle} lines and, optionally, with other commands that
+globally affect the document formatting, such as @code{@@synindex} or
address@hidden@@footnotestyle}; and then by an end-of-header line (@pxref{End of
+Header}).
+
+The start- and end-of-header lines allow you to format only part of a
+Texinfo file for Info or printing. @xref{texinfo-format commands}.
+
+The odd string of characters, @samp{%**}, is to ensure that no other
+comment is accidentally taken for a start-of-header line. You can
+change it if you wish by setting the @code{tex-start-of-header} and/or
address@hidden Emacs variables. @xref{Texinfo Mode Printing}.
+
+
address@hidden setfilename
address@hidden @code{@@setfilename}: Set the output file name
address@hidden setfilename
address@hidden Texinfo requires @code{@@setfilename}
+
+In order to serve as the primary input file for either @code{makeinfo}
+or @TeX{}, a Texinfo file must contain a line that looks like this:
+
address@hidden
+@@setfilename @var{info-file-name}
address@hidden example
+
+Write the @code{@@setfilename} command at the beginning of a line and
+follow it on the same line by the Info file name. Do not write anything
+else on the line; anything on the line after the command is considered
+part of the file name, including what would otherwise be a
+comment.
+
address@hidden Ignored before @code{@@setfilename}
address@hidden @samp{\input} source line ignored
+The Info formatting commands ignore everything written before the
address@hidden@@setfilename} line, which is why the very first line of
+the file (the @code{\input} line) does not show up in the output.
+
+The @code{@@setfilename} line specifies the name of the output file to
+be generated. This name must be different from the name of the Texinfo
+file. There are two conventions for choosing the name: you can either
+remove the extension (such as @samp{.texi}) entirely from the input file
+name, or, preferably, replace it with the @samp{.info} extension.
+
address@hidden Length of file names
address@hidden File name collision
address@hidden Info file name, choosing
+Although an explicit @samp{.info} extension is preferable, some
+operating systems cannot handle long file names. You can run into a
+problem even when the file name you specify is itself short enough.
+This occurs because the Info formatters split a long Info file into
+short indirect subfiles, and name them by appending @samp{-1},
address@hidden, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original
+file name. (@xref{Tag and Split Files}.) The subfile name
address@hidden, for example, is too long for old systems with a
+14-character limit on filenames; so the Info file name for this document
+is @file{texinfo} rather than @file{texinfo.info}. When @code{makeinfo}
+is running on operating systems such as MS-DOS which impose severe
+limits on file names, it may remove some characters from the original
+file name to leave enough space for the subfile suffix, thus producing
+files named @file{texin-10}, @file{gcc.i12}, etc.
+
+When producing HTML output, @code{makeinfo} will replace any extension
+with @samp{html}, or add @samp{.html} if the given name has no
+extension.
+
address@hidden texinfo.cnf
+The @code{@@setfilename} line produces no output when you typeset a
+manual with @TeX{}, but it is nevertheless essential: it opens the
+index, cross-reference, and other auxiliary files used by Texinfo, and
+also reads @file{texinfo.cnf} if that file is present on your system
+(@pxref{Preparing for TeX,, Preparing for @TeX{}}).
+
+
address@hidden settitle
address@hidden @code{@@settitle}: Set the document title
address@hidden settitle
+
+In order to be made into a printed manual, a Texinfo file must contain
+a line that looks like this:
+
address@hidden
+@@settitle @var{title}
address@hidden example
+
+Write the @code{@@settitle} command at the beginning of a line and
+follow it on the same line by the title. This tells @TeX{} the title to
+use in a header or footer. Do not write anything else on the line;
+anything on the line after the command is considered part of the title,
+including what would otherwise be a comment.
+
+The @code{@@settitle} command should precede everything that generates
+actual output in @TeX{}.
+
address@hidden <title> HTML tag
+In the HTML file produced by @command{makeinfo}, @var{title} also serves
+as the document @samp{<title>} and the default document description in
+the @samp{<head>} part; see @ref{documentdescription}, for how to change
+that.
+
+The title in the @code{@@settitle} command does not affect the title as
+it appears on the title page. Thus, the two do not need not match
+exactly. A practice we recommend is to include the version or edition
+number of the manual in the @code{@@settitle} title; on the title page,
+the version number generally appears as a @code{@@subtitle} so it would
+be omitted from the @code{@@title}. (@xref{titlepage}.)
+
+Conventionally, when @TeX{} formats a Texinfo file for double-sided
+output, the title is printed in the left-hand (even-numbered) page
+headings and the current chapter title is printed in the right-hand
+(odd-numbered) page headings. (@TeX{} learns the title of each chapter
+from each @code{@@chapter} command.) By default, no page footer is
+printed.
+
+Even if you are printing in a single-sided style, @TeX{} looks for an
address@hidden@@settitle} command line, in case you include the manual title
+in the heading.
+
address@hidden prints page headings only for that text that comes after the
address@hidden@@end titlepage} command in the Texinfo file, or that comes
+after an @code{@@headings} command that turns on headings.
+(@xref{headings on off, , The @code{@@headings} Command}, for more
+information.)
+
+You may, if you wish, create your own, customized headings and footings.
address@hidden, for a detailed discussion of this.
+
+
address@hidden End of Header
address@hidden End of Header
address@hidden End of header line
+
+Follow the header lines with an @w{end-of-header} line, which is a
+Texinfo comment that looks like this:
+
address@hidden
+@@c %**end of header
address@hidden example
+
address@hidden of Header}.
+
+
address@hidden Document Permissions
address@hidden Document Permissions
address@hidden Document Permissions
address@hidden Copying Permissions
+
+The copyright notice and copying permissions for a document need to
+appear in several places in the various Texinfo output formats.
+Therefore, Texinfo provides a command (@code{@@copying}) to declare
+this text once, and another command (@code{@@insertcopying}) to
+insert the text at appropriate points.
+
address@hidden
+* copying:: Declare the document's copying permissions.
+* insertcopying:: Where to insert the permissions.
address@hidden menu
+
+
address@hidden copying
address@hidden @code{@@copying}: Declare copying permissions
address@hidden copying
+
+The @code{@@copying} command should be given very early in the document;
+right after the header material (@pxref{Texinfo File Header}) is the
+recommended location. It conventionally consists of a sentence or two
+about what the program is, the legal copyright line, and the copying
+permissions. Here is a skeletal example:
+
address@hidden
+@@copying
+This manual is for @var{program} (version @var{version}),
+which @dots{}
+
+Copyright @@address@hidden@} @var{years} @var{copyright-owner}.
+
+@@quotation
+Permission is granted to @dots{}
+@@end quotation
+@@end copying
address@hidden example
+
+The @code{@@quotation} has no legal significance; it's there to improve
+readability in some contexts.
+
address@hidden Sample Texts}, for the full text to be used in GNU manuals.
address@hidden Free Documentation License}, for the license itself under
+which GNU and other free manuals are distributed.
+
+The text of @code{@@copying} is output as a comment at the beginning of
+Info, HTML, and XML output files. It is @emph{not} output implicitly in
+plain text or @TeX{}; it's up to you to use @code{@@insertcopying} to
+emit the copying information. See the next section for details.
+
address@hidden copyright
+In output formats that support it (print and HTML), the
address@hidden@@address@hidden@}} command generates a @samp{c} inside a circle.
In
+Info and plain text, it generates @samp{(C)}. The copyright notice
+itself has the following legally defined sequence:
+
address@hidden
+Copyright @copyright{} @var{years} @var{copyright-owner}.
address@hidden example
+
address@hidden Copyright word, always in English
+The word `Copyright' must always be written in English, even if the
+manual is otherwise in another language. This is due to international
+law.
+
address@hidden Years, in copyright line
+The list of years should include all years in which a version was
+completed (even if it was released in a subsequent year). Ranges are
+not allowed, each year must be written out individually, separated by
+commas.
+
address@hidden Copyright owner for FSF works
+The copyright owner (or owners) is whoever holds legal copyright on the
+work. In the case of works assigned to the FSF, the owner is `Free
+Software Foundation, Inc.'.
+
address@hidden Notices,,,maintain,GNU Maintenance Instructions}, for
+additional information.
+
+
address@hidden insertcopying
address@hidden @code{@@insertcopying}: Include permissions text
address@hidden insertcopying
address@hidden Copying text, including
address@hidden Permissions text, including
address@hidden Including permissions text
+
+The @code{@@insertcopying} command is simply written on a line by
+itself, like this:
+
address@hidden
+@@insertcopying
address@hidden example
+
+It inserts the text previously defined by @code{@@copying}. Legally, it
+must be used on the copyright page in the printed manual
+(@pxref{Copyright}).
+
+Although it's not a legal requirement, we also strongly recommend using
address@hidden@@insertcopying} in the Top node of your manual (@pxref{The Top
+Node}). Here's why:
+
+The @code{@@copying} command itself causes the permissions text to
+appear in an Info file @emph{before} the first node. The text is also
+copied into the beginning of each split Info output file, as is legally
+necessary. This location implies a human reading the manual using Info
+does @emph{not} see this text (except when using the advanced Info
+command @kbd{g *}). Therefore, an explicit @code{@@insertcopying}
+in the Top node makes it apparent to readers that the manual is free.
+
+Similarly, the @code{@@copying} text is automatically included at the
+beginning of each HTML output file, as an HTML comment. Again, this
+text is not visible (unless the reader views the HTML source). And
+therefore again, the @code{@@insertcopying} in the Top node is valuable
+because it makes the copying permissions visible and thus promotes
+freedom.
+
+The permissions text defined by @code{@@copying} also appears
+automatically at the beginning of the XML output file.
+
+
address@hidden Titlepage & Copyright Page
address@hidden Title and Copyright Pages
+
+In hard copy output, the manual's name and author are usually printed on
+a title page. Copyright information is usually printed on the back of
+the title 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 several slightly
+obscure @TeX{} typesetting commands that cannot 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 appears in the printed manual.
+
address@hidden Title page, for plain text
address@hidden Copyright page, for plain text
+You may wish to include titlepage-like information for plain text
+output. Simply place any such leading material between
address@hidden@@ifplaintext} and @code{@@end ifplaintext}; @command{makeinfo}
+includes this when writing plain text (@samp{--no-headers}), along with
+an @code{@@insertcopying}.
+
address@hidden
+* titlepage:: Create a title for the printed document.
+* titlefont center sp:: The @code{@@titlefont}, @code{@@center},
+ and @code{@@sp} commands.
+* title subtitle author:: The @code{@@title}, @code{@@subtitle},
+ and @code{@@author} commands.
+* Copyright:: How to write the copyright notice and
+ include copying permissions.
+* end titlepage:: Turn on page headings after the title and
+ copyright pages.
+* headings on off:: An option for turning headings on and off
+ and double or single sided printing.
address@hidden menu
+
+
address@hidden titlepage
address@hidden @code{@@titlepage}
address@hidden Title page
address@hidden titlepage
+
+Start the material for the title page and following copyright page
+with @code{@@titlepage} on a line by itself and end it with
address@hidden@@end titlepage} on a line by itself.
+
+The @code{@@end titlepage} command starts a new page and turns on page
+numbering. (@xref{Headings, , Page Headings}, for details about how to
+generate page headings.) All the material that you want to appear on
+unnumbered pages should be put between the @code{@@titlepage} and
address@hidden@@end titlepage} commands. You can force the table of contents to
+appear there with the @code{@@setcontentsaftertitlepage} command
+(@pxref{Contents}).
+
address@hidden address@hidden, within @code{@@titlepage}}
+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 thereby create more than one unnumbered page. This is how
+the copyright page is produced. (The @code{@@titlepage} command might
+perhaps have been better named the @code{@@titleandadditionalpages}
+command, but that would have been rather long!)
+
+When you write a manual about a computer program, you should write the
+version of the program to which the manual applies on the title page.
+If the manual changes more frequently than the program or is independent
+of it, you should also include an edition address@hidden have found
+that it is helpful to refer to versions of independent manuals as
+`editions' and versions of programs as `versions'; otherwise, we find we
+are liable to confuse each other in conversation by referring to both
+the documentation and the software with the same words.} for the manual.
+This helps readers keep track of which manual is for which version of
+the program. (The `Top' node should also contain this information; see
address@hidden Top Node}.)
+
+Texinfo provides two main methods for creating a title page. One method
+uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands
+to generate a title page in which the words on the page are
+centered.
+
+The second method uses the @code{@@title}, @code{@@subtitle}, and
address@hidden@@author} commands to create a title page with black rules under
+the title and author lines and the subtitle text set flush to the
+right hand side of the page. With this method, you do not specify any
+of the actual formatting of the title page. You specify the text
+you want, and Texinfo does the formatting.
+
+You may use either method, or you may combine them; see the examples in
+the sections below.
+
address@hidden shorttitlepage
address@hidden Bastard title page
address@hidden Title page, bastard
+For extremely simple applications, and for the bastard title page in
+traditional book front matter, Texinfo also provides a command
address@hidden@@shorttitlepage} which takes the rest of the line as the title.
+The argument is typeset on a page by itself and followed by a blank
+page.
+
+
address@hidden titlefont center sp
address@hidden @code{@@titlefont}, @code{@@center}, and @code{@@sp}
address@hidden titlefont
address@hidden center
address@hidden sp @r{(titlepage line spacing)}
+
+You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center}
+commands to create a title page for a printed document. (This is the
+first of the two methods for creating a title page in Texinfo.)
+
+Use the @code{@@titlefont} command to select a large font suitable for
+the title itself. You can use @code{@@titlefont} more than once if you
+have an especially long title.
+
address@hidden 700
+For example:
+
address@hidden
+@@address@hidden@}
address@hidden example
+
+Use the @code{@@center} command at the beginning of a line to center
+the remaining text on that line. Thus,
+
address@hidden
+@@center @@address@hidden@}
address@hidden example
+
address@hidden
+centers the title, which in this example is ``Texinfo'' printed
+in the title font.
+
+Use the @code{@@sp} command to insert vertical space. For example:
+
address@hidden
+@@sp 2
address@hidden example
+
address@hidden
+This inserts two blank lines on the printed page. (@xref{sp, ,
address@hidden@@sp}}, for more information about the @code{@@sp}
+command.)
+
+A template for this method looks like this:
+
address@hidden
address@hidden
+@@titlepage
+@@sp 10
+@@center @@address@hidden@address@hidden
+@@sp 2
+@@center @var{subtitle-if-any}
+@@sp 2
+@@center @var{author}
address@hidden
+@@end titlepage
address@hidden group
address@hidden example
+
+The spacing of the example fits an 8.5 by 11 inch manual.
+
+
address@hidden title subtitle author
address@hidden @code{@@title}, @code{@@subtitle}, and @code{@@author}
address@hidden title
address@hidden subtitle
address@hidden author
+
+You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author}
+commands to create a title page in which the vertical and horizontal
+spacing is done for you automatically. This contrasts with the method
+described in the previous section, in which the @code{@@sp} command is
+needed to adjust vertical spacing.
+
+Write the @code{@@title}, @code{@@subtitle}, or @code{@@author}
+commands at the beginning of a line followed by the title, subtitle,
+or author.
+
+The @code{@@title} command produces a line in which the title is set
+flush to the left-hand side of the page in a larger than normal font.
+The title is underlined with a black rule. Only a single line is
+allowed; the @code{@@*} command may not be used to break the title into
+two lines. To handle very long titles, you may find it profitable to
+use both @code{@@title} and @code{@@titlefont}; see the final example in
+this section.
+
+The @code{@@subtitle} command sets subtitles in a normal-sized font
+flush to the right-hand side of the page.
+
+The @code{@@author} command sets the names of the author or authors in
+a middle-sized font flush to the left-hand side of the page on a line
+near the bottom of the title page. The names are underlined with a
+black rule that is thinner than the rule that underlines the title.
+(The black rule only occurs if the @code{@@author} command line is
+followed by an @code{@@page} command line.)
+
+There are two ways to use the @code{@@author} command: you can write
+the name or names on the remaining part of the line that starts with
+an @code{@@author} command:
+
address@hidden
+@@author by Jane Smith and John Doe
address@hidden example
+
address@hidden
+or you can write the names one above each other by using two (or more)
address@hidden@@author} commands:
+
address@hidden
address@hidden
+@@author Jane Smith
+@@author John Doe
address@hidden group
address@hidden example
+
address@hidden
+(Only the bottom name is underlined with a black rule.)
+
address@hidden 950
+A template for this method looks like this:
+
address@hidden
address@hidden
+@@titlepage
+@@title @var{name-of-manual-when-printed}
+@@subtitle @var{subtitle-if-any}
+@@subtitle @var{second-subtitle}
+@@author @var{author}
+@@page
address@hidden
+@@end titlepage
address@hidden group
address@hidden example
+
+You may also combine the @code{@@titlefont} method described in the
+previous section and @code{@@title} method described in this one. This
+may be useful if you have a very long title. Here is a real-life example:
+
address@hidden
address@hidden
+@@titlepage
+@@address@hidden address@hidden
+@@sp 1
+@@title for MS-Windows and MS-DOS
+@@subtitle Edition @@address@hidden@} for Release @@address@hidden@}
+@@author by Daniel Hagerty, Melissa Weisshaus
+@@author and Eli Zaretskii
address@hidden group
address@hidden example
+
address@hidden
+(The use of @code{@@value} here is explained in @ref{value Example}.
+
+
address@hidden Copyright
address@hidden Copyright Page
address@hidden Copyright page
address@hidden Printed permissions
address@hidden Permissions, printed
+
+By international treaty, the copyright notice for a book must be either
+on the title page or on the back of the title page. When the copyright
+notice is on the back of the title page, that page is customarily not
+numbered. Therefore, in Texinfo, the information on the copyright page
+should be within @code{@@titlepage} and @code{@@end titlepage}
+commands.
+
address@hidden vskip @address@hidden vertical skip}
address@hidden filll @address@hidden dimension}
+Use the @code{@@page} command to cause a page break. To push the
+copyright notice and the other text on the copyright page towards the
+bottom of the page, use the following incantantion after @code{@@page}:
+
address@hidden
+@@vskip 0pt plus 1filll
address@hidden example
+
address@hidden
+This is a @TeX{} command that is not supported by the Info formatting
+commands. The @code{@@vskip} command inserts whitespace. The @samp{0pt
+plus 1filll} means to put in zero points of mandatory whitespace, and as
+much optional whitespace as needed to push the following text to the
+bottom of the page. Note the use of three @samp{l}s in the word
address@hidden; this is correct.
+
+To insert the copyright text itself, write @code{@@insertcopying}
+next (@pxref{Document Permissions}):
+
address@hidden
+@@insertcopying
address@hidden example
+
+Follow the copying text by the publisher, ISBN numbers, cover art
+credits, and other such information.
+
+Here is an example putting all this together:
+
address@hidden
+@@titlepage
address@hidden
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
+
+Published by @dots{}
+
+Cover art by @dots{}
+@@end titlepage
address@hidden example
+
+
address@hidden end titlepage
address@hidden Heading Generation
address@hidden end titlepage
address@hidden Headings, page, begin to appear
address@hidden Titlepage end starts headings
address@hidden End titlepage starts headings
+
+The @code{@@end titlepage} command must be written on a line by itself.
+It not only marks the end of the title and copyright pages, but also
+causes @TeX{} to start generating page headings and page numbers.
+
+To repeat what is said elsewhere, Texinfo has two standard page heading
+formats, one for documents which are printed on one side of each sheet of paper
+(single-sided printing), and the other for documents which are printed on both
+sides of each sheet (double-sided printing).
+You can specify these formats in different ways:
+
address@hidden @bullet
address@hidden
+The conventional way is to write an @code{@@setchapternewpage} command
+before the title page commands, and then have the @code{@@end
+titlepage} command start generating page headings in the manner desired.
+(@xref{setchapternewpage}.)
+
address@hidden
+Alternatively, you can use the @code{@@headings} command to prevent page
+headings from being generated or to start them for either single or
+double-sided printing. (Write an @code{@@headings} command immediately
+after the @code{@@end titlepage} command. @xref{headings on off, , The
address@hidden@@headings} Command}, for more information.)@refill
+
address@hidden
+Or, you may specify your own page heading and footing format.
address@hidden, , Page Headings}, for detailed
+information about page headings and footings.
address@hidden itemize
+
+Most documents are formatted with the standard single-sided or
+double-sided format, using @code{@@setchapternewpage odd} for
+double-sided printing and no @code{@@setchapternewpage} command for
+single-sided printing.
+
+
address@hidden headings on off
address@hidden The @code{@@headings} Command
address@hidden headings
+
+The @code{@@headings} command is rarely used. It specifies what kind of
+page headings and footings to print on each page. Usually, this is
+controlled by the @code{@@setchapternewpage} command. You need the
address@hidden@@headings} command only if the @code{@@setchapternewpage} command
+does not do what you want, or if you want to turn off pre-defined page
+headings prior to defining your own. Write an @code{@@headings} command
+immediately after the @code{@@end titlepage} address@hidden
+
+You can use @code{@@headings} as follows:@refill
+
address@hidden @code
address@hidden @@headings off
+Turn off printing of page address@hidden
+
address@hidden @@headings single
+Turn on page headings appropriate for single-sided printing.
address@hidden
+
address@hidden @@headings double
address@hidden @@headings on
+Turn on page headings appropriate for double-sided printing. The two
+commands, @code{@@headings on} and @code{@@headings double}, are
address@hidden
+
address@hidden @@headings singleafter
address@hidden @@headings doubleafter
+Turn on @code{single} or @code{double} headings, respectively, after the
+current page is output.
+
address@hidden @@headings on
+Turn on page headings: @code{single} if @samp{@@setchapternewpage
+on}, @code{double} otherwise.
address@hidden table
+
+For example, suppose you write @code{@@setchapternewpage off} before the
address@hidden@@titlepage} command to tell @TeX{} to start a new chapter on the
+same page as the end of the last chapter. This command also causes
address@hidden to typeset page headers for single-sided printing. To cause
address@hidden to typeset for double sided printing, write @code{@@headings
+double} after the @code{@@end titlepage} command.
+
+You can stop @TeX{} from generating any page headings at all by
+writing @code{@@headings off} on a line of its own immediately after the
+line containing the @code{@@end titlepage} command, like this:@refill
+
address@hidden
+@@end titlepage
+@@headings off
address@hidden example
+
address@hidden
+The @code{@@headings off} command overrides the @code{@@end titlepage}
+command, which would otherwise cause @TeX{} to print page
address@hidden
+
+You can also specify your own style of page heading and footing.
address@hidden, , Page Headings}, for more address@hidden
+
+
address@hidden The Top Node
address@hidden The `Top' Node and Master Menu
address@hidden Top node
address@hidden Node, `Top'
+
+The `Top' node is the node in which a reader enters an Info manual. As
+such, it should begin with the @code{@@insertcopying} command
+(@pxref{Document Permissions}) to provide a brief description of the
+manual (including the version number) and copying permissions, and end
+with a master menu for the whole manual. Of course you should include
+any other general information you feel a reader would find helpful.
+
address@hidden top
+It is also conventional to write an @code{@@top} sectioning command line
+containing the title of the document immediately after the @code{@@node
+Top} line (@pxref{makeinfo top command, , The @code{@@top} Sectioning
+Command}).
+
+The contents of the `Top' node should appear only in the online output;
+none of it should appear in printed output, so enclose it between
address@hidden@@ifnottex} and @code{@@end ifnottex} commands. (@TeX{} does not
+print either an @code{@@node} line or a menu; they appear only in Info;
+strictly speaking, you are not required to enclose these parts between
address@hidden@@ifnottex} and @code{@@end ifnottext}, but it is simplest to do
+so. @xref{Conditionals, , Conditionally Visible Text}.)
+
address@hidden
+* Top Node Example::
+* Master Menu Parts::
address@hidden menu
+
+
address@hidden Top Node Example
address@hidden Top Node Example
+
address@hidden Top node example
+
+Here is an example of a Top node.
+
address@hidden
address@hidden
+@@ifnottex
+@@node Top
+@@top Sample Title
+
+@@insertcopying
address@hidden group
+
+Additional general information.
+
address@hidden
+@@menu
+* First Chapter::
+* Second Chapter::
address@hidden
+* Index::
address@hidden group
+@@end menu
address@hidden example
+
+
address@hidden Master Menu Parts
address@hidden Parts of a Master Menu
address@hidden Master menu
address@hidden Menu, master
address@hidden Parts of a master menu
+
+A @dfn{master menu} is a detailed main menu listing all the nodes in a
+file.
+
+A master menu is enclosed in @code{@@menu} and @code{@@end menu}
+commands and does not appear in the printed document.
+
+Generally, a master menu is divided into parts.
+
address@hidden @bullet
address@hidden
+The first part contains the major nodes in the Texinfo file: the nodes
+for the chapters, chapter-like sections, and the appendices.
+
address@hidden
+The second part contains nodes for the indices.
+
address@hidden
+The third and subsequent parts contain a listing of the other, lower
+level nodes, often ordered by chapter. This way, rather than go
+through an intermediary menu, an inquirer can go directly to a
+particular node when searching for specific information. These menu
+items are not required; add them if you think they are a
+convenience. If you do use them, put @code{@@detailmenu} before the
+first one, and @code{@@end detailmenu} after the last; otherwise,
address@hidden will get confused.
address@hidden itemize
+
+Each section in the menu can be introduced by a descriptive line. So
+long as the line does not begin with an asterisk, it will not be
+treated as a menu entry. (@xref{Writing a Menu}, for more
+information.)
+
+For example, the master menu for this manual looks like the following
+(but has many more entries):
+
address@hidden
address@hidden
+@@menu
+* Copying Conditions:: Your rights.
+* Overview:: Texinfo in brief.
address@hidden
address@hidden group
address@hidden
+* Command and Variable Index::
+* Concept Index::
address@hidden group
+
address@hidden
+@@detailmenu
+ --- The Detailed Node Listing ---
+
+Overview of Texinfo
+
+* Reporting Bugs:: @dots{}
address@hidden
address@hidden group
+
address@hidden
+Beginning a Texinfo File
+
+* Sample Beginning:: @dots{}
address@hidden
+@@end detailmenu
+@@end menu
address@hidden group
address@hidden example
+
+
address@hidden Global Document Commands
address@hidden Global Document Commands
address@hidden Global Document Commands
+
+Besides the basic commands mentioned in the previous sections, here are
+additional commands which affect the document as a whole. They are
+generally all given before the Top node, if they are given at all.
+
address@hidden
+* documentdescription:: Document summary for the HTML output.
+* setchapternewpage:: Start chapters on right-hand pages.
+* paragraphindent:: Specify paragraph indentation.
+* exampleindent:: Specify environment indentation.
address@hidden menu
+
+
address@hidden documentdescription
address@hidden @code{@@documentdescription}: Summary text
address@hidden Document description
address@hidden Description of document
address@hidden Summary of document
address@hidden Abstract of document
address@hidden <meta> HTML tag, and document description
address@hidden documentdescription
+
+When producing HTML output for a document, @command{makeinfo} writes a
address@hidden<meta>} element in the @samp{<head>} to give some idea of the
+content of the document. By default, this @dfn{description} is the title
+of the document, taken from the @code{@@settitle} command
+(@pxref{settitle}). To change this, use the @code{@@documentdescription}
+environment, as in:
+
address@hidden
+@@documentdescription
+descriptive text.
+@@end documentdescription
address@hidden example
+
address@hidden
+This will produce the following output in the @samp{<head>} of the HTML:
+
address@hidden
+<meta name=description content="descriptive text.">
address@hidden example
+
address@hidden@@documentdescription} must be specified before the first node of
+the document.
+
+
address@hidden setchapternewpage
address@hidden @code{@@setchapternewpage}:
address@hidden Starting chapters
address@hidden Pages, starting odd
address@hidden setchapternewpage
+
+In an officially bound book, text is usually printed on both sides of
+the paper, chapters start on right-hand pages, and right-hand pages have
+odd numbers. But in short reports, text often is printed only on one
+side of the paper. Also in short reports, chapters sometimes do not
+start on new pages, but are printed on the same page as the end of the
+preceding chapter, after a small amount of vertical whitespace.
+
+You can use the @code{@@setchapternewpage} command with various
+arguments to specify how @TeX{} should start chapters and whether it
+should format headers for printing on one or both sides of the paper
+(single-sided or double-sided printing).
+
+Write the @code{@@setchapternewpage} command at the beginning of a
+line followed by its argument.
+
+For example, you would write the following to cause each chapter to
+start on a fresh odd-numbered page:
+
address@hidden
+@@setchapternewpage odd
address@hidden example
+
+You can specify one of three alternatives with the
address@hidden@@setchapternewpage} command:
+
address@hidden @asis
+
address@hidden @code{@@setchapternewpage off}
+Cause @TeX{} to typeset a new chapter on the same page as the last
+chapter, after skipping some vertical whitespace. Also, cause @TeX{} to
+format page headers for single-sided printing.
+
address@hidden @code{@@setchapternewpage on}
+Cause @TeX{} to start new chapters on new pages and to format page
+headers for single-sided printing. This is the form most often used for
+short reports or personal printing. This is the default.
+
address@hidden @code{@@setchapternewpage odd}
+Cause @TeX{} to start new chapters on new, odd-numbered pages
+(right-handed pages) and to typeset for double-sided printing. This is
+the form most often used for books and manuals.
address@hidden table
+
+Texinfo does not have an @code{@@setchapternewpage even} command,
+because there is no printing tradition of starting chapters or books on
+an even-numbered page.
+
+If you don't like the default headers that @code{@@setchapternewpage}
+sets, you can explicit control them with the @code{@@headings} command.
address@hidden on off, , The @code{@@headings} Command}.
+
+At the beginning of a manual or book, pages are not numbered---for
+example, the title and copyright pages of a book are not numbered. By
+convention, table of contents and frontmatter pages are numbered with
+roman numerals and not in sequence with the rest of the document.
+
+Since an Info file does not have pages, the @code{@@setchapternewpage}
+command has no effect on it.
+
+We recommend not including any @code{@@setchapternewpage} command in
+your manual sources at all, since the desired output is not intrinsic to
+the document. For a particular hard copy run, if you don't want the
+default option (no blank pages, same headers on all pages) use the
address@hidden option to @command{texi2dvi} to specify the output
+you want.
+
+
address@hidden paragraphindent
address@hidden Paragraph Indenting
address@hidden Indenting paragraphs, control of
address@hidden Paragraph indentation control
address@hidden paragraphindent
+
+The Texinfo processors may insert whitespace at the beginning of the
+first line of each paragraph, thereby indenting that paragraph. You can
+use the @code{@@paragraphindent} command to specify this indentation.
+Write an @code{@@paragraphindent} command at the beginning of a line
+followed by either @samp{asis} or a number:
+
address@hidden
+@@paragraphindent @var{indent}
address@hidden example
+
+The indentation is according to the value of @var{indent}:
+
address@hidden @asis
address@hidden @code{asis}
+Do not change the existing indentation (not implemented in @TeX{}).
+
address@hidden @code{none}
address@hidden 0
+Omit all indentation.
+
address@hidden @var{n}
+Indent by @var{n} space characters in Info output, by @var{n} ems in
address@hidden
+
address@hidden table
+
+The default value of @var{indent} is 3. @code{@@paragraphindent} is
+ignored for HTML output.
+
+It is best to write the @code{@@paragraphindent} command before the
+end-of-header line at the beginning of a Texinfo file, so the region
+formatting commands indent paragraphs as specified. @xref{Start of
+Header}.
+
+A peculiarity of the @code{texinfo-format-buffer} and
address@hidden commands is that they do not indent (nor
+fill) paragraphs that contain @code{@@w} or @code{@@*} commands.
address@hidden Paragraphs}, for further information.
+
+
address@hidden exampleindent
address@hidden @code{@@exampleindent}: Environment Indenting
address@hidden Indenting environments
address@hidden Environment indentation
address@hidden Example indentation
address@hidden exampleindent
+
+The Texinfo processors indent each line of @code{@@example} and similar
+environments. You can use the @code{@@exampleindent} command to specify
+this indentation. Write an @code{@@exampleindent} command at the
+beginning of a line followed by either @samp{asis} or a number:
+
address@hidden
+@@exampleindent @var{indent}
address@hidden example
+
+The indentation is according to the value of @var{indent}:
+
address@hidden @asis
address@hidden @code{asis}
+Do not change the existing indentation (not implemented in @TeX{}).
+
address@hidden 0
+Omit all indentation.
+
address@hidden @var{n}
+Indent environments by @var{n} space characters in Info output, by
address@hidden ems in @TeX{}.
+
address@hidden table
+
+The default value of @var{indent} is 5. @code{@@exampleindent} is
+ignored for HTML output.
+
+It is best to write the @code{@@exampleindent} command before the
+end-of-header line at the beginning of a Texinfo file, so the region
+formatting commands indent paragraphs as specified. @xref{Start of
+Header}.
+
+
address@hidden Software Copying Permissions
address@hidden Software Copying Permissions
address@hidden Software copying permissions
address@hidden Copying software
address@hidden Distribution
address@hidden License agreement
+
+If the Texinfo file has a section containing the ``General Public
+License'' and the distribution information and a warranty disclaimer for
+the software that is documented, we recommend placing this right after
+the `Top' node. The General Public License is very important to Project
+GNU software. It ensures that you and others will continue to have a
+right to use and share the software.
+
+The copying and distribution information and the disclaimer are followed
+by an introduction or else by the first chapter of the manual.
+
address@hidden Introduction, as part of file
+Although an introduction 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, an introduction would follow the licensing and distribution
+information, although sometimes people put it earlier in the document.
+
+
address@hidden Ending a File
address@hidden Ending a Texinfo File
address@hidden Ending a Texinfo file
address@hidden Texinfo file ending
address@hidden File ending
address@hidden bye
+
+The end of a Texinfo file should include commands to create indices and
+(perhaps) to generate both the full and summary tables of contents.
+Finally, it must include the @code{@@bye} command that marks the last
+line to be processed.
+
address@hidden 700
+For example:
+
address@hidden
+@@node Index
+@@unnumbered Index
+
+@@printindex cp
+
+@@shortcontents
+@@contents
+
+@@bye
address@hidden example
+
address@hidden
+* Printing Indices & Menus:: How to print an index in hardcopy and
+ generate index menus in Info.
+* Contents:: How to create a table of contents.
+* File End:: How to mark the end of a file.
address@hidden menu
+
+
address@hidden Printing Indices & Menus
address@hidden Printing Indices and Menus
address@hidden printindex
address@hidden Printing an index
address@hidden Indices, printing and menus
address@hidden Generating menus with indices
address@hidden Menus generated with indices
+
+To print an index means to include it as part of a manual or Info file.
+This does not happen automatically just because you use @code{@@cindex}
+or other index-entry generating commands in the Texinfo file; those just
+cause the raw data for the index to be accumulated. To generate an
+index, you must include the @code{@@printindex} command at the place in
+the document where you want the index to appear. Also, as part of the
+process of creating a printed manual, you must run a program called
address@hidden (@pxref{Hardcopy}) to sort the raw data to produce a
+sorted index file. The sorted index file is what is actually used to
+print the index.
+
+Texinfo offers six separate types of predefined index, each with a
+two-letter abbreviation, as illustrated in the following table.
+However, you may merge indices (@pxref{Combining Indices}) or define
+your own indices (@pxref{New Indices}).
+
+Here are the predefined indices, their abbreviations, and the
+corresponding index entry commands:
+
address@hidden @samp
address@hidden cp
+concept index (@code{@@cindex})
address@hidden fn
+function index (@code{@@findex})
address@hidden vr
+variable index (@code{@@index})
address@hidden ky
+key index (@code{@@kindex})
address@hidden pg
+program index (@code{@@pindex})
address@hidden tp
+data type index (@code{@@tindex})
address@hidden table
+
+The @code{@@printindex} command takes a two-letter index abbreviation,
+reads the corresponding sorted index file and formats it appropriately
+into an index.
+
+The @code{@@printindex} command does not generate a chapter heading for
+the index. Consequently, you should precede the @code{@@printindex}
+command with a suitable section or chapter command (usually
address@hidden@@appendix} or @code{@@unnumbered}) to supply the chapter heading
+and put the index into the table of contents. Precede the
address@hidden@@unnumbered} command with an @code{@@node} line.
+
+For example:
+
address@hidden
address@hidden
+@@node Variable Index
+@@unnumbered Variable Index
+
+@@printindex vr
address@hidden group
+
address@hidden
+@@node Concept Index
+@@unnumbered Concept Index
+
+@@printindex cp
address@hidden group
address@hidden smallexample
+
address@hidden
+
+We recommend placing the concept index last, since that makes it easiest
+to find. We also recommend having a single index whenever possible,
+since then readers have only one place to look (@pxref{Combining Indices}).
+
+
address@hidden Contents
address@hidden Generating a Table of Contents
address@hidden Table of contents
address@hidden Contents, Table of
address@hidden Short table of contents
address@hidden contents
address@hidden summarycontents
address@hidden shortcontents
+
+The @code{@@chapter}, @code{@@section}, and other structuring commands
+supply the information to make up a table of contents, but they do not
+cause an actual table to appear in the manual. To do this, you must use
+the @code{@@contents} and/or @code{@@summarycontents} command(s).
+
address@hidden @code
address@hidden @@contents
+Generate a table of contents in a printed manual, including all
+chapters, sections, subsections, etc., as well as appendices and
+unnumbered chapters. Headings generated by the @code{@@heading}
+series of commands do not appear in the table of contents.
+
address@hidden @@shortcontents
address@hidden @@summarycontents
+(@code{@@summarycontents} is a synonym for @code{@@shortcontents}.)
+
+Generate a short or summary table of contents that lists only the
+chapters, appendices, and unnumbered chapters. Sections, subsections
+and subsubsections are omitted. Only a long manual needs a short table
+of contents in addition to the full table of contents.
+
address@hidden table
+
+Both contents commands should be written on a line by themselves.
+The contents commands automatically generate a chapter-like heading at
+the top of the first table of contents page, so don't include any
+sectioning command such as @code{@@unnumbered} before them.
+
+Since an Info file uses menus instead of tables of contents, the Info
+formatting commands ignore the contents commands. But the contents are
+included in plain text output (generated by @code{makeinfo
+--no-headers}), unless @code{makeinfo} is writing its output to standard
+output.
+
+When @code{makeinfo} writes a short table of contents while producing
+html output, the links in the short table of contents point to
+corresponding entries in the full table of contents rather than the text
+of the document. The links in the full table of contents point to the
+main text of the document.
+
+The contents commands can be placed either at the very end of the file,
+after any indices (see the previous section) and just before the
address@hidden@@bye} (see the next section), or near the beginning of the file,
+after the @code{@@end titlepage} (@pxref{titlepage}). The advantage to
+the former is that then the contents output is always up to date,
+because it reflects the processing just done. The advantage to the
+latter is that the contents are printed in the proper place, thus you do
+not need to rearrange the DVI file with @command{dviselect} or shuffle
+paper.
+
address@hidden setcontentsaftertitlepage
address@hidden setshortcontentsaftertitlepage
address@hidden Contents, after title page
address@hidden Table of contents, after title page
+As an author, you can put the contents commands wherever you prefer.
+But if you are a user simply printing a manual, you may wish to print
+the contents after the title page even if the author put the contents
+commands at the end of the document (as is the case in most existing
+Texinfo documents, at this writing). You can do this by specifying
address@hidden@@setcontentsaftertitlepage} and/or
address@hidden@@setshortcontentsaftertitlepage}. The first prints only the main
+contents after the @code{@@end titlepage}; the second prints both the
+short contents and the main contents. In either case, any subsequent
address@hidden@@contents} or @code{@@shortcontents} is ignored (unless no
address@hidden@@end titlepage} is ever encountered).
+
+You need to include the @code{@@address@hidden
+commands early in the document (just after @code{@@setfilename}, for
+example). We recommend using @command{texi2dvi} (@pxref{Format with
+texi2dvi}) to specify this without altering the source file at all. For
+example:
address@hidden
+texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi
address@hidden example
+
+
address@hidden File End
address@hidden @code{@@bye} File Ending
address@hidden bye
+
+An @code{@@bye} command terminates @TeX{} or Info formatting. None of
+the formatting commands reading anything following @code{@@bye}. The
address@hidden@@bye} command should be on a line by itself.
+
+If you wish, you may follow the @code{@@bye} line with notes. These
+notes will not be formatted and will not appear in either Info or a
+printed manual; it is as if text after @code{@@bye} were within
address@hidden@@ignore} @dots{} @code{@@end ignore}. Also, you may follow the
address@hidden@@bye} line with a local variables list for Emacs.
address@hidden, , Using Local Variables and the Compile Command},
+for more information.
+
+
address@hidden Structuring
address@hidden Chapter Structuring
address@hidden Chapter structuring
address@hidden Structuring of chapters
+
+The @dfn{chapter structuring} commands divide a document into a hierarchy of
+chapters, sections, subsections, and subsubsections. These commands
+generate large headings; they also provide information for the table
+of contents of a printed manual (@pxref{Contents, , Generating a Table
+of Contents})address@hidden
+
+The chapter structuring commands do not create an Info node structure,
+so normally you should put an @code{@@node} command immediately before
+each chapter structuring command (@pxref{Nodes}). The only time you
+are likely to use the chapter structuring commands without using the
+node structuring commands is if you are writing a document that
+contains no cross references and will never be transformed into Info
address@hidden
+
+It is unlikely that you will ever write a Texinfo file that is
+intended only as an Info file and not as a printable document. If you
+do, you might still use chapter structuring commands to create a
+heading at the top of each node---but you don't need address@hidden
+
address@hidden
+* Tree Structuring:: A manual is like an upside down tree @dots{}
+* Structuring Command Types:: How to divide a manual into parts.
+* makeinfo top:: The @code{@@top} command, part of the `Top'
node.
+* chapter::
+* unnumbered & appendix::
+* majorheading & chapheading::
+* section::
+* unnumberedsec appendixsec heading::
+* subsection::
+* unnumberedsubsec appendixsubsec subheading::
+* subsubsection:: Commands for the lowest level sections.
+* Raise/lower sections:: How to change commands' hierarchical level.
address@hidden menu
+
+
address@hidden Tree Structuring
address@hidden Tree Structure of Sections
address@hidden Tree structuring
+
+A Texinfo file is usually structured like a book with chapters,
+sections, subsections, and the like. This structure can be visualized
+as a tree (or rather as an upside-down tree) with the root at the top
+and the levels corresponding to chapters, sections, subsection, and
address@hidden
+
+Here is a diagram that shows a Texinfo file with three chapters,
+each of which has two address@hidden
+
address@hidden
address@hidden
+ Top
+ |
+ -------------------------------------
+ | | |
+ Chapter 1 Chapter 2 Chapter 3
+ | | |
+ -------- -------- --------
+ | | | | | |
+ Section Section Section Section Section Section
+ 1.1 1.2 2.1 2.2 3.1 3.2
+
address@hidden group
address@hidden example
+
+In a Texinfo file that has this structure, the beginning of Chapter 2
+looks like this:@refill
+
address@hidden
address@hidden
+@@node Chapter 2, Chapter 3, Chapter 1, top
+@@chapter Chapter 2
address@hidden group
address@hidden example
+
+The chapter structuring commands are described in the sections that
+follow; the @code{@@node} and @code{@@menu} commands are described in
+following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill
+
+
address@hidden Structuring Command Types
address@hidden Structuring Command Types
+
+The chapter structuring commands fall into four groups or series, each
+of which contains structuring commands corresponding to the
+hierarchical levels of chapters, sections, subsections, and
address@hidden
+
+The four groups are the @code{@@chapter} series, the
address@hidden@@unnumbered} series, the @code{@@appendix} series, and the
address@hidden@@heading} address@hidden
+
+Each command produces titles that have a different appearance on the
+printed page or Info file; only some of the commands produce
+titles that are listed in the table of contents of a printed book or
address@hidden
+
address@hidden @bullet
address@hidden
+The @code{@@chapter} and @code{@@appendix} series of commands produce
+numbered or lettered entries both in the body of a printed work and in
+its table of address@hidden
+
address@hidden
+The @code{@@unnumbered} series of commands produce unnumbered entries
+both in the body of a printed work and in its table of contents. The
address@hidden@@top} command, which has a special use, is a member of this
+series (@pxref{makeinfo top, , @code{@@top}})address@hidden
+
address@hidden
+The @code{@@heading} series of commands produce unnumbered headings
+that do not appear in a table of contents. The heading commands never
+start a new address@hidden
+
address@hidden
+The @code{@@majorheading} command produces results similar to using
+the @code{@@chapheading} command but generates a larger vertical
+whitespace before the address@hidden
+
address@hidden
+When an @code{@@setchapternewpage} command says to do so, the
address@hidden@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands
+start new pages in the printed manual; the @code{@@heading} commands
+do address@hidden
address@hidden itemize
+
+Here are the four groups of chapter structuring commands:
+
address@hidden
+{\globaldefs = 1 \smallfonts}
address@hidden tex
+
address@hidden @columnfractions .19 .30 .29 .22
address@hidden @tab @tab
@tab No new page
address@hidden @i{Numbered} @tab @i{Unnumbered} @tab
@i{Lettered/numbered} @tab @i{Unnumbered}
address@hidden In contents @tab In contents @tab In
contents @tab Omitted address@hidden
address@hidden @tab @code{@@top} @tab
@tab @code{@@majorheading}
address@hidden @code{@@chapter} @tab @code{@@unnumbered} @tab
@code{@@appendix} @tab @code{@@chapheading}
address@hidden @code{@@section} @tab @code{@@unnumberedsec} @tab
@code{@@appendixsec} @tab @code{@@heading}
address@hidden @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab
@code{@@appendixsubsec} @tab @code{@@subheading}
address@hidden @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab
@code{@@appendixsubsubsec} @tab @code{@@subsubheading}
address@hidden multitable
address@hidden
+{\globaldefs = 1 \textfonts}
address@hidden tex
+
+
address@hidden makeinfo top
address@hidden @code{@@top}
+
+The @code{@@top} command is a special sectioning command that you use
+only after an @samp{@@node Top} line at the beginning of a Texinfo file.
+The @code{@@top} command tells the @code{makeinfo} formatter which node
+is the `Top' node, so it can use it as the root of the node tree if your
+manual uses implicit pointers. It has the same typesetting effect as
address@hidden@@unnumbered} (@pxref{unnumbered & appendix, , @code{@@unnumbered}
+and @code{@@appendix}}). For detailed information, see @ref{makeinfo
+top command, , The @code{@@top} Command}.
+
+The @code{@@top} node and its menu (if any) is conventionally wrapped in
+an @code{@@ifnottex} conditional so that it will appear only in Info and
+HTML output, not @TeX{}.
+
+
address@hidden chapter, unnumbered & appendix, makeinfo top, Structuring
address@hidden node-name, next, previous, up
address@hidden @code{@@chapter}
address@hidden chapter
+
address@hidden@@chapter} identifies a chapter in the document. Write the
+command at the beginning of a line and follow it on the same line by
+the title of the address@hidden
+
+For example, this chapter in this manual is entitled ``Chapter
+Structuring''; the @code{@@chapter} line looks like this:@refill
+
address@hidden
+@@chapter Chapter Structuring
address@hidden example
+
+In @TeX{}, the @code{@@chapter} command creates a chapter in the
+document, specifying the chapter title. The chapter is numbered
address@hidden
+
+In Info, the @code{@@chapter} command causes the title to appear on a
+line by itself, with a line of asterisks inserted underneath. Thus,
+in Info, the above example produces the following output:@refill
+
address@hidden
+Chapter Structuring
+*******************
address@hidden example
+
address@hidden centerchap
+Texinfo also provides a command @code{@@centerchap}, which is analogous
+to @code{@@unnumbered}, but centers its argument in the printed output.
+This kind of stylistic choice is not usually offered by Texinfo.
address@hidden but the Hacker's Dictionary wanted it ...
+
+
address@hidden unnumbered & appendix
address@hidden @code{@@unnumbered} and @code{@@appendix}
address@hidden unnumbered
address@hidden appendix
+
+Use the @code{@@unnumbered} command to create a chapter that appears
+in a printed manual without chapter numbers of any kind. Use the
address@hidden@@appendix} command to create an appendix in a printed manual
+that is labelled by letter instead of by address@hidden
+
+For Info file output, the @code{@@unnumbered} and @code{@@appendix}
+commands are equivalent to @code{@@chapter}: the title is printed on a
+line by itself with a line of asterisks underneath. (@xref{chapter, ,
address@hidden@@chapter}}.)@refill
+
+To create an appendix or an unnumbered chapter, write an
address@hidden@@appendix} or @code{@@unnumbered} command at the beginning of a
+line and follow it on the same line by the title, as you would if you
+were creating a address@hidden
+
+
address@hidden majorheading & chapheading, section, unnumbered & appendix,
Structuring
address@hidden @code{@@majorheading}, @code{@@chapheading}
address@hidden majorheading
address@hidden chapheading
+
+The @code{@@majorheading} and @code{@@chapheading} commands put
+chapter-like headings in the body of a address@hidden
+
+However, neither command causes @TeX{} to produce a numbered heading
+or an entry in the table of contents; and neither command causes
address@hidden to start a new page in a printed address@hidden
+
+In @TeX{}, an @code{@@majorheading} command generates a larger vertical
+whitespace before the heading than an @code{@@chapheading} command but
+is otherwise the address@hidden
+
+In Info,
+the @code{@@majorheading} and
address@hidden@@chapheading} commands are equivalent to
address@hidden@@chapter}: the title is printed on a line by itself with a line
+of asterisks underneath. (@xref{chapter, , @code{@@chapter}}.)@refill
+
address@hidden section, unnumberedsec appendixsec heading, majorheading &
chapheading, Structuring
address@hidden node-name, next, previous, up
address@hidden @code{@@section}
address@hidden section
+
+In a printed manual, an @code{@@section} command identifies a
+numbered section within a chapter. The section title appears in the
+table of contents. In Info, an @code{@@section} command provides a
+title for a segment of text, underlined with @address@hidden
+
+This section is headed with an @code{@@section} command and looks like
+this in the Texinfo file:@refill
+
address@hidden
+@@section @@address@hidden@@@@address@hidden
address@hidden example
+
+To create a section, write the @code{@@section} command at the
+beginning of a line and follow it on the same line by the section
address@hidden
+
+Thus,
+
address@hidden
+@@section This is a section
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+This is a section
+=================
address@hidden group
address@hidden example
+
address@hidden
+in Info.
+
address@hidden unnumberedsec appendixsec heading, subsection, section,
Structuring
address@hidden node-name, next, previous, up
address@hidden @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
address@hidden unnumberedsec
address@hidden appendixsec
address@hidden heading
+
+The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading}
+commands are, respectively, the unnumbered, appendix-like, and
+heading-like equivalents of the @code{@@section} command.
+(@xref{section, , @code{@@section}}.)@refill
+
address@hidden @code
address@hidden @@unnumberedsec
+The @code{@@unnumberedsec} command may be used within an
+unnumbered chapter or within a regular chapter or appendix to
+provide an unnumbered address@hidden
+
address@hidden @@appendixsec
address@hidden @@appendixsection
address@hidden@@appendixsection} is a longer spelling of the
address@hidden@@appendixsec} command; the two are address@hidden
address@hidden appendixsection
+
+Conventionally, the @code{@@appendixsec} or @code{@@appendixsection}
+command is used only within address@hidden
+
address@hidden @@heading
+You may use the @code{@@heading} command anywhere you wish for a
+section-style heading that will not appear in the table of address@hidden
address@hidden table
+
address@hidden subsection, unnumberedsubsec appendixsubsec subheading,
unnumberedsec appendixsec heading, Structuring
address@hidden node-name, next, previous, up
address@hidden The @code{@@subsection} Command
address@hidden subsection
+
+Subsections are to sections as sections are to chapters.
+(@xref{section, , @code{@@section}}.) In Info, subsection titles are
+underlined with @samp{-}. For example,@refill
+
address@hidden
+@@subsection This is a subsection
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+This is a subsection
+--------------------
address@hidden group
address@hidden example
+
+In a printed manual, subsections are listed in the table of contents
+and are numbered three levels address@hidden
+
address@hidden unnumberedsubsec appendixsubsec subheading, subsubsection,
subsection, Structuring
address@hidden node-name, next, previous, up
address@hidden The @code{@@subsection}-like Commands
address@hidden Subsection-like commands
address@hidden unnumberedsubsec
address@hidden appendixsubsec
address@hidden subheading
+
+The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and
address@hidden@@subheading} commands are, respectively, the unnumbered,
+appendix-like, and heading-like equivalents of the @code{@@subsection}
+command. (@xref{subsection, , @code{@@subsection}}.)@refill
+
+In Info, the @code{@@subsection}-like commands generate a title
+underlined with hyphens. In a printed manual, an @code{@@subheading}
+command produces a heading like that of a subsection except that it is
+not numbered and does not appear in the table of contents. Similarly,
+an @code{@@unnumberedsubsec} command produces an unnumbered heading like
+that of a subsection and an @code{@@appendixsubsec} command produces a
+subsection-like heading labelled with a letter and numbers; both of
+these commands produce headings that appear in the table of
address@hidden
+
address@hidden subsubsection, Raise/lower sections, unnumberedsubsec
appendixsubsec subheading, Structuring
address@hidden node-name, next, previous, up
address@hidden The `subsub' Commands
address@hidden Subsub commands
address@hidden subsubsection
address@hidden unnumberedsubsubsec
address@hidden appendixsubsubsec
address@hidden subsubheading
+
+The fourth and lowest level sectioning commands in Texinfo are the
+`subsub' commands. They are:@refill
+
address@hidden @code
address@hidden @@subsubsection
+Subsubsections are to subsections as subsections are to sections.
+(@xref{subsection, , @code{@@subsection}}.) In a printed manual,
+subsubsection titles appear in the table of contents and are numbered
+four levels address@hidden
+
address@hidden @@unnumberedsubsubsec
+Unnumbered subsubsection titles appear in the table of contents of a
+printed manual, but lack numbers. Otherwise, unnumbered
+subsubsections are the same as subsubsections. In Info, unnumbered
+subsubsections look exactly like ordinary address@hidden
+
address@hidden @@appendixsubsubsec
+Conventionally, appendix commands are used only for appendices and are
+lettered and numbered appropriately in a printed manual. They also
+appear in the table of contents. In Info, appendix subsubsections look
+exactly like ordinary address@hidden
+
address@hidden @@subsubheading
+The @code{@@subsubheading} command may be used anywhere that you need
+a small heading that will not appear in the table of contents. In
+Info, subsubheadings look exactly like ordinary subsubsection
address@hidden
address@hidden table
+
+In Info, `subsub' titles are underlined with periods.
+For example,@refill
+
address@hidden
+@@subsubsection This is a subsubsection
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+This is a subsubsection
+.......................
address@hidden group
address@hidden example
+
address@hidden Raise/lower sections, , subsubsection, Structuring
address@hidden node-name, next, previous, up
address@hidden @code{@@raisesections} and @code{@@lowersections}
address@hidden raisesections
address@hidden lowersections
address@hidden Raising and lowering sections
address@hidden Sections, raising and lowering
+
+The @code{@@raisesections} and @code{@@lowersections} commands raise and
+lower the hierarchical level of chapters, sections, subsections and the
+like. The @code{@@raisesections} command changes sections to chapters,
+subsections to sections, and so on. The @code{@@lowersections} command
+changes chapters to sections, sections to subsections, and so on.
+
address@hidden Include files, and section levels
+An @code{@@lowersections} command is useful if you wish to include text
+that is written as an outer or standalone Texinfo file in another
+Texinfo file as an inner, included file. If you write the command at
+the beginning of the file, all your @code{@@chapter} commands are
+formatted as if they were @code{@@section} commands, all your
address@hidden@@section} command are formatted as if they were
address@hidden@@subsection} commands, and so on.
+
address@hidden 1000
address@hidden@@raisesections} raises a command one level in the chapter
+structuring hierarchy:@refill
+
address@hidden
address@hidden
+ @r{Change} @r{To}
+
+@@subsection @@section,
+@@section @@chapter,
+@@heading @@chapheading,
+ @r{etc.}
address@hidden group
address@hidden example
+
address@hidden 1000
address@hidden@@lowersections} lowers a command one level in the chapter
+structuring hierarchy:@refill
+
address@hidden
address@hidden
+ @r{Change} @r{To}
+
+@@chapter @@section,
+@@subsection @@subsubsection,
+@@heading @@subheading,
+ @r{etc.}
address@hidden group
address@hidden example
+
+An @code{@@raisesections} or @code{@@lowersections} command changes only
+those structuring commands that follow the command in the Texinfo file.
+Write an @code{@@raisesections} or @code{@@lowersections} command on a
+line of its own.
+
+An @code{@@lowersections} command cancels an @code{@@raisesections}
+command, and vice versa. Typically, the commands are used like this:
+
address@hidden
+@@lowersections
+@@include somefile.texi
+@@raisesections
address@hidden example
+
+Without the @code{@@raisesections}, all the subsequent sections in your
+document will be lowered.
+
+Repeated use of the commands continue to raise or lower the hierarchical
+level a step at a time.
+
+An attempt to raise above `chapters' reproduces chapter commands; an
+attempt to lower below `subsubsections' reproduces subsubsection
+commands.
+
address@hidden Nodes
address@hidden Nodes
+
address@hidden are the primary segments of a Texinfo file. They do not
+themselves impose a hierarchical or any other kind of structure on a file.
+Nodes contain @dfn{node pointers} that name other nodes, and can contain
address@hidden which are lists of nodes. In Info, the movement commands
+can carry you to a pointed-to node or to a node listed in a menu. Node
+pointers and menus provide structure for Info files just as chapters,
+sections, subsections, and the like, provide structure for printed
address@hidden
+
address@hidden
+* Two Paths:: Different commands to structure
+ Info output and printed output.
+* Node Menu Illustration:: A diagram, and sample nodes and menus.
+* node:: Creating nodes, in detail.
+* makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
+* anchor:: Defining arbitrary cross-reference targets.
address@hidden menu
+
+
address@hidden Two Paths
address@hidden Two Paths
+
+The node and menu commands and the chapter structuring commands are
+technically independent of each other:
+
address@hidden @bullet
address@hidden
+In Info, node and menu commands provide structure. The chapter
+structuring commands generate headings with different kinds of
+underlining---asterisks for chapters, hyphens for sections, and so on;
+they do nothing address@hidden
+
address@hidden
+In @TeX{}, the chapter structuring commands generate chapter and section
+numbers and tables of contents. The node and menu commands provide
+information for cross references; they do nothing address@hidden
address@hidden itemize
+
+You can use node pointers and menus to structure an Info file any way
+you want; and you can write a Texinfo file so that its Info output has a
+different structure than its printed output. However, virtually all
+Texinfo files are written such that the structure for the Info output
+corresponds to the structure for the printed output. It is neither
+convenient nor understandable to the reader to do address@hidden
+
+Generally, printed output is structured in a tree-like hierarchy in
+which the chapters are the major limbs from which the sections branch
+out. Similarly, node pointers and menus are organized to create a
+matching structure in the Info address@hidden
+
+
address@hidden Node Menu Illustration
address@hidden Node and Menu Illustration
+
+Here is a copy of the diagram shown earlier that illustrates a Texinfo
+file with three chapters, each of which contains two address@hidden
+
+The ``root'' is at the top of the diagram and the ``leaves'' are at the
+bottom. This is how such a diagram is drawn conventionally; it
+illustrates an upside-down tree. For this reason, the root node is
+called the `Top' node, and `Up' node pointers carry you closer to the
address@hidden
+
address@hidden
address@hidden
+ Top
+ |
+ -------------------------------------
+ | | |
+ Chapter 1 Chapter 2 Chapter 3
+ | | |
+ -------- -------- --------
+ | | | | | |
+ Section Section Section Section Section Section
+ 1.1 1.2 2.1 2.2 3.1 3.2
address@hidden group
address@hidden example
+
+The fully-written command to start Chapter 2 would be this:
+
address@hidden
address@hidden
+@@node Chapter 2, Chapter 3, Chapter 1, Top
+@@comment node-name, next, previous, up
address@hidden group
address@hidden example
+
address@hidden
+This @code{@@node} line says that the name of this node is ``Chapter
+2'', the name of the `Next' node is ``Chapter 3'', the name of the
+`Previous' node is ``Chapter 1'', and the name of the `Up' node is
+``Top''. You can omit writing out these node names if your document is
+hierarchically organized (@pxref{makeinfo Pointer Creation}), but the
+pointer relationships still obtain.
+
address@hidden
address@hidden Note:} `Next' refers to the next node at the same
+hierarchical level in the manual, not necessarily to the next node
+within the Texinfo file. In the Texinfo file, the subsequent node may
+be at a lower level---a section-level node most often follows a
+chapter-level node, for example. `Next' and `Previous' refer to nodes
+at the @emph{same} hierarchical level. (The `Top' node contains the
+exception to this rule. Since the `Top' node is the only node at that
+level, `Next' refers to the first following node, which is almost always
+a chapter or chapter-level node.)@refill
address@hidden quotation
+
+To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter
+2. (@xref{Menus}.) You would write the menu just
+before the beginning of Section 2.1, like this:@refill
+
address@hidden
address@hidden
+ @@menu
+ * Sect. 2.1:: Description of this section.
+ * Sect. 2.2::
+ @@end menu
address@hidden group
address@hidden example
+
+Write the node for Sect. 2.1 like this:@refill
+
address@hidden
address@hidden
+ @@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
+ @@comment node-name, next, previous, up
address@hidden group
address@hidden example
+
+In Info format, the `Next' and `Previous' pointers of a node usually
+lead to other nodes at the same level---from chapter to chapter or from
+section to section (sometimes, as shown, the `Previous' pointer points
+up); an `Up' pointer usually leads to a node at the level above (closer
+to the `Top' node); and a `Menu' leads to nodes at a level below (closer
+to `leaves'). (A cross reference can point to a node at any level;
+see @ref{Cross References}.)@refill
+
+Usually, an @code{@@node} command and a chapter structuring command are
+used in sequence, along with indexing commands. (You may follow the
address@hidden@@node} line with a comment line that reminds you which pointer is
+which.)@refill
+
+Here is the beginning of the chapter in this manual called ``Ending a
+Texinfo File''. This shows an @code{@@node} line followed by a comment
+line, an @code{@@chapter} line, and then by indexing address@hidden
+
address@hidden
address@hidden
+@@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
address@hidden group
address@hidden example
+
+
address@hidden node
address@hidden The @code{@@node} Command
+
address@hidden Node, defined
address@hidden node
+
+A @dfn{node} is a segment of text that begins at an @code{@@node}
+command and continues until the next @code{@@node} command. The
+definition of node is different from that for chapter or section. A
+chapter may contain sections and a section may contain subsections;
+but a node cannot contain subnodes; the text of a node continues only
+until the next @code{@@node} command in the file. A node usually
+contains only one chapter structuring command, the one that follows
+the @code{@@node} line. On the other hand, in printed output nodes
+are used only for cross references, so a chapter or section may
+contain any number of nodes. Indeed, a chapter usually contains
+several nodes, one for each section, subsection, and
address@hidden
+
+To create a node, write an @code{@@node} command at the beginning of a
+line, and follow it with up to four arguments, separated by commas, on
+the rest of the same line. The first argument is required; it is the
+name of this node. The subsequent arguments are the names of the
+`Next', `Previous', and `Up' pointers, in that order, and may be omitted
+if your Texinfo document is hierarchically organized (@pxref{makeinfo
+Pointer Creation}).
+
+You may insert spaces before each name if you wish; the spaces are
+ignored. You must write the name of the node and the names of the
+`Next', `Previous', and `Up' pointers all on the same line. Otherwise,
+the formatters fail. (@inforef{Top, info, info}, for more information
+about nodes in Info.)
+
+Usually, you write one of the chapter-structuring command lines
+immediately after an @code{@@node} line---for example, an
address@hidden@@section} or @code{@@subsection} line. (@xref{Structuring
+Command Types}.)
+
address@hidden
address@hidden note:} The GNU Emacs Texinfo mode updating commands work
+only with Texinfo files in which @code{@@node} lines are followed by chapter
+structuring lines. @xref{Updating address@hidden
address@hidden quotation
+
address@hidden uses @code{@@node} lines to identify the names to use for cross
+references. For this reason, you must write @code{@@node} lines in a
+Texinfo file that you intend to format for printing, even if you do not
+intend to format it for Info. (Cross references, such as the one at the
+end of this sentence, are made with @code{@@xref} and related commands;
+see @ref{Cross References}.)@refill
+
address@hidden
+* Node Names:: How to choose node and pointer names.
+* Writing a Node:: How to write an @code{@@node} line.
+* Node Line Tips:: Keep names short.
+* Node Line Requirements:: Keep names unique, without @@-commands.
+* First Node:: How to write a `Top' node.
+* makeinfo top command:: How to use the @code{@@top} command.
address@hidden menu
+
+
address@hidden Node Names
address@hidden Choosing Node and Pointer Names
+
address@hidden Node names, choosing
+The name of a node identifies the node. The pointers enable
+you to reach other nodes and consist of the names of those address@hidden
+
+Normally, a node's `Up' pointer contains the name of the node whose menu
+mentions that node. The node's `Next' pointer contains the name of the
+node that follows that node in that menu and its `Previous' pointer
+contains the name of the node that precedes it in that menu. When a
+node's `Previous' node is the same as its `Up' node, both node pointers
+name the same address@hidden
+
+Usually, the first node of a Texinfo file is the `Top' node, and its
+`Up' and `Previous' pointers point to the @file{dir} file, which
+contains the main menu for all of address@hidden
+
+The `Top' node itself contains the main or master menu for the manual.
+Also, it is helpful to include a brief description of the manual in the
+`Top' node. @xref{First Node}, for information on how to write the
+first node of a Texinfo address@hidden
+
+Even when you explicitly specify all pointers, that does not mean you
+can write the nodes in the Texinfo source file in an arbitrary order!
+Because @TeX{} processes the file sequentially, irrespective of node
+pointers, you must write the nodes in the order you wish them to appear
+in the printed output.
+
+
address@hidden Writing a Node
address@hidden How to Write an @code{@@node} Line
address@hidden Writing an @code{@@node} line
address@hidden @code{@@node} line writing
address@hidden Node line writing
+
+The easiest way to write an @code{@@node} line is to write @code{@@node}
+at the beginning of a line and then the name of the node, like
+this:@refill
+
address@hidden
+@@node @var{node-name}
address@hidden example
+
+If you are using GNU Emacs, you can use the update node commands
+provided by Texinfo mode to insert the names of the pointers; or you
+can leave the pointers out of the Texinfo file and let @code{makeinfo}
+insert node pointers into the Info file it creates. (@xref{Texinfo
+Mode}, and @ref{makeinfo Pointer Creation}.)@refill
+
+Alternatively, you can insert the `Next', `Previous', and `Up'
+pointers yourself. If you do this, you may find it helpful to use the
+Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts
address@hidden@@node} and a comment line listing the names of the pointers in
+their proper order. The comment line helps you keep track of which
+arguments are for which pointers. This comment line is especially useful
+if you are not familiar with address@hidden
+
+The template for a fully-written-out node line with `Next', `Previous',
+and `Up' pointers looks like this:@refill
+
address@hidden
+@@node @var{node-name}, @var{next}, @var{previous}, @var{up}
address@hidden example
+
+If you wish, you can ignore @code{@@node} lines altogether in your first
+draft and then use the @code{texinfo-insert-node-lines} command to
+create @code{@@node} lines for you. However, we do not recommend this
+practice. It is better to name the node itself at the same time that
+you write a segment so you can easily make cross references. A large
+number of cross references are an especially important feature of a good
+Info file.
+
+After you have inserted an @code{@@node} line, you should immediately
+write an @@-command for the chapter or section and insert its name.
+Next (and this is important!), put in several index entries. Usually,
+you will find at least two and often as many as four or five ways of
+referring to the node in the index. Use them all. This will make it
+much easier for people to find the node.
+
+
address@hidden Node Line Tips
address@hidden @code{@@node} Line Tips
+
+Here are three suggestions:
+
address@hidden @bullet
address@hidden
+Try to pick node names that are informative but address@hidden
+
+In the Info file, the file name, node name, and pointer names are all
+inserted on one line, which may run into the right edge of the window.
+(This does not cause a problem with Info, but is ugly.)@refill
+
address@hidden
+Try to pick node names that differ from each other near the beginnings
+of their names. This way, it is easy to use automatic name completion in
address@hidden
+
address@hidden
+By convention, node names are capitalized just as they would be for
+section or chapter titles---initial and significant words are
+capitalized; others are address@hidden
address@hidden itemize
+
+
address@hidden Node Line Requirements, First Node, Node Line Tips, node
address@hidden @code{@@node} Line Requirements
+
address@hidden Node line requirements
address@hidden Restrictions on node names
+Here are several requirements for @code{@@node} lines:
+
address@hidden @bullet
address@hidden Unique nodename requirement
address@hidden Node name must be unique
address@hidden
+All the node names for a single Info file must be address@hidden
+
+Duplicates confuse the Info movement commands. This means, for
+example, that if you end every chapter with a summary, you must name
+each summary node differently. You cannot just call each one
+``Summary''. You may, however, duplicate the titles of chapters, sections,
+and the like. Thus you can end each chapter in a book with a section
+called ``Summary'', so long as the node names for those sections are all
address@hidden
+
address@hidden
+A pointer name must be the name of a address@hidden
+
+The node to which a pointer points may come before or after the
+node containing the pointer.
+
address@hidden @@-commands in nodename
address@hidden Node name, should not contain @@-commands
address@hidden
address@hidden@@-commands} used in node names generally confuse Info, so you
+should avoid them. This includes punctuation characters that are
+escaped with a @samp{@@}, such as @code{@@} and @address@hidden For a few
+rare cases when this is useful, Texinfo has limited support for using
address@hidden@@-commands} in node names; see @ref{Pointer Validation}.
+
address@hidden 750
+Thus, the beginning of the section called @code{@@chapter} looks like
+this:@refill
+
address@hidden
address@hidden
+@@node chapter, unnumbered & appendix, makeinfo top, Structuring
+@@comment node-name, next, previous, up
+@@section @@address@hidden@@@@address@hidden
+@@findex chapter
address@hidden group
address@hidden smallexample
+
address@hidden
address@hidden Parentheses in nodename
+You cannot use parentheses in node names, because a node name such as
address@hidden(foo)bar} is interpreted by the Info readers as a node
address@hidden in an Info file @file{foo}.
+
address@hidden
address@hidden Apostrophe in nodename
address@hidden Colon in nodename
address@hidden Comma in nodename
address@hidden Period in nodename
address@hidden Characters, invalid in node name
address@hidden Invalid characters in node names
+Unfortunately, you cannot use periods, commas, colons or apostrophes
+within a node name; these confuse @TeX{} or the Info formatters.
+
address@hidden 700
+For example, the following is a section title:
+
address@hidden
+@@address@hidden@@@@address@hidden, @@address@hidden@@@@address@hidden,
@@address@hidden@@@@address@hidden
address@hidden smallexample
+
address@hidden
+The corresponding node name is:
+
address@hidden
+unnumberedsec appendixsec heading
address@hidden smallexample
+
address@hidden Case in node name
address@hidden
+Case is significant.
address@hidden itemize
+
+
address@hidden First Node
address@hidden The First Node
address@hidden Top node is first
address@hidden First node
+
+The first node of a Texinfo file is the @dfn{Top} node, except in an
+included file (@pxref{Include Files}). The Top node should contain a
+short summary, copying permissions, and a master menu. @xref{The Top
+Node}, for more information on the Top node contents and examples.
+
+Here is a description of the node pointers to be used in the Top node:
+
address@hidden @bullet
+
address@hidden
address@hidden Up node of Top node
address@hidden (dir) as Up node of Top node
+The Top node (which must be named @samp{top} or @samp{Top}) should have
+as its `Up' node the name of a node in another file, where there is a
+menu that leads to this file. Specify the file name in parentheses.
+
+Usually, all Info files are installed in the same Info directory tree;
+in this case, use @samp{(dir)} as the parent of the Top node; this is
+short for @samp{(dir)top}, and specifies the Top node in the @file{dir}
+file, which contains the main menu for the Info system as a whole.
+
address@hidden
address@hidden Previous node of Top node
+On the other hand, do not define the `Previous' node of the Top node to
+be @samp{(dir)}, as it causes confusing behavior for users: if you are
+in the Top node and hits @key{DEL} to go backwards, you wind up in the
+middle of the some other entry in the @file{dir} file, which has nothing
+to do with what you were reading.
+
address@hidden
address@hidden Next node of Top node
+The `Next' node of the Top node should be the first chapter in your
+document.
+
address@hidden itemize
+
address@hidden an Info File}, for more information about installing
+an Info file in the @file{info} directory.
+
+For concreteness, here is an example with explicit pointers (which you
+can maintain automatically with the texinfo mode commands):
+
+Or you can leave the pointers off entirely and let the tools implicitly
+define them. This is recommended. Thus:
+
address@hidden
+@@node Top
address@hidden example
+
+
address@hidden makeinfo top command
address@hidden The @code{@@top} Sectioning Command
address@hidden top @r{(@@-command)}
+
+A special sectioning command, @code{@@top} should be used with the
address@hidden@@node Top} line. The @code{@@top} sectioning command tells
address@hidden that it marks the `Top' node in the file. It provides
+the information that @code{makeinfo} needs to insert node pointers
+automatically. Write the @code{@@top} command at the beginning of the
+line immediately following the @code{@@node Top} line. Write the title
+on the remaining part of the same line as the @code{@@top} command.
+
+In Info, the @code{@@top} sectioning command causes the title to appear
+on a line by itself, with a line of asterisks inserted underneath, as
+other sectioning commands do.
+
+In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
+sectioning command is merely a synonym for @code{@@unnumbered}.
+Neither of these formatters require an @code{@@top} command, and do
+nothing special with it. You can use @code{@@chapter} or
address@hidden@@unnumbered} after the @code{@@node Top} line when you use
+these formatters. Also, you can use @code{@@chapter} or
address@hidden@@unnumbered} when you use the Texinfo updating commands to
+create or update pointers and menus.
+
+Thus, in practice, a Top node starts like this:
+
address@hidden
+@@node Top
+@@top Your Manual Title
address@hidden example
+
+
address@hidden makeinfo Pointer Creation
address@hidden Creating Pointers with @code{makeinfo}
address@hidden Creating pointers with @code{makeinfo}
address@hidden Pointer creation with @code{makeinfo}
address@hidden Automatic pointer creation with @code{makeinfo}
+
+The @code{makeinfo} program has a feature for automatically defining
+node pointers for a hierarchically organized file.
+
+When you take advantage of this feature, you do not need to write the
+`Next', `Previous', and `Up' pointers after the name of a node.
+However, you must write a sectioning command, such as @code{@@chapter}
+or @code{@@section}, on the line immediately following each truncated
address@hidden@@node} line (except that comment lines may intervene).
+
+In addition, you must follow the `Top' @code{@@node} line with a line
+beginning with @code{@@top} to mark the `Top' node in the
+file. @xref{makeinfo top, , @code{@@top}}.
+
+Finally, you must write the name of each node (except for the `Top'
+node) in a menu that is one or more hierarchical levels above the
+node's hierarchical level.
+
+This node pointer insertion feature in @code{makeinfo} relieves you from
+the need to update menus and pointers manually or with Texinfo mode
+commands. (@xref{Updating Nodes and Menus}.)
+
+In most cases, you will want to take advantage of this feature and not
+redundantly specify node pointers. However, Texinfo documents are not
+required to be organized hierarchically or in fact contain sectioning
+commands at all. For example, if you never intend the document to be
+printed. In those cases, you will need to explicitly specify the pointers.
+
+
address@hidden anchor
address@hidden @code{@@anchor}: Defining Arbitrary Cross-reference Targets
+
address@hidden anchor
address@hidden Anchors
address@hidden Cross-reference targets, arbitrary
address@hidden Targets for cross-references, arbitrary
+
+An @dfn{anchor} is a position in your document, labeled so that
+cross-references can refer to it, just as they can to nodes. You create
+an anchor with the @code{@@anchor} command, and give the label as a
+normal brace-delimited argument. For example:
+
address@hidden
+This marks the @@address@hidden@}spot.
address@hidden
+@@address@hidden,,the address@hidden
address@hidden example
+
address@hidden produces:
+
address@hidden
+This marks the spot.
address@hidden
+See [the spot], page 1.
address@hidden example
+
+As you can see, the @code{@@anchor} command itself produces no output.
+This example defines an anchor `x-spot' just before the word `spot'.
+You can refer to it later with an @code{@@xref} or other cross-reference
+command, as shown. @xref{Cross References}, for details on the
+cross-reference commands.
+
+It is best to put @code{@@anchor} commands just before the position you
+wish to refer to; that way, the reader's eye is led on to the correct
+text when they jump to the anchor. You can put the @code{@@anchor}
+command on a line by itself if that helps readability of the source.
+Spaces are always ignored after @code{@@anchor}.
+
+Anchor names and node names may not conflict. Anchors and nodes are
+given similar treatment in some ways; for example, the @code{goto-node}
+command in standalone Info takes either an anchor name or a node name as
+an argument. (@xref{goto-node,,,info-stnd,GNU Info}.)
+
+
address@hidden Menus
address@hidden Menus
address@hidden Menus
address@hidden menu
+
address@hidden contain pointers to subordinate address@hidden can
+carry you to any node, regardless of the hierarchical structure; even to
+nodes in a different Info file. However, the GNU Emacs Texinfo mode
+updating commands work only to create menus of subordinate nodes.
+Conventionally, cross references are used to refer to other nodes.} In
+Info, you use menus to go to such nodes. Menus have no effect in
+printed manuals and do not appear in them.
+
+By convention, a menu is put at the end of a node since a reader who
+uses the menu may not see text that follows it. Furthermore, a node
+that has a menu should not contain much text. If you have a lot of text
+and a menu, move most of the text into a new subnode---all but a few
+lines. Otherwise, a reader with a terminal that displays only a few
+lines may miss the menu and its associated text. As a practical matter,
+you should locate a menu within 20 lines of the beginning of the
+node.
+
address@hidden
+* Menu Location:: Put a menu in a short node.
+* Writing a Menu:: What is a menu?
+* Menu Parts:: A menu entry has three parts.
+* Less Cluttered Menu Entry:: Two part menu entry.
+* Menu Example:: Two and three part menu entries.
+* Other Info Files:: How to refer to a different Info file.
address@hidden menu
+
+
address@hidden Menu Location, Writing a Menu, Menus, Menus
address@hidden Menus Need Short Nodes
address@hidden Menu location
address@hidden Location of menus
address@hidden Nodes for menus are short
address@hidden Short nodes for menus
+
+The short text before a menu may look awkward in a printed manual. To
+avoid this, you can write a menu near the beginning of its node and
+follow the menu by an @code{@@node} line, and then an @code{@@heading}
+line located within @code{@@ifinfo} and @code{@@end ifinfo}. This way,
+the menu, @code{@@node} line, and title appear only in the Info file,
+not the printed document.
+
+For example, the preceding two paragraphs follow an Info-only menu,
address@hidden@@node} line, and heading, and look like this:
+
address@hidden
address@hidden
+@@menu
+* Menu Location:: Put a menu in a short node.
+* Writing a Menu:: What is a menu?
+* Menu Parts:: A menu entry has three parts.
+* Less Cluttered Menu Entry:: Two part menu entry.
+* Menu Example:: Two and three part entries.
+* Other Info Files:: How to refer to a different
+ Info file.
+@@end menu
+
+@@node Menu Location, Writing a Menu, , Menus
+@@ifinfo
+@@heading Menus Need Short Nodes
+@@end ifinfo
address@hidden group
address@hidden example
+
+The Texinfo file for this document contains a number of
+examples of this procedure; one is at the beginning of this chapter.
+
+
address@hidden Writing a Menu, Menu Parts, Menu Location, Menus
address@hidden Writing a Menu
address@hidden Writing a menu
address@hidden Menu writing
+
+A menu consists of an @code{@@menu} command on a line by
+itself followed by menu entry lines or menu comment lines
+and then by an @code{@@end menu} command on a line by
address@hidden
+
+A menu looks like this:@refill
+
address@hidden
address@hidden
+@@menu
+Larger Units of Text
+
+* Files:: All about handling files.
+* Multiples: Buffers. Multiple buffers; editing
+ several files at once.
+@@end menu
address@hidden group
address@hidden example
+
+In a menu, every line that begins with an @address@hidden }} is a @dfn{menu
+entry}. (Note the space after the asterisk.) A line that does not
+start with an @address@hidden }} may also appear in a menu. Such a line is
+not a menu entry but is a menu comment line that appears in the Info
+file. In the example above, the line @samp{Larger Units of Text} is a
+menu comment line; the two lines starting with @address@hidden }} are menu
address@hidden Spaces, in menus
+entries. Space characters in a menu are preserved as-is; this allows
+you to format the menu as you wish.
+
+
address@hidden Menu Parts, Less Cluttered Menu Entry, Writing a Menu, Menus
address@hidden The Parts of a Menu
address@hidden Parts of a menu
address@hidden Menu parts
address@hidden @code{@@menu} parts
+
+A menu entry has three parts, only the second of which is required:
+
address@hidden
address@hidden
+The menu entry name (optional).
+
address@hidden
+The name of the node (required).
+
address@hidden
+A description of the item (optional).
address@hidden enumerate
+
+The template for a menu entry looks like this:@refill
+
address@hidden
+* @var{menu-entry-name}: @var{node-name}. @var{description}
address@hidden example
+
+Follow the menu entry name with a single colon and follow the node name
+with tab, comma, period, or address@hidden
+
+In Info, a user selects a node with the @kbd{m} (@code{Info-menu})
+command. The menu entry name is what the user types after the @kbd{m}
address@hidden
+
+The third part of a menu entry is a descriptive phrase or sentence.
+Menu entry names and node names are often short; the description
+explains to the reader what the node is about. A useful description
+complements the node name rather than repeats it. The description,
+which is optional, can spread over two or more lines; if it does, some
+authors prefer to indent the second line while others prefer to align it
+with the first (and all others). It's up to you.
+
+
address@hidden Less Cluttered Menu Entry, Menu Example, Menu Parts, Menus
address@hidden node-name, next, previous, up
address@hidden Less Cluttered Menu Entry
address@hidden Two part menu entry
address@hidden Double-colon menu entries
address@hidden Menu entries with two colons
address@hidden Less cluttered menu entry
address@hidden Uncluttered menu entry
+
+When the menu entry name and node name are the same, you can write
+the name immediately after the asterisk and space at the beginning of
+the line and follow the name with two address@hidden
+
address@hidden 800
+For example, write
+
address@hidden
+* Name:: @var{description}
address@hidden example
+
address@hidden 800
address@hidden
+instead of
+
address@hidden
+* Name: Name. @var{description}
address@hidden example
+
+You should use the node name for the menu entry name whenever possible,
+since it reduces visual clutter in the address@hidden
+
address@hidden Menu Example, Other Info Files, Less Cluttered Menu Entry, Menus
address@hidden node-name, next, previous, up
address@hidden A Menu Example
address@hidden Menu example
address@hidden Example menu
+
+A menu looks like this in Texinfo:@refill
+
address@hidden
address@hidden
+@@menu
+* menu entry name: Node name. A short description.
+* Node name:: This form is preferred.
+@@end menu
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+This produces:
+
address@hidden
address@hidden
+* menu:
+
+* menu entry name: Node name. A short description.
+* Node name:: This form is preferred.
address@hidden group
address@hidden example
+
address@hidden 700
+Here is an example as you might see it in a Texinfo file:@refill
+
address@hidden
address@hidden
+@@menu
+Larger Units of Text
+
+* Files:: All about handling files.
+* Multiples: Buffers. Multiple buffers; editing
+ several files at once.
+@@end menu
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+This produces:
+
address@hidden
address@hidden
+* menu:
+Larger Units of Text
+
+* Files:: All about handling files.
+* Multiples: Buffers. Multiple buffers; editing
+ several files at once.
address@hidden group
address@hidden example
+
+In this example, the menu has two entries. @samp{Files} is both a menu
+entry name and the name of the node referred to by that name.
address@hidden is the menu entry name; it refers to the node named
address@hidden The line @samp{Larger Units of Text} is a comment; it
+appears in the menu, but is not an address@hidden
+
+Since no file name is specified with either @samp{Files} or
address@hidden, they must be the names of nodes in the same Info file
+(@pxref{Other Info Files, , Referring to Other Info Files})address@hidden
+
address@hidden Other Info Files, , Menu Example, Menus
address@hidden node-name, next, previous, up
address@hidden Referring to Other Info Files
address@hidden Referring to other Info files
address@hidden Nodes in other Info files
address@hidden Other Info files' nodes
address@hidden Going to other Info files' nodes
address@hidden Info; other files' nodes
+
+You can create a menu entry that enables a reader in Info to go to a
+node in another Info file by writing the file name in parentheses just
+before the node name. In this case, you should use the three-part menu
+entry format, which saves the reader from having to type the file
address@hidden
+
address@hidden 800
+The format looks like this:@refill
+
address@hidden
address@hidden
+@@menu
+* @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description}
+* @var{second-entry-name}:(@var{filename})@var{second-node}. @var{description}
+@@end menu
address@hidden group
address@hidden example
+
+For example, to refer directly to the @samp{Outlining} and
address@hidden nodes in the @cite{Emacs Manual}, you would write a
+menu like this:@refill
+
address@hidden
address@hidden
+@@menu
+* Outlining: (emacs)Outline Mode. The major mode for
+ editing outlines.
+* Rebinding: (emacs)Rebinding. How to redefine the
+ meaning of a key.
+@@end menu
address@hidden group
address@hidden example
+
+If you do not list the node name, but only name the file, then Info
+presumes that you are referring to the `Top' address@hidden
+
+The @file{dir} file that contains the main menu for Info has menu
+entries that list only file names. These take you directly to the `Top'
+nodes of each Info document. (@xref{Installing an Info File}.)
+
address@hidden 700
+For example:
+
address@hidden
address@hidden
+* Info: (info). Documentation browsing system.
+* Emacs: (emacs). The extensible, self-documenting
+ text editor.
address@hidden group
address@hidden example
+
address@hidden
+(The @file{dir} top level directory for the Info system is an Info file,
+not a Texinfo file, but a menu entry looks the same in both types of
+file.)@refill
+
+The GNU Emacs Texinfo mode menu updating commands only work with nodes
+within the current buffer, so you cannot use them to create menus that
+refer to other files. You must write such menus by hand.
+
+
address@hidden Cross References
address@hidden Cross References
address@hidden Making cross references
address@hidden Cross references
address@hidden References
+
address@hidden references} are used to refer the reader to other parts of the
+same or different Texinfo files. In Texinfo, nodes and anchors are the
+places to which cross references can refer.
+
address@hidden
+* References:: What cross references are for.
+* Cross Reference Commands:: A summary of the different commands.
+* Cross Reference Parts:: A cross reference has several parts.
+* xref:: Begin a reference with `See' @dots{}
+* Top Node Naming:: How to refer to the beginning of another file.
+* ref:: A reference for the last part of a sentence.
+* pxref:: How to write a parenthetical cross reference.
+* inforef:: How to refer to an Info-only file.
+* uref:: How to refer to a uniform resource locator.
address@hidden menu
+
address@hidden References, Cross Reference Commands, Cross References, Cross
References
address@hidden What References Are For
+
+Often, but not always, a printed document should be designed so that
+it can be read sequentially. People tire of flipping back and forth
+to find information that should be presented to them as they need
address@hidden
+
+However, in any document, some information will be too detailed for
+the current context, or incidental to it; use cross references to
+provide access to such information. Also, an online help system or a
+reference manual is not like a novel; few read such documents in
+sequence from beginning to end. Instead, people look up what they
+need. For this reason, such creations should contain many cross
+references to help readers find other information that they may not
+have address@hidden
+
+In a printed manual, a cross reference results in a page reference,
+unless it is to another manual altogether, in which case the cross
+reference names that address@hidden
+
+In Info, a cross reference results in an entry that you can follow using
+the Info @samp{f} command. (@inforef{Help-Adv, Some advanced Info
+commands, info}.)@refill
+
+The various cross reference commands use nodes (or anchors,
address@hidden,,@code{@@anchor}}) to define cross reference locations.
+This is evident in Info, in which a cross reference takes you to the
+specified location. @TeX{} also uses nodes to define cross reference
+locations, but the action is less obvious. When @TeX{} generates a DVI
+file, it records each node's page number and uses the page numbers in making
+references. Thus, if you are writing a manual that will only be
+printed, and will not be used online, you must nonetheless write
address@hidden@@node} lines to name the places to which you make cross
address@hidden
+
address@hidden 800
address@hidden Cross Reference Commands, Cross Reference Parts, References,
Cross References
address@hidden node-name, next, previous, up
address@hidden Different Cross Reference Commands
address@hidden Different cross reference commands
+
+There are four different cross reference commands:@refill
+
address@hidden @code
address@hidden @@xref
+Used to start a sentence in the printed manual saying @w{`See @dots{}'}
+or an Info cross-reference saying @samp{*Note @var{name}: @var{node}.}.
+
address@hidden @@ref
+Used within or, more often, at the end of a sentence; same as
address@hidden@@xref} for Info; produces just the reference in the printed
+manual without a preceding `See'address@hidden
+
address@hidden @@pxref
+Used within parentheses to make a reference that suits both an Info
+file and a printed book. Starts with a lower case `see' within the
+printed manual. (@samp{p} is for `parenthesis'.)@refill
+
address@hidden @@inforef
+Used to make a reference to an Info file for which there is no printed
address@hidden
address@hidden table
+
address@hidden
+(The @code{@@cite} command is used to make references to books and
+manuals for which there is no corresponding Info file and, therefore,
+no node to which to point. @xref{cite, , @code{@@cite}}.)@refill
+
address@hidden Cross Reference Parts, xref, Cross Reference Commands, Cross
References
address@hidden node-name, next, previous, up
address@hidden Parts of a Cross Reference
address@hidden Cross reference parts
address@hidden Parts of a cross reference
+
+A cross reference command requires only one argument, which is the
+name of the node to which it refers. But a cross reference command
+may contain up to four additional arguments. By using these
+arguments, you can provide a cross reference name for Info, a topic
+description or section title for the printed output, the name of a
+different Info file, and the name of a different printed
address@hidden
+
+Here is a simple cross reference example:@refill
+
address@hidden
+@@address@hidden address@hidden
address@hidden example
+
address@hidden
+which produces
+
address@hidden
+*Note Node name::.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See Section @var{nnn} [Node name], page @var{ppp}.
address@hidden quotation
+
address@hidden 700
+Here is an example of a full five-part cross reference:@refill
+
address@hidden
address@hidden
+@@address@hidden name, Cross Reference Name, Particular Topic,
+info-file-name, A Printed address@hidden, for details.
address@hidden group
address@hidden example
+
address@hidden
+which produces
+
address@hidden
+*Note Cross Reference Name: (info-file-name)Node name,
+for details.
address@hidden example
+
address@hidden
+in Info and
+
address@hidden
+See section ``Particular Topic'' in @i{A Printed Manual}, for details.
address@hidden quotation
+
address@hidden
+in a printed book.
+
+The five possible arguments for a cross reference are:@refill
+
address@hidden
address@hidden
+The node or anchor name (required). This is the location to which the
+cross reference takes you. In a printed document, the location of the
+node provides the page reference only for references within the same
address@hidden
+
address@hidden
+The cross reference name for the Info reference, if it is to be different
+from the node name. If you include this argument, it becomes
+the first part of the cross reference. It is usually address@hidden
+
address@hidden
+A topic description or section name. Often, this is the title of the
+section. This is used as the name of the reference in the printed
+manual. If omitted, the node name is address@hidden
+
address@hidden
+The name of the Info file in which the reference is located, if it is
+different from the current file. You need not include any @samp{.info}
+suffix on the file name, since Info readers try appending it
+automatically.
+
address@hidden
+The name of a printed manual from a different Texinfo address@hidden
address@hidden enumerate
+
+The template for a full five argument cross reference looks like
+this:@refill
+
address@hidden
address@hidden
+@@address@hidden@var{node-name}, @var{cross-reference-name},
@var{title-or-topic},
address@hidden, @address@hidden
address@hidden group
address@hidden example
+
+Cross references with one, two, three, four, and five arguments are
+described separately following the description of @code{@@address@hidden
+
+Write a node name in a cross reference in exactly the same way as in
+the @code{@@node} line, including the same capitalization; otherwise, the
+formatters may not find the address@hidden
+
+You can write cross reference commands within a paragraph, but note
+how Info and @TeX{} format the output of each of the various commands:
+write @code{@@xref} at the beginning of a sentence; write
address@hidden@@pxref} only within parentheses, and so address@hidden
+
address@hidden xref, Top Node Naming, Cross Reference Parts, Cross References
address@hidden node-name, next, previous, up
address@hidden @code{@@xref}
address@hidden xref
address@hidden Cross references using @code{@@xref}
address@hidden References using @code{@@xref}
+
+The @code{@@xref} command generates a cross reference for the
+beginning of a sentence. The Info formatting commands convert it into
+an Info cross reference, which the Info @samp{f} command can use to
+bring you directly to another node. The @TeX{} typesetting commands
+convert it into a page reference, or a reference to another book or
address@hidden
+
address@hidden
+* Reference Syntax:: What a reference looks like and requires.
+* 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.
address@hidden menu
+
address@hidden Reference Syntax, One Argument, xref, xref
address@hidden What a Reference Looks Like and Requires
+
+Most often, an Info cross reference looks like this:@refill
+
address@hidden
+*Note @var{node-name}::.
address@hidden example
+
address@hidden
+or like this
+
address@hidden
+*Note @var{cross-reference-name}: @var{node-name}.
address@hidden example
+
address@hidden
+In @TeX{}, a cross reference looks like this:
+
address@hidden
+See Section @var{section-number} address@hidden, page @var{page}.
address@hidden quotation
+
address@hidden
+or like this
+
address@hidden
+See Section @var{section-number} address@hidden, page @var{page}.
address@hidden quotation
+
+The @code{@@xref} command does not generate a period or comma to end
+the cross reference in either the Info file or the printed output.
+You must write that period or comma yourself; otherwise, Info will not
+recognize the end of the reference. (The @code{@@pxref} command works
+differently. @xref{pxref, , @code{@@pxref}}.)@refill
+
address@hidden
address@hidden note:} A period or comma @strong{must} follow the closing
+brace of an @code{@@xref}. It is required to terminate the cross
+reference. This period or comma will appear in the output, both in
+the Info file and in the printed address@hidden
address@hidden quotation
+
address@hidden@@xref} must refer to an Info node by name. Use @code{@@node}
+to define the node (@pxref{Writing a Node})address@hidden
+
address@hidden@@xref} is followed by several arguments inside braces, separated
by
+commas. Whitespace before and after these commas is address@hidden
+
+A cross reference requires only the name of a node; but it may contain
+up to four additional arguments. Each of these variations produces a
+cross reference that looks somewhat address@hidden
+
address@hidden
address@hidden note:} Commas separate arguments in a cross reference;
+avoid including them in the title or other part lest the formatters
+mistake them for address@hidden
address@hidden quotation
+
address@hidden One Argument, Two Arguments, Reference Syntax, xref
address@hidden @code{@@xref} with One Argument
+
+The simplest form of @code{@@xref} takes one argument, the name of
+another node in the same Info file. The Info formatters produce
+output that the Info readers can use to jump to the reference; @TeX{}
+produces output that specifies the page and section number for address@hidden
+
address@hidden 700
address@hidden
+For example,
+
address@hidden
+@@address@hidden address@hidden
address@hidden example
+
address@hidden
+produces
+
address@hidden
+*Note Tropical Storms::.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See Section 3.1 [Tropical Storms], page 24.
address@hidden quotation
+
address@hidden
+(Note that in the preceding example the closing brace is followed by a
+period.)@refill
+
+You can write a clause after the cross reference, like this:@refill
+
address@hidden
+@@address@hidden address@hidden, for more info.
address@hidden example
+
address@hidden
+which produces
+
address@hidden
+*Note Tropical Storms::, for more info.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See Section 3.1 [Tropical Storms], page 24, for more info.
address@hidden quotation
+
address@hidden
+(Note that in the preceding example the closing brace is followed by a
+comma, and then by the clause, which is followed by a period.)@refill
+
address@hidden Two Arguments, Three Arguments, One Argument, xref
address@hidden @code{@@xref} with Two Arguments
+
+With two arguments, the second is used as the name of the Info cross
+reference, while the first is still the name of the node to which the
+cross reference address@hidden
+
address@hidden 750
address@hidden
+The template is like this:
+
address@hidden
+@@address@hidden@var{node-name}, @address@hidden
address@hidden example
+
address@hidden 700
address@hidden
+For example,
+
address@hidden
+@@address@hidden Effects, address@hidden
address@hidden example
+
address@hidden
+produces:
+
address@hidden
+*Note Lightning: Electrical Effects.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See Section 5.2 [Electrical Effects], page 57.
address@hidden quotation
+
address@hidden
+(Note that in the preceding example the closing brace is followed by a
+period; and that the node name is printed, not the cross reference name.)
+
+You can write a clause after the cross reference, like this:@refill
+
address@hidden
+@@address@hidden Effects, address@hidden, for more info.
address@hidden example
+
address@hidden
+which produces
address@hidden
+*Note Lightning: Electrical Effects, for more info.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See Section 5.2 [Electrical Effects], page 57, for more info.
address@hidden quotation
+
address@hidden
+(Note that in the preceding example the closing brace is followed by a
+comma, and then by the clause, which is followed by a period.)@refill
+
address@hidden Three Arguments, Four and Five Arguments, Two Arguments, xref
address@hidden @code{@@xref} with Three Arguments
+
+A third argument replaces the node name in the @TeX{} output. The third
+argument should be the name of the section in the printed output, or
+else state the topic discussed by that section. Often, you will want to
+use initial upper case letters so it will be easier to read when the
+reference is printed. Use a third argument when the node name is
+unsuitable because of syntax or address@hidden
+
+Remember to avoid placing a comma within the title or topic section of
+a cross reference, or within any other section. The formatters divide
+cross references into arguments according to the commas; a comma
+within a title or other section will divide it into two arguments. In
+a reference, you need to write a title such as ``Clouds, Mist, and
+Fog'' without the address@hidden
+
+Also, remember to write a comma or period after the closing brace of an
address@hidden@@xref} to terminate the cross reference. In the following
+examples, a clause follows a terminating address@hidden
+
+
address@hidden 750
address@hidden
+The template is like this:
+
address@hidden
address@hidden
+@@address@hidden@var{node-name}, @var{cross-reference-name}, @address@hidden
address@hidden group
address@hidden example
+
address@hidden 700
address@hidden
+For example,
+
address@hidden
address@hidden
+@@address@hidden Effects, Lightning, Thunder and address@hidden,
+for details.
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
+*Note Lightning: Electrical Effects, for details.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See Section 5.2 [Thunder and Lightning], page 57, for details.
address@hidden quotation
+
+If a third argument is given and the second one is empty, then the
+third argument serves both. (Note how two commas, side by side, mark
+the empty second argument.)@refill
+
address@hidden
address@hidden
+@@address@hidden Effects, , Thunder and address@hidden,
+for details.
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
+*Note Thunder and Lightning: Electrical Effects, for details.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See Section 5.2 [Thunder and Lightning], page 57, for details.
address@hidden quotation
+
+As a practical matter, it is often best to write cross references with
+just the first argument if the node name and the section title are the
+same, and with the first and third arguments if the node name and title
+are address@hidden
+
+Here are several examples from @cite{The GNU Awk User's Guide}:@refill
+
address@hidden
+@@address@hidden address@hidden
+@@address@hidden@}.
+@@address@hidden, ,Case-sensitivity in address@hidden
+@@address@hidden Output, , Closing Output Files and address@hidden,
+ for more information.
+@@address@hidden, , Regular Expressions as address@hidden
address@hidden smallexample
+
address@hidden Four and Five Arguments, , Three Arguments, xref
address@hidden @code{@@xref} with Four and Five Arguments
+
+In a cross reference, a fourth argument specifies the name of another
+Info file, different from the file in which the reference appears, and
+a fifth argument specifies its title as a printed address@hidden
+
+Remember that a comma or period must follow the closing brace of an
address@hidden@@xref} command to terminate the cross reference. In the
+following examples, a clause follows a terminating address@hidden
+
address@hidden 800
address@hidden
+The template is:
+
address@hidden
address@hidden
+@@address@hidden@var{node-name}, @var{cross-reference-name},
@var{title-or-topic},
address@hidden, @address@hidden
address@hidden group
address@hidden example
+
address@hidden 700
address@hidden
+For example,
+
address@hidden
+@@address@hidden Effects, Lightning, Thunder and Lightning,
+weather, An Introduction to address@hidden, for details.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+*Note Lightning: (weather)Electrical Effects, for details.
address@hidden example
+
address@hidden
+The name of the Info file is enclosed in parentheses and precedes
+the name of the node.
+
address@hidden
+In a printed manual, the reference looks like this:@refill
+
address@hidden
+See section ``Thunder and Lightning'' in @i{An Introduction to
+Meteorology}, for details.
address@hidden quotation
+
address@hidden
+The title of the printed manual is typeset in italics; and the
+reference lacks a page number since @TeX{} cannot know to which page a
+reference refers when that reference is to another address@hidden
+
+Often, you will leave out the second argument when you use the long
+version of @code{@@xref}. In this case, the third argument, the topic
+description, will be used as the cross reference name in address@hidden
+
address@hidden
+The template looks like this:
+
address@hidden
+@@address@hidden@var{node-name}, , @var{title-or-topic}, @var{info-file-name},
address@hidden@}, for details.
address@hidden example
+
address@hidden
+which produces
+
address@hidden
+*Note @var{title-or-topic}: (@var{info-file-name})@var{node-name}, for details.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See section @var{title-or-topic} in @var{printed-manual-title}, for details.
address@hidden quotation
+
address@hidden 700
address@hidden
+For example,
+
address@hidden
+@@address@hidden Effects, , Thunder and Lightning,
+weather, An Introduction to address@hidden, for details.
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+*Note Thunder and Lightning: (weather)Electrical Effects,
+for details.
address@hidden group
address@hidden example
+
address@hidden
+and
+
address@hidden
+See section ``Thunder and Lightning'' in @i{An Introduction to
+Meteorology}, for details.
address@hidden quotation
+
+On rare occasions, you may want to refer to another Info file that
+is within a single printed manual---when multiple Texinfo files are
+incorporated into the same @TeX{} run but make separate Info files.
+In this case, you need to specify only the fourth argument, and not
+the address@hidden
+
address@hidden Top Node Naming, ref, xref, Cross References
address@hidden Naming a `Top' Node
address@hidden Naming a `Top' Node in references
address@hidden @address@hidden node naming for references
+
+In a cross reference, you must always name a node. This means that in
+order to refer to a whole manual, you must identify the `Top' node by
+writing it as the first argument to the @code{@@xref} command. (This
+is different from the way you write a menu entry; see @ref{Other Info
+Files, , Referring to Other Info Files}.) At the same time, to
+provide a meaningful section topic or title in the printed cross
+reference (instead of the word `Top'), you must write an appropriate
+entry for the third argument to the @code{@@xref} command.
address@hidden
+
address@hidden
+Thus, to make a cross reference to @cite{The GNU Make Manual},
+write:@refill
+
address@hidden
+@@address@hidden, , Overview, make, The GNU Make address@hidden
address@hidden example
+
address@hidden
+which produces
+
address@hidden
+*Note Overview: (make)Top.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See section ``Overview'' in @i{The GNU Make Manual}.
address@hidden quotation
+
address@hidden
+In this example, @samp{Top} is the name of the first node, and
address@hidden is the name of the first section of the address@hidden
address@hidden ref, pxref, Top Node Naming, Cross References
address@hidden node-name, next, previous, up
address@hidden @code{@@ref}
address@hidden Cross references using @code{@@ref}
address@hidden References using @code{@@ref}
address@hidden ref
+
address@hidden@@ref} is nearly the same as @code{@@xref} except that it does
+not generate a `See' in the printed output, just the reference itself.
+This makes it useful as the last part of a address@hidden
+
address@hidden 700
address@hidden
+For example,
+
address@hidden Hurricanes
address@hidden
+For more information, see @@address@hidden@}.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+For more information, see *Note Hurricanes::.
address@hidden example
+
address@hidden
+and
+
address@hidden
+For more information, see Section 8.2 [Hurricanes], page 123.
address@hidden quotation
+
+The @code{@@ref} command sometimes leads writers to express themselves
+in a manner that is suitable for a printed manual but looks awkward
+in the Info format. Bear in mind that your audience will be using
+both the printed and the Info address@hidden
+
address@hidden 800
address@hidden
+For example,
+
address@hidden Sea surges
address@hidden
address@hidden
+Sea surges are described in @@address@hidden@}.
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+produces
+
address@hidden
+Sea surges are described in Section 6.7 [Hurricanes], page 72.
address@hidden quotation
+
address@hidden 800
address@hidden
+in a printed document, and the following in Info:
+
address@hidden
+Sea surges are described in *Note Hurricanes::.
address@hidden example
+
address@hidden
address@hidden:} You @emph{must} write a period, comma, or right
+parenthesis immediately after an @code{@@ref} command with two or more
+arguments. Otherwise, Info will not find the end of the cross reference
+entry and its attempt to follow the cross reference will fail. As a
+general rule, you should write a period or comma after every
address@hidden@@ref} command. This looks best in both the printed and the Info
address@hidden
address@hidden quotation
+
address@hidden pxref, inforef, ref, Cross References
address@hidden node-name, next, previous, up
address@hidden @code{@@pxref}
address@hidden Cross references using @code{@@pxref}
address@hidden References using @code{@@pxref}
address@hidden pxref
+
+The parenthetical reference command, @code{@@pxref}, is nearly the
+same as @code{@@xref}, but you use it @emph{only} inside parentheses
+and you do @emph{not} type a comma or period after the command's
+closing brace. The command differs from @code{@@xref} in two
+ways:@refill
+
address@hidden
address@hidden
address@hidden typesets the reference for the printed manual with a lower case
+`see' rather than an upper case `See'address@hidden
+
address@hidden
+The Info formatting commands automatically end the reference with a
+closing colon or address@hidden
address@hidden enumerate
+
+Because one type of formatting automatically inserts closing
+punctuation and the other does not, you should use @code{@@pxref}
address@hidden inside parentheses as part of another sentence. Also, you
+yourself should not insert punctuation after the reference, as you do
+with @code{@@address@hidden
+
address@hidden@@pxref} is designed so that the output looks right and works
+right between parentheses both in printed output and in an Info file.
+In a printed manual, a closing comma or period should not follow a
+cross reference within parentheses; such punctuation is wrong. But in
+an Info file, suitable closing punctuation must follow the cross
+reference so Info can recognize its end. @code{@@pxref} spares you
+the need to use complicated methods to put a terminator into one form
+of the output and not the address@hidden
+
address@hidden
+With one argument, a parenthetical cross reference looks like
+this:@refill
+
address@hidden Flooding
address@hidden
address@hidden storms cause flooding (@@address@hidden@}) @dots{}
address@hidden example
+
address@hidden 800
address@hidden
+which produces
+
address@hidden
address@hidden
address@hidden storms cause flooding (*Note Hurricanes::) @dots{}
address@hidden group
address@hidden example
+
address@hidden
+and
+
address@hidden
address@hidden storms cause flooding (see Section 6.7 [Hurricanes], page 72)
@dots{}
address@hidden quotation
+
+With two arguments, a parenthetical cross reference has this
+template:@refill
+
address@hidden
address@hidden (@@address@hidden@var{node-name}, @address@hidden) @dots{}
address@hidden example
+
address@hidden
+which produces
+
address@hidden
address@hidden (*Note @var{cross-reference-name}: @var{node-name}.) @dots{}
address@hidden example
+
address@hidden
+and
+
address@hidden 1500
address@hidden
address@hidden (see Section @var{nnn} address@hidden, page @var{ppp}) @dots{}
address@hidden quotation
+
address@hidden@@pxref} can be used with up to five arguments just like
address@hidden@@xref} (@pxref{xref, , @code{@@xref}})address@hidden
+
address@hidden
address@hidden note:} Use @code{@@pxref} only as a parenthetical
+reference. Do not try to use @code{@@pxref} as a clause in a sentence.
+It will look bad in either the Info file, the printed output, or
address@hidden
+
+Also, parenthetical cross references look best at the ends of sentences.
+Although you may write them in the middle of a sentence, that location
+breaks up the flow of address@hidden
address@hidden quotation
+
address@hidden inforef, uref, pxref, Cross References
address@hidden @code{@@inforef}
address@hidden Cross references using @code{@@inforef}
address@hidden References using @code{@@inforef}
address@hidden inforef
+
address@hidden@@inforef} is used for cross references to Info files for which
+there are no printed manuals. Even in a printed manual,
address@hidden@@inforef} generates a reference directing the user to look in
+an Info address@hidden
+
+The command takes either two or three arguments, in the following
+order:@refill
+
address@hidden
address@hidden
+The node name.
+
address@hidden
+The cross reference name (optional).
+
address@hidden
+The Info file name.
address@hidden enumerate
+
address@hidden
+Separate the arguments with commas, as with @code{@@xref}. Also, you
+must terminate the reference with a comma or period after the
address@hidden@}}, as you do with @code{@@address@hidden
+
address@hidden
+The template is:
+
address@hidden
+@@address@hidden@var{node-name}, @var{cross-reference-name}, @address@hidden,
address@hidden example
+
address@hidden 800
address@hidden
+Thus,
+
address@hidden
address@hidden
+@@address@hidden, Advanced Info commands, address@hidden,
+for more information.
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+produces
+
address@hidden
address@hidden
+*Note Advanced Info commands: (info)Expert,
+for more information.
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+and
+
address@hidden
+See Info file @file{info}, node @samp{Expert}, for more information.
address@hidden quotation
+
address@hidden 800
address@hidden
+Similarly,
+
address@hidden
address@hidden
+@@address@hidden, , address@hidden, for more information.
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+produces
+
address@hidden
+*Note (info)Expert::, for more information.
address@hidden example
+
address@hidden 800
address@hidden
+and
+
address@hidden
+See Info file @file{info}, node @samp{Expert}, for more information.
address@hidden quotation
+
+The converse of @code{@@inforef} is @code{@@cite}, which is used to
+refer to printed works for which no Info form exists. @xref{cite, ,
address@hidden@@address@hidden
+
+
address@hidden uref
address@hidden @code{@@address@hidden@var{url}[, @var{text}][, @address@hidden
address@hidden uref
address@hidden Uniform resource locator, referring to
address@hidden URL, referring to
+
address@hidden @code{href}, producing HTML
address@hidden@@uref} produces a reference to a uniform resource locator (url).
+It takes one mandatory argument, the url, and two optional arguments
+which control the text that is displayed. In HTML output, @code{@@uref}
+produces a link you can follow.
+
+The second argument, if specified, is the text to display (the default
+is the url itself); in Info and DVI output, but not in HTML output, the
+url is also output.
+
address@hidden Man page, reference to
+The third argument, on the other hand, if specified is also the text to
+display, but the url is @emph{not} output in any format. This is useful
+when the text is already sufficiently referential, as in a man page. If
+the third argument is given, the second argument is ignored.
+
+The simple one argument form, where the url is both the target and the
+text of the link:
+
address@hidden
+The official GNU ftp site is @@address@hidden://ftp.gnu.org/address@hidden
address@hidden example
+
address@hidden produces:
address@hidden
+The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}.
address@hidden display
+
+
+An example of the two-argument form:
address@hidden
+The official @@address@hidden://ftp.gnu.org/gnu, GNU ftp address@hidden
+holds programs and texts.
address@hidden example
+
address@hidden produces:
address@hidden
+The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site}
+holds programs and texts.
address@hidden display
+
address@hidden that is, the Info output is this:
address@hidden
+The official GNU ftp site (ftp://ftp.gnu.org/gnu)
+holds programs and texts.
address@hidden example
+
address@hidden and the HTML output is this:
address@hidden
+The official <a href="ftp://ftp.gnu.org/gnu";>GNU ftp site</a>
+holds programs and texts.
address@hidden example
+
+
+An example of the three-argument form:
address@hidden
+The @@address@hidden/man.cgi/1/ls,,ls(1)@} program @dots{}
address@hidden example
+
address@hidden produces:
address@hidden
+The @uref{/man.cgi/1/ls,,ls(1)} program @dots{}
address@hidden display
+
address@hidden but with HTML:
address@hidden
+The <a href="/man.cgi/1/ls">ls(1)</a> program @dots{}
address@hidden example
+
+To merely indicate a url without creating a link people can follow, use
address@hidden@@url} (@pxref{url, @code{@@url}}).
+
+Some people prefer to display url's in the unambiguous format:
+
address@hidden
+<URL:http://@var{host}/@var{path}>
address@hidden display
+
address@hidden
address@hidden <URL convention, not used
+You can use this form in the input file if you wish. We feel it's not
+necessary to clutter up the output with the extra @samp{<URL:} and
address@hidden>}, since any software that tries to detect url's in text already
+has to detect them without the @samp{<URL:} to be useful.
+
+
address@hidden Marking Text
address@hidden Marking Words and Phrases
address@hidden Paragraph, marking text within
address@hidden Marking words and phrases
address@hidden Words and phrases, marking them
address@hidden Marking text within a paragraph
address@hidden Text, marking up
+
+In Texinfo, you can mark words and phrases in a variety of ways.
+The Texinfo formatters use this information to determine how to
+highlight the text.
+You can specify, for example, whether a word or phrase is a
+defining occurrence, a metasyntactic variable, or a symbol used in a
+program. Also, you can emphasize text, in several different ways.
+
address@hidden
+* Indicating:: How to indicate definitions, files, etc.
+* Emphasis:: How to emphasize text.
address@hidden menu
+
+
address@hidden Indicating, Emphasis, Marking Text, Marking Text
address@hidden Indicating Definitions, Commands, etc.
address@hidden Highlighting text
address@hidden Indicating commands, definitions, etc.
+
+Texinfo has commands for indicating just what kind of object a piece of
+text refers to. For example, metasyntactic variables are marked by
address@hidden@@var}, and code by @code{@@code}. Since the pieces of text are
+labelled by commands that tell what kind of object they are, it is easy
+to change the way the Texinfo formatters prepare such text. (Texinfo is
+an @emph{intentional} formatting language rather than a @emph{typesetting}
+formatting language.)@refill
+
+For example, in a printed manual,
+code is usually illustrated in a typewriter font;
address@hidden@@code} tells @TeX{} to typeset this text in this font. But it
+would be easy to change the way @TeX{} highlights code to use another
+font, and this change would not affect how keystroke examples are
+highlighted. If straight typesetting commands were used in the body
+of the file and you wanted to make a change, you would need to check
+every single occurrence to make sure that you were changing code and
+not something else that should not be address@hidden
+
address@hidden
+* Useful Highlighting:: Highlighting provides useful information.
+* code:: Indicating program code.
+* kbd:: Showing keyboard input.
+* key:: Specifying keys.
+* samp:: A literal sequence of characters.
+* verb:: A verbatim sequence of characters.
+* var:: Indicating metasyntactic variables.
+* env:: Indicating environment variables.
+* file:: Indicating file names.
+* command:: Indicating command names.
+* option:: Indicating option names.
+* dfn:: Specifying definitions.
+* cite:: Referring to books not in the Info system.
+* acronym:: Indicating acronyms.
+* url:: Indicating a World Wide Web reference.
+* email:: Indicating an electronic mail address.
address@hidden menu
+
+
address@hidden Useful Highlighting, code, Indicating, Indicating
address@hidden Highlighting Commands are Useful
+
+The highlighting commands can be used to extract useful information
+from the file, such as lists of functions or file names. It is
+possible, for example, to write a program in Emacs Lisp (or a keyboard
+macro) to insert an index entry after every paragraph that contains
+words or phrases marked by a specified command. You could do this to
+construct an index of functions if you had not already made the
address@hidden
+
+The commands serve a variety of purposes:@refill
+
address@hidden @code
address@hidden @@address@hidden@address@hidden
+Indicate text that is a literal example of a piece of a address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate keyboard address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate the conventional name for a key on a address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate text that is a literal example of a sequence of address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate a metasyntactic address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate an environment address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate the name of a address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate the name of a address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate a command-line address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate the introductory or defining use of a address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate the name of a address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate an address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate a uniform resource locator for the World Wide Web.
+
address@hidden @@address@hidden@var{email-address}[, @address@hidden
+Indicate an electronic mail address.
+
address@hidden table
+
+
address@hidden code
address@hidden @code{@@address@hidden@address@hidden
address@hidden code
+
address@hidden Syntactic tokens, indicating
+Use the @code{@@code} command to indicate text that is a piece of a
+program and which consists of entire syntactic tokens. Enclose the
+text in braces.
+
address@hidden Expressions in a program, indicating
address@hidden Keywords, indicating
address@hidden Reserved words, indicating
+Thus, you should use @code{@@code} for an expression in a program, for
+the name of a variable or function used in a program, or for a
+keyword in a programming language.
+
+Use @code{@@code} for command names in languages that resemble
+programming languages, such as Texinfo. For example, @code{@@code} and
address@hidden@@samp} are produced by writing
@samp{@@address@hidden@@@@address@hidden and
address@hidden@@address@hidden@@@@address@hidden in the Texinfo source,
respectively.
+
address@hidden Case, not altering in @code{@@code}
+It is incorrect to alter the case of a word inside an @code{@@code}
+command when it appears at the beginning of a sentence. Most computer
+languages are case sensitive. In C, for example, @code{Printf} is
+different from the identifier @code{printf}, and most likely is a
+misspelling of it. Even in languages which are not case sensitive, it
+is confusing to a human reader to see identifiers spelled in different
+ways. Pick one spelling and always use that. If you do not want to
+start a sentence with a command name written all in lower case, you
+should rearrange the sentence.
+
+In the printed manual, @code{@@code} causes @TeX{} to typeset the
+argument in a typewriter face. In the Info file, it causes the Info
+formatting commands to use single quotation marks around the text.
+
address@hidden 700
+For example,
+
address@hidden
+The function returns @@address@hidden@}.
address@hidden example
+
address@hidden
+produces this in the printed manual:
+
address@hidden
+The function returns @code{nil}.
address@hidden quotation
+
+
+Here are some cases for which it is preferable not to use @code{@@code}:
+
address@hidden @bullet
address@hidden
+For shell command names such as @command{ls} (use @code{@@command}).
+
address@hidden
+For shell options such as @samp{-c} when such options stand alone (use
address@hidden@@option}).
+
address@hidden
+Also, an entire shell command often looks better if written using
address@hidden@@samp} rather than @code{@@code}. In this case, the rule is to
+choose the more pleasing format.
+
address@hidden
+For environment variable such as @env{TEXINPUTS} (use @code{@@env}).
+
address@hidden
+For a string of characters shorter than a syntactic token. For example,
+if you are writing about @samp{goto-ch}, which is just a part of the
+name for the @code{goto-char} Emacs Lisp function, you should use
address@hidden@@samp}.
+
address@hidden
+In general, when writing about the characters used in a token; for
+example, do not use @code{@@code} when you are explaining what letters
+or printable symbols can be used in the names of functions. (Use
address@hidden@@samp}.) Also, you should not use @code{@@code} to mark text
+that is considered input to programs unless the input is written in a
+language that is like a programming language. For example, you should
+not use @code{@@code} for the keystroke commands of GNU Emacs (use
address@hidden@@kbd} instead) although you may use @code{@@code} for the names
+of the Emacs Lisp functions that the keystroke commands invoke.
+
address@hidden itemize
+
+Since @code{@@command}, @code{@@option}, and @code{@@env} were
+introduced relatively recently, it is acceptable to use @code{@@code} or
address@hidden@@samp} for command names, options, and environment variables.
+The new commands allow you to express the markup more precisely, but
+there is no real harm in using the older commands, and of course the
+long-standing manuals do so.
+
+
address@hidden kbd
address@hidden @code{@@address@hidden@address@hidden
address@hidden kbd
address@hidden Keyboard input
+
+Use the @code{@@kbd} command for characters of input to be typed by
+users. For example, to refer to the characters @kbd{M-a},
address@hidden
+
address@hidden
+@@address@hidden@}
address@hidden example
+
address@hidden
+and to refer to the characters @kbd{M-x shell}, address@hidden
+
address@hidden
+@@address@hidden address@hidden
address@hidden example
+
address@hidden user input
address@hidden slanted typewriter font, for @code{@@kbd}
+The @code{@@kbd} command has the same effect as @code{@@code} in Info,
+but by default produces a different font (slanted typewriter instead of
+normal typewriter) in the printed manual, so users can distinguish the
+characters they are supposed to type from those the computer outputs.
+
address@hidden kbdinputstyle
+Since the usage of @code{@@kbd} varies from manual to manual, you can
+control the font switching with the @code{@@kbdinputstyle} command.
+This command has no effect on Info output. Write this command at the
+beginning of a line with a single word as an argument, one of the
+following:
address@hidden address@hidden, arg to @@kbdinputstyle}
address@hidden address@hidden, arg to @@kbdinputstyle}
address@hidden address@hidden, arg to @@kbdinputstyle}
address@hidden @samp
address@hidden code
+Always use the same font for @code{@@kbd} as @code{@@code}.
address@hidden example
+Use the distinguishing font for @code{@@kbd} only in @code{@@example}
+and similar environments.
address@hidden distinct
+(the default) Always use the distinguishing font for @code{@@kbd}.
address@hidden table
+
+You can embed another @@-command inside the braces of an @code{@@kbd}
+command. Here, for example, is the way to describe a command that
+would be described more verbosely as ``press an @samp{r} and then
+press the @key{RET} key'':@refill
+
address@hidden
+@@address@hidden @@address@hidden@address@hidden
address@hidden example
+
address@hidden
+This produces: @kbd{r @key{RET}}
+
+You also use the @code{@@kbd} command if you are spelling out the letters
+you type; for example:@refill
+
address@hidden
+To give the @@address@hidden@} command,
+type the characters @@address@hidden o g o u t @@address@hidden@address@hidden
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
+To give the @code{logout} command,
+type the characters @kbd{l o g o u t @key{RET}}.
address@hidden quotation
+
+(Also, this example shows that you can add spaces for clarity. If you
+really want to mention a space character as one of the characters of
+input, write @kbd{@@address@hidden@}} for it.)@refill
+
+
address@hidden key, samp, kbd, Indicating
address@hidden node-name, next, previous, up
address@hidden @code{@@address@hidden@address@hidden
address@hidden key
+
+Use the @code{@@key} command for the conventional name for a key on a
+keyboard, as in:@refill
+
address@hidden
+@@address@hidden@}
address@hidden example
+
+You can use the @code{@@key} command within the argument of an
address@hidden@@kbd} command when the sequence of characters to be typed
+includes one or more keys that are described by address@hidden
+
address@hidden 700
+For example, to produce @kbd{C-x @key{ESC}} you would type:@refill
+
address@hidden
+@@address@hidden @@address@hidden@address@hidden
address@hidden example
+
+Here is a list of the recommended names for keys:
address@hidden Recommended names for keys
address@hidden Keys, recommended names
address@hidden Names recommended for keys
address@hidden Abbreviations for keys
+
address@hidden
address@hidden @t
address@hidden SPC
+Space
address@hidden RET
+Return
address@hidden LFD
+Linefeed (however, since most keyboards nowadays do not have a Linefeed key,
+it might be better to call this character @kbd{C-j}.
address@hidden TAB
+Tab
address@hidden BS
+Backspace
address@hidden ESC
+Escape
address@hidden DEL
+Delete
address@hidden SHIFT
+Shift
address@hidden CTRL
+Control
address@hidden META
+Meta
address@hidden table
address@hidden quotation
+
address@hidden META key
+There are subtleties to handling words like `meta' or `ctrl' that are
+names of modifier keys. When mentioning a character in which the
+modifier key is used, such as @kbd{Meta-a}, use the @code{@@kbd} command
+alone; do not use the @code{@@key} command; but when you are referring
+to the modifier key in isolation, use the @code{@@key} command. For
+example, write @samp{@@address@hidden@}} to produce @kbd{Meta-a} and
address@hidden@@address@hidden@}} to produce @key{META}.
+
address@hidden I don't think this is a good explanation.
address@hidden I think it will puzzle readers more than it clarifies matters.
-- rms.
address@hidden In other words, use @code{@@kbd} for what you do, and use
@code{@@key}
address@hidden for what you talk about: ``Press @code{@@address@hidden@}} to
move point to
address@hidden the beginning of the sentence. The @code{@@address@hidden@}}
key is often in
address@hidden the lower left of the keyboard.''@refill
+
address@hidden samp
address@hidden @code{@@address@hidden@address@hidden
address@hidden samp
+
+Use the @code{@@samp} command to indicate text that is a literal example
+or `sample' of a sequence of characters in a file, string, pattern, etc.
+Enclose the text in braces. The argument appears within single
+quotation marks in both the Info file and the printed manual; in
+addition, it is printed in a fixed-width address@hidden
+
address@hidden
+To match @@address@hidden@} at the end of the line,
+use the regexp @@address@hidden@}.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+To match @samp{foo} at the end of the line, use the regexp
address@hidden@refill
address@hidden quotation
+
+Any time you are referring to single characters, you should use
address@hidden@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate.
+Also, you may use @code{@@samp} for entire statements in C and for entire
+shell commands---in this case, @code{@@samp} often looks better than
address@hidden@@code}. Basically, @code{@@samp} is a catchall for whatever is
+not covered by @code{@@code}, @code{@@kbd}, or @code{@@address@hidden
+
+Only include punctuation marks within braces if they are part of the
+string you are specifying. Write punctuation marks outside the braces
+if those punctuation marks are part of the English text that surrounds
+the string. In the following sentence, for example, the commas and
+period are outside of the braces:@refill
+
address@hidden
address@hidden
+In English, the vowels are @@address@hidden@}, @@address@hidden@},
+@@address@hidden@}, @@address@hidden@}, @@address@hidden@}, and sometimes
+@@address@hidden@}.
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
+In English, the vowels are @samp{a}, @samp{e},
address@hidden, @samp{o}, @samp{u}, and sometimes
address@hidden
address@hidden quotation
+
+
address@hidden verb
address@hidden @code{@@address@hidden<char>@var{text}<char>@}
address@hidden verb
address@hidden Verbatim in-line text
+
address@hidden Delimiter character, for verbatim
+Use the @code{@@verb} command to print a verbatim sequence of
+characters.
+
+Like address@hidden's @code{\verb} command, the verbatim text can be quoted
using
+any unique delimiter character. Enclose the verbatim text, including the
+delimiters, in braces. Text is printed in a fixed-width font:
+
address@hidden
+How many @@address@hidden|@@|@}-escapes does one need to print this
+@@address@hidden@@a @@b @@address@hidden string or
@@address@hidden@@'address@hidden@address@hidden@address@hidden this?
address@hidden example
+
address@hidden
+produces
+
address@hidden
+How many @verb{|@ |}-escapes does one need to print this
address@hidden@a @b @c.} string or these @verb{+@'e?`{}!`\+} this?
address@hidden example
+
+This is in contrast to @code{@@samp} (see the previous
+section), whose argument is normal Texinfo text, where the characters
address@hidden@@@address@hidden are special; with @code{@@verb}, nothing is
special except
+the delimiter character you choose.
+
+
address@hidden var
address@hidden @code{@@address@hidden@address@hidden
address@hidden var
+
+Use the @code{@@var} command to indicate metasyntactic variables. A
address@hidden variable} is something that stands for another piece of
+text. For example, you should use a metasyntactic variable in the
+documentation of a function to describe the arguments that are passed
+to that address@hidden
+
+Do not use @code{@@var} for the names of particular variables in
+programming languages. These are specific names from a program, so
address@hidden@@code} is correct for them (@pxref{code}). For example, the
+Emacs Lisp variable @code{texinfo-tex-command} is not a metasyntactic
+variable; it is properly formatted using @code{@@code}.
+
+Do not use @code{@@var} for environment variables either; @code{@@env}
+is correct for them (see the next section).
+
+The effect of @code{@@var} in the Info file is to change the case of the
+argument to all upper case. In the printed manual and HTML output, the
+argument is printed in slanted type.
+
address@hidden 700
+For example,
+
address@hidden
+To delete file @@address@hidden@},
+type @@address@hidden @@address@hidden@address@hidden
address@hidden example
+
address@hidden
+produces
+
address@hidden
+To delete file @var{filename}, type @samp{rm @var{filename}}.
address@hidden quotation
+
address@hidden
+(Note that @code{@@var} may appear inside @code{@@code},
address@hidden@@samp}, @code{@@file}, etc.)@refill
+
+Write a metasyntactic variable all in lower case without spaces, and
+use hyphens to make it more readable. Thus, the Texinfo source for
+the illustration of how to begin a Texinfo manual looks like
+this:@refill
+
address@hidden
address@hidden
+\input texinfo
+@@@@setfilename @@address@hidden@}
+@@@@settitle @@address@hidden@}
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
address@hidden
+\input texinfo
+@@setfilename @var{info-file-name}
+@@settitle @var{name-of-manual}
address@hidden group
address@hidden example
+
+In some documentation styles, metasyntactic variables are shown with
+angle brackets, for example:@refill
+
address@hidden
address@hidden, type rm <filename>
address@hidden example
+
address@hidden
+However, that is not the style that Texinfo uses. (You can, of
+course, modify the sources to @file{texinfo.tex} and the Info formatting
commands
+to output the @code{<@dots{}>} format if you wish.)@refill
+
+
address@hidden env
address@hidden @code{@@address@hidden@address@hidden
address@hidden env
+
+Use the @code{@@env} command to indicate environment variables, as used
+by many operating systems, including GNU. Do not use it for
+metasyntactic variables; use @code{@@var} instead (see the previous
+section).
+
address@hidden@@env} is equivalent to @code{@@code} in its effects.
+For example:
+
address@hidden
+The @@address@hidden@} environment variable @dots{}
address@hidden example
address@hidden produces
address@hidden
+The @env{PATH} environment variable @dots{}
address@hidden quotation
+
+
address@hidden file
address@hidden @code{@@address@hidden@address@hidden
address@hidden file
+
+Use the @code{@@file} command to indicate text that is the name of a
+file, buffer, or directory, or is the name of a node in Info. You can
+also use the command for file name suffixes. Do not use @code{@@file}
+for symbols in a programming language; use @code{@@code}.
+
+Currently, @code{@@file} is equivalent to @code{@@samp} in its effects.
+For example,@refill
+
address@hidden
+The @@address@hidden@} files are in
+the @@address@hidden/usr/local/emacs/address@hidden directory.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+The @file{.el} files are in
+the @file{/usr/local/emacs/lisp} directory.
address@hidden quotation
+
+
address@hidden command
address@hidden @code{@@address@hidden@address@hidden
address@hidden command
address@hidden Command names, indicating
address@hidden Program names, indicating
+
+Use the @code{@@command} command to indicate command names, such as
address@hidden or @command{cc}.
+
address@hidden@@command} is equivalent to @code{@@code} in its effects.
+For example:
+
address@hidden
+The command @@address@hidden@} lists directory contents.
address@hidden example
address@hidden produces
address@hidden
+The command @command{ls} lists directory contents.
address@hidden quotation
+
+You should write the name of a program in the ordinary text font, rather
+than using @code{@@command}, if you regard it as a new English word,
+such as `Emacs' or `Bison'.
+
+When writing an entire shell command invocation, as in @samp{ls -l},
+you should use either @code{@@samp} or @code{@@code} at your discretion.
+
+
address@hidden option
address@hidden @code{@@address@hidden@address@hidden
address@hidden option
+
+Use the @code{@@option} command to indicate a command-line option; for
+example, @option{-l} or @option{--version} or
address@hidden@var{filename}}.
+
address@hidden@@option} is equivalent to @code{@@samp} in its effects.
+For example:
+
address@hidden
+The option @@address@hidden@} produces a long listing.
address@hidden example
address@hidden produces
address@hidden
+The option @option{-l} produces a long listing.
address@hidden quotation
+
+In tables, putting options inside @code{@@code} produces a
+more pleasing effect.
+
address@hidden dfn
address@hidden node-name, next, previous, up
address@hidden @code{@@address@hidden@address@hidden
address@hidden dfn
+
+Use the @code{@@dfn} command to identify the introductory or defining
+use of a technical term. Use the command only in passages whose
+purpose is to introduce a term which will be used again or which the
+reader ought to know. Mere passing mention of a term for the first
+time does not deserve @code{@@dfn}. The command generates italics in
+the printed manual, and double quotation marks in the Info file. For
+example:@refill
+
address@hidden
+Getting rid of a file is called @@address@hidden@} it.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+Getting rid of a file is called @dfn{deleting} it.
address@hidden quotation
+
+As a general rule, a sentence containing the defining occurrence of a
+term should be a definition of the term. The sentence does not need
+to say explicitly that it is a definition, but it should contain the
+information of a definition---it should make the meaning clear.
+
address@hidden cite
address@hidden @code{@@address@hidden@address@hidden
address@hidden cite
+
+Use the @code{@@cite} command for the name of a book that lacks a
+companion Info file. The command produces italics in the printed
+manual, and quotation marks in the Info file.
+
+If a book is written in Texinfo, it is better to use a cross reference
+command since a reader can easily follow such a reference in Info.
address@hidden, , @code{@@xref}}.
+
+
+
+
address@hidden acronym
address@hidden @code{@@address@hidden@address@hidden
address@hidden acronym
+
address@hidden NASA, as acronym
address@hidden F.B.I., as acronym
address@hidden Abbreviations, tagging
address@hidden Acronyms, tagging
+Use the @code{@@acronym} command for abbreviations written in all
+capital letters, such as address@hidden'. The abbreviation is given as
+the single argument in braces, as in @samp{@@address@hidden@}}. As
+a matter of style, or for particular abbreviations, you may prefer to
+use periods, as in @samp{@@address@hidden@}}.
+
+In @TeX{} and HTML, the argument is printed in a slightly smaller font
+size. In Info or plain text output, this command changes nothing.
+
+
address@hidden url
address@hidden @code{@@address@hidden@address@hidden
address@hidden url
address@hidden Uniform resource locator, indicating
address@hidden URL, indicating
+
+Use the @code{@@url} command to indicate a uniform resource locator on
+the World Wide Web. This is analogous to @code{@@file}, @code{@@var},
+etc., and is purely for markup purposes. It does not produce a link you
+can follow in HTML output (use the @code{@@uref} command for that,
address@hidden,, @code{@@uref}}). It is useful for url's which do
+not actually exist. For example:
+
address@hidden Two lines because one is too long for smallbook format.
address@hidden
+For example, the url might be @@address@hidden://example.org/address@hidden
address@hidden example
+
address@hidden which produces:
+
address@hidden
+For example, the url might be @url{http://example.org/path}.
address@hidden display
+
+
address@hidden email
address@hidden @code{@@address@hidden@var{email-address}[, @address@hidden
address@hidden email
+
+Use the @code{@@email} command to indicate an electronic mail address.
+It takes one mandatory argument, the address, and one optional argument, the
+text to display (the default is the address itself).
+
address@hidden mailto link
+In Info and @TeX{}, the address is shown in angle brackets, preceded by
+the text to display if any. In HTML output, @code{@@email} produces a
address@hidden link that usually brings up a mail composition window.
+For example:
+
address@hidden
+Send bug reports to @@address@hidden@@@@address@hidden,
+suggestions to the @@address@hidden@@@@gnu.org, same address@hidden
address@hidden example
address@hidden produces
address@hidden
+Send bug reports to @email{bug-texinfo@@gnu.org},
+suggestions to the @email{bug-texinfo@@gnu.org, same place}.
address@hidden display
+
+
address@hidden Emphasis
address@hidden node-name, next, previous, up
address@hidden Emphasizing Text
address@hidden Emphasizing text
+
+Usually, Texinfo changes the font to mark words in the text according to
+what category the words belong to; an example is the @code{@@code} command.
+Most often, this is the best way to mark words.
+However, sometimes you will want to emphasize text without indicating a
+category. Texinfo has two commands to do this. Also, Texinfo has
+several commands that specify the font in which @TeX{} will typeset
+text. These commands have no effect on Info and only one of them,
+the @code{@@r} command, has any regular address@hidden
+
address@hidden
+* emph & strong:: How to emphasize text in Texinfo.
+* Smallcaps:: How to use the small caps font.
+* Fonts:: Various font commands for printed output.
address@hidden menu
+
address@hidden emph & strong
address@hidden @code{@@address@hidden@address@hidden and
@code{@@address@hidden@address@hidden
address@hidden Emphasizing text, font for
address@hidden emph
address@hidden strong
+
+The @code{@@emph} and @code{@@strong} commands are for emphasis;
address@hidden@@strong} is stronger. In printed output, @code{@@emph} produces
address@hidden and @code{@@strong} produces @strong{bold}.
+
address@hidden 800
+For example,
+
address@hidden
address@hidden
+@@quotation
+@@address@hidden:@} @@address@hidden * address@hidden removes
@@address@hidden@}
+files in the directory.
+@@end quotation
address@hidden group
address@hidden example
+
address@hidden
+produces:
+
address@hidden
+ *Caution*: `rm * .[^.]*' removes _all_
+ files in the directory.
address@hidden example
+
+The @code{@@strong} command is seldom used except to mark what is, in
+effect, a typographical element, such as the word `Caution' in the
+preceding example.
+
+In the Info output, @code{@@emph} surrounds the text with underscores
+(@samp{_}), and @code{@@strong} puts asterisks around the text.
+
address@hidden
address@hidden:} Do not use @code{@@strong} with the word @samp{Note};
+Info will mistake the combination for a cross reference. Use a phrase
+such as @strong{Please note} or @strong{Caution} instead.
address@hidden quotation
+
+
address@hidden Smallcaps
address@hidden @code{@@address@hidden@address@hidden: The Small Caps Font
address@hidden Small caps font
address@hidden sc @r{(small caps font)}
+
+Use the @samp{@@sc} command to set text in the printed and the HTML
+output in @sc{a small caps font} and set text in the Info file in upper
+case letters. Write the text you want to be in small caps (where
+possible) between braces in lower case, like this:
+
address@hidden
+The @@address@hidden@} and @@address@hidden@} are technical societies.
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
+The @sc{acm} and @sc{ieee} are technical societies.
address@hidden display
+
address@hidden typesets the small caps font in a manner that prevents the
+letters from `jumping out at you on the page'. This makes small caps
+text easier to read than text in all upper case---but it's usually
+better to use regular mixed case anyway. The Info formatting commands
+set all small caps text in upper case. In HTML, the text is upper-cased
+and a smaller font is used to render it.
+
+If the text between the braces of an @code{@@sc} command is uppercase,
address@hidden typesets in FULL-SIZE CAPITALS. Use full-size capitals
+sparingly, if ever, and since it's redundant to mark all-uppercase text
+with @code{@@sc}, @command{makeinfo} warns about such usage.
+
+You may also use the small caps font for a jargon word such as
address@hidden (a @sc{nasa} word meaning `abort to orbit').
+
+There are subtleties to using the small caps font with a jargon word
+such as @sc{cdr}, a word used in Lisp programming. In this case, you
+should use the small caps font when the word refers to the second and
+subsequent elements of a list (the @sc{cdr} of the list), but you
+should use @samp{@@code} when the word refers to the Lisp function of
+the same spelling.
+
+
address@hidden Fonts
address@hidden Fonts for Printing, Not Info
address@hidden Fonts for printing, not for Info
address@hidden i @r{(italic font)}
address@hidden b @r{(bold font)}
address@hidden t @r{(typewriter font)}
address@hidden r @r{(Roman font)}
+
+Texinfo provides four font commands that specify font changes in the
+printed manual but have no effect in the Info file. @code{@@i}
+requests @i{italic} font (in some versions of @TeX{}, a slanted font
+is used), @code{@@b} requests @b{bold} face, @code{@@t} requests the
address@hidden, typewriter-style font used by @code{@@code}, and @code{@@r}
requests a
address@hidden font, which is the usual font in which text is printed. All
+four commands apply to an argument that follows, surrounded by
address@hidden
+
+Only the @code{@@r} command has much use: in example programs, you
+can use the @code{@@r} command to convert code comments from the
+fixed-width font to a roman font. This looks better in printed
address@hidden
+
address@hidden 700
+For example,
+
address@hidden
address@hidden
+@@lisp
+(+ 2 2) ; @@address@hidden two plus address@hidden
+@@end lisp
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
+(+ 2 2) ; @r{Add two plus two.}
address@hidden lisp
+
+If possible, you should avoid using the other three font commands. If
+you need to use one, it probably indicates a gap in the Texinfo
+language.
+
+
address@hidden Quotations and Examples
address@hidden Quotations and Examples
+
+Quotations and examples are blocks of text consisting of one or more
+whole paragraphs that are set off from the bulk of the text and
+treated differently. They are usually address@hidden
+
+In Texinfo, you always begin a quotation or example by writing an
+@@-command at the beginning of a line by itself, and end it by writing
+an @code{@@end} command that is also at the beginning of a line by
+itself. For instance, you begin an example by writing @code{@@example}
+by itself at the beginning of a line and end the example by writing
address@hidden@@end example} on a line by itself, at the beginning of that
+line.
address@hidden end
+
address@hidden
+* Block Enclosing Commands:: Different constructs for different purposes.
+* quotation:: Writing a quotation.
+* example:: Writing an example in a fixed-width font.
+* verbatim:: Writing a verbatim example.
+* verbatiminclude:: Including a file verbatim.
+* lisp:: Illustrating Lisp code.
+* small:: Forms for @code{@@smallbook}.
+* display:: Writing an example in the current font.
+* format:: Writing an example without narrowed margins.
+* exdent:: Undo indentation on a line.
+* flushleft & flushright:: Pushing text flush left or flush right.
+* noindent:: Preventing paragraph indentation.
+* cartouche:: Drawing rounded rectangles around examples.
address@hidden menu
+
+
address@hidden Block Enclosing Commands
address@hidden Block Enclosing Commands
+
+Here are commands for quotations and examples, explained further in the
+following sections:
+
address@hidden @code
address@hidden @@quotation
+Indicate text that is quoted. The text is filled, indented, and
+printed in a roman font by default.
+
address@hidden @@example
+Illustrate code, commands, and the like. The text is printed
+in a fixed-width font, and indented but not filled.
+
address@hidden @@verbatim
+Mark a piece of text that is to be printed verbatim; no character
+substitutions are made and all commands are ignored, until the next
address@hidden@@end verbatim}. The text is printed in a fixed-width font,
+and not indented or filled. Extra spaces and blank lines are
+significant, and tabs are expanded.
+
address@hidden @@smallexample
+Same as @code{@@example}, except that in @TeX{} this command typesets
+text in a smaller font.
+
address@hidden @@lisp
+Like @code{@@example}, but specifically for illustrating Lisp code. The
+text is printed in a fixed-width font, and indented but not filled.
+
address@hidden @@smalllisp
+Is to @code{@@lisp} as @code{@@smallexample} is to @code{@@example}.
+
address@hidden @@display
+Display illustrative text. The text is indented but not filled, and
+no font is selected (so, by default, the font is roman)address@hidden
+
address@hidden @@smalldisplay
+Is to @code{@@display} as @code{@@smallexample} is to @code{@@example}.
+
address@hidden @@format
+Like @code{@@display} (the text is not filled and no font is selected),
+but the text is not indented.
+
address@hidden @@smallformat
+Is to @code{@@format} as @code{@@smallexample} is to @code{@@example}.
address@hidden table
+
+The @code{@@exdent} command is used within the above constructs to
+undo the indentation of a line.
+
+The @code{@@flushleft} and @code{@@flushright} commands are used to line
+up the left or right margins of unfilled address@hidden
+
+The @code{@@noindent} command may be used after one of the above
+constructs to prevent the following text from being indented as a new
+paragraph.
+
+You can use the @code{@@cartouche} command within one of the above
+constructs to highlight the example or quotation by drawing a box with
+rounded corners around it. @xref{cartouche, , Drawing Cartouches Around
+Examples}.
+
+
address@hidden quotation
address@hidden @code{@@quotation}
address@hidden Quotations
address@hidden quotation
+
+The text of a quotation is processed normally except that:
+
address@hidden @bullet
address@hidden
+the margins are closer to the center of the page, so the whole of the
+quotation is indented;@refill
+
address@hidden
+the first lines of paragraphs are indented no more than other
+lines;@refill
+
address@hidden
+in the printed output, interparagraph spacing is address@hidden
address@hidden itemize
+
address@hidden
+This is an example of text written between an @code{@@quotation}
+command and an @code{@@end quotation} command. An @code{@@quotation}
+command is most often used to indicate text that is excerpted from
+another (real or hypothetical) printed address@hidden
address@hidden quotation
+
+Write an @code{@@quotation} command as text on a line by itself. This
+line will disappear from the output. Mark the end of the quotation
+with a line beginning with and containing only @code{@@end quotation}.
+The @code{@@end quotation} line will likewise disappear from the
+output. Thus, the following,@refill
+
address@hidden
+@@quotation
+This is
+a foo.
+@@end quotation
address@hidden example
+
address@hidden
+produces
+
address@hidden
+This is a foo.
address@hidden quotation
+
+
address@hidden example
address@hidden @code{@@example}: Example Text
address@hidden Examples, formatting them
address@hidden Formatting examples
address@hidden example
+
+The @code{@@example} command is used to indicate an example that is
+not part of the running text, such as computer input or output.
+
address@hidden
address@hidden
+This is an example of text written between an
address@hidden@@example} command
+and an @code{@@end example} command.
+The text is indented but not filled.
address@hidden group
+
address@hidden
+In the printed manual, the text is typeset in a
+fixed-width font, and extra spaces and blank lines are
+significant. In the Info file, an analogous result is
+obtained by indenting each line with five spaces.
address@hidden group
address@hidden example
+
+Write an @code{@@example} command at the beginning of a line by itself.
+Mark the end of the example
+with an @code{@@end example} command, also written at the beginning of a
+line by address@hidden
+
address@hidden 700
+For example,
+
address@hidden
+@@example
+mv foo bar
+@@end example
address@hidden example
+
address@hidden
+produces
+
address@hidden
+mv foo bar
address@hidden example
+
+The lines containing @code{@@example} and @code{@@end example}
+will disappear from the output.
+To make the output look good,
+you should put a blank line before the
address@hidden@@example} and another blank line after the @code{@@end example}.
+Note that blank lines inside the beginning
address@hidden@@example} and the ending @code{@@end example} will appear in
+the address@hidden
+
address@hidden
address@hidden:} Do not use tabs in the lines of an example or anywhere
+else in Texinfo (except in verbatim environments)! The @TeX{}
+implementation of Texinfo treats tabs as single spaces, and that is not
+what they look like. (If necessary, in Emacs, you can use @kbd{M-x
+untabify} to convert tabs in a region to multiple spaces.)@refill
address@hidden quotation
+
+Examples are often, logically speaking, ``in the middle'' of a
+paragraph, and the text that continues after an example should not be
+indented. The @code{@@noindent} command prevents a piece of text from
+being indented as if it were a new paragraph.
+(@xref{noindent}.)
+
+(The @code{@@code} command is used for examples of code that are
+embedded within sentences, not set off from preceding and following
+text. @xref{code, , @code{@@code}}.)
+
+
address@hidden verbatim
address@hidden @code{@@verbatim}: Literal Text
address@hidden verbatim
address@hidden Verbatim environment
+
+Use the @code{@@verbatim} environment for printing of text that may
+contain special characters or commands that should not be interpreted,
+such as computer input or output (@code{@@example} interprets its text
+as regular Texinfo commands). This is especially useful for including
+automatically generated output in a Texinfo manual. Here is an example;
+the output you see is just the same as the input, with a line
address@hidden@@verbatim} before and a line @code{@@end verbatim} after.
+
address@hidden
+This is an example of text written in a @verbatim
+block. No character substitutions are made. All commands
+are ignored, until `<at>end verbatim'.
+
+In the printed manual, the text is typeset in a
+fixed-width font, and not indented or filled. All
+spaces and blank lines are significant, including tabs.
address@hidden verbatim
+
+Write a @code{@@verbatim} command at the beginning of a line by itself.
+This line will disappear from the output. Mark the end of the verbatim
+block with a @code{@@end verbatim} command, also written at the
+beginning of a line by itself. The @code{@@end verbatim} will also
+disappear from the output.
+
+For example:
address@hidden oops, got to trick this a bit: can't use @end verbatim inside
@verbatim
+
address@hidden
address@hidden @@verbatim
address@hidden @{
address@hidden <tab>@@command with strange characters: @@'e
address@hidden expand<tab>me
address@hidden @}
address@hidden @@end verbatim
address@hidden example
+
address@hidden
+produces
+
address@hidden
+{
+ @command with strange characters: @'e
+expand me
+}
address@hidden verbatim
+
+Since the lines containing @code{@@verbatim} and @code{@@end verbatim}
+produce no output, tyically you should put a blank line before the
address@hidden@@verbatim} and another blank line after the @code{@@end
+verbatim}. Blank lines between the beginning @code{@@verbatim} and the
+ending @code{@@end verbatim} will appear in the output.
+
+
address@hidden verbatiminclude
address@hidden @code{@@verbatiminclude} @var{file}: Include a File Verbatim
address@hidden Verbatim, include file
address@hidden Including a file verbatim
address@hidden verbatiminclude
+
+You can include the exact contents of a file in the document with the
address@hidden@@verbatiminclude} command:
+
address@hidden
+@@verbatiminclude @var{filename}
address@hidden example
+
+The contents of @var{filename} is printed in a verbatim environment
+(@pxref{verbatim,,@code{@@verbatim}}). Generally, the file is printed
+exactly as it is, with all special characters and white space retained.
+
+
address@hidden lisp
address@hidden @code{@@lisp}: Marking a Lisp Example
address@hidden lisp
address@hidden Lisp example
+
+The @code{@@lisp} command is used for Lisp code. It is synonymous
+with the @code{@@example} command.
+
address@hidden
+This is an example of text written between an
address@hidden@@lisp} command and an @code{@@end lisp} command.
address@hidden lisp
+
+Use @code{@@lisp} instead of @code{@@example} to preserve information
+regarding the nature of the example. This is useful, for example, if
+you write a function that evaluates only and all the Lisp code in a
+Texinfo file. Then you can use the Texinfo file as a Lisp
address@hidden would be straightforward to extend Texinfo to work
+in a similar fashion for C, Fortran, or other languages.}
+
+Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by
address@hidden
+
+
address@hidden small
address@hidden @code{@@address@hidden Block Commands
address@hidden Small examples
address@hidden Examples in smaller fonts
address@hidden Lisp examples in smaller fonts
address@hidden smalldisplay
address@hidden smallexample
address@hidden smallformat
address@hidden smalllisp
+
+In addition to the regular @code{@@example} and @code{@@lisp} commands,
+Texinfo has ``small'' example-style commands. These are
address@hidden@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, and
address@hidden@@smalllisp}.
+
+In @TeX{}, the @code{@@address@hidden commands typeset text in a smaller
+font than the non-small example commands. Consequently, many examples
+containing long lines fit on a page without needing to be shortened.
+
+In Info, the @code{@@address@hidden commands are equivalent to their
+non-small companion commands.
+
+Mark the end of an @code{@@address@hidden block with a corresponding
address@hidden@@end address@hidden For example, pair @code{@@smallexample} with
address@hidden@@end smallexample}.
+
address@hidden
+This is an example of text written between @code{@@smallexample} and
address@hidden@@end smallexample}. In Info this text appears in its normal
size;
+but in a 7 by 9.25 inch manual, this text appears in a smaller font.
address@hidden smallexample
+
+The @code{@@address@hidden commands make it easier to prepare manuals
+without forcing you to edit examples by hand to fit them onto narrower
+pages.
+
+As a general rule, a printed document looks better if you use only one
+of (for example) @code{@@example} or in @code{@@smallexample}
+consistently within a chapter. Only occasionally should you mix the two
+formats.
+
address@hidden, , Printing ``Small'' Books}, for more information
+about the @code{@@smallbook} command.
+
+
address@hidden display
address@hidden @code{@@display} and @code{@@smalldisplay}
address@hidden Display formatting
address@hidden display
+
+The @code{@@display} command begins a kind of example. It is like the
address@hidden@@example} command
+except that, in
+a printed manual, @code{@@display} does not select the fixed-width
+font. In fact, it does not specify the font at all, so that the text
+appears in the same font it would have appeared in without the
address@hidden@@display} address@hidden
+
address@hidden
+This is an example of text written between an @code{@@display} command
+and an @code{@@end display} command. The @code{@@display} command
+indents the text, but does not fill it.
address@hidden display
+
address@hidden smalldisplay
+Texinfo also provides a command @code{@@smalldisplay}, which is like
address@hidden@@display} but uses a smaller font in @code{@@smallbook} format.
address@hidden
+
+
address@hidden format
address@hidden @code{@@format} and @code{@@smallformat}
address@hidden format
+
+The @code{@@format} command is similar to @code{@@example} except
+that, in the printed manual, @code{@@format} does not select the
+fixed-width font and does not narrow the address@hidden
+
address@hidden
+This is an example of text written between an @code{@@format} command
+and an @code{@@end format} command. As you can see
+from this example,
+the @code{@@format} command does not fill the text.
address@hidden format
+
address@hidden smallformat
+Texinfo also provides a command @code{@@smallformat}, which is like
address@hidden@@format} but uses a smaller font in @code{@@smallbook} format.
address@hidden
+
+
+
address@hidden exdent
address@hidden @code{@@exdent}: Undoing a Line's Indentation
address@hidden Indentation undoing
address@hidden exdent
+
+The @code{@@exdent} command removes any indentation a line might have.
+The command is written at the beginning of a line and applies only to
+the text that follows the command that is on the same line. Do not use
+braces around the text. In a printed manual, the text on an
address@hidden@@exdent} line is printed in the roman address@hidden
+
address@hidden@@exdent} is usually used within examples. Thus,@refill
+
address@hidden
address@hidden
+@@example
+This line follows an @@@@example command.
+@@exdent This line is exdented.
+This line follows the exdented line.
+The @@@@end example comes on the next line.
+@@end group
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+This line follows an @@example command.
address@hidden This line is exdented.
+This line follows the exdented line.
+The @@end example comes on the next line.
address@hidden group
address@hidden example
+
+In practice, the @code{@@exdent} command is rarely used.
+Usually, you un-indent text by ending the example and
+returning the page to its normal address@hidden
+
+
address@hidden flushleft & flushright
address@hidden @code{@@flushleft} and @code{@@flushright}
address@hidden flushleft
address@hidden flushright
address@hidden ragged right
address@hidden ragged left
+
+The @code{@@flushleft} and @code{@@flushright} commands line up the
+ends of lines on the left and right margins of a page,
+but do not fill the text. The commands are written on lines of their
+own, without braces. The @code{@@flushleft} and @code{@@flushright}
+commands are ended by @code{@@end flushleft} and @code{@@end
+flushright} commands on lines of their address@hidden
+
address@hidden 1500
+For example,
+
address@hidden
address@hidden
+@@flushleft
+This text is
+written flushleft.
+@@end flushleft
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+This text is
+written flushleft.
address@hidden flushleft
address@hidden quotation
+
+
address@hidden@@flushright} produces the type of indentation often used in the
+return address of letters. For example,
+
address@hidden
address@hidden
+@@flushright
+Here is an example of text written
+flushright. The @@address@hidden@@address@hidden command
+right justifies every line but leaves the
+left end ragged.
+@@end flushright
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
+Here is an example of text written
+flushright. The @code{@@flushright} command
+right justifies every line but leaves the
+left end ragged.
address@hidden flushright
+
+
address@hidden noindent
address@hidden @code{@@noindent}: Omitting Indentation
address@hidden noindent
+
+An example or other inclusion can break a paragraph into segments.
+Ordinarily, the formatters indent text that follows an example as a new
+paragraph. However, you can prevent this by writing @code{@@noindent}
+at the beginning of a line by itself preceding the continuation
address@hidden
+
address@hidden 1500
+For example:
+
address@hidden
address@hidden
+@@example
+This is an example
+@@end example
+
+@@noindent
+This line is not indented. As you can see, the
+beginning of the line is fully flush left with the line
+that follows after it. (This whole example is between
+@@address@hidden@@@@address@hidden and @@address@hidden@@@@end address@hidden)
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+This is an example
address@hidden example
address@hidden
+% Remove extra vskip; this is a kludge to counter the effect of display
+\vskip-3.5\baselineskip
address@hidden tex
+
address@hidden
+This line is not indented. As you can see, the
+beginning of the line is fully flush left with the line
+that follows after it. (This whole example is between
address@hidden@@display} and @code{@@end display}.)
address@hidden display
+
+To adjust the number of blank lines properly in the Info file output,
+remember that the line containing @code{@@noindent} does not generate a
+blank line, and neither does the @code{@@end example} address@hidden
+
+In the Texinfo source file for this manual, each line that says
+`produces' is preceded by a line containing @code{@@address@hidden
+
+Do not put braces after an @code{@@noindent} command; they are not
+necessary, since @code{@@noindent} is a command used outside of
+paragraphs (@pxref{Command Syntax})address@hidden
+
+
address@hidden cartouche
address@hidden @code{@@cartouche}: Rounded Rectangles Around Examples
address@hidden cartouche
address@hidden Box with rounded corners
address@hidden Rounded rectangles, around examples
+
+In a printed manual, the @code{@@cartouche} command draws a box with
+rounded corners around its contents. You can use this command to
+further highlight an example or quotation. For instance, you could
+write a manual in which one type of example is surrounded by a cartouche
+for emphasis.
+
address@hidden@@cartouche} affects only the printed manual; it has no effect in
+other output files.
+
address@hidden 1500
+For example,
+
address@hidden
address@hidden
+@@example
+@@cartouche
+% pwd
+/usr/local/share/emacs
+@@end cartouche
+@@end example
address@hidden group
address@hidden example
+
address@hidden
+surrounds the two-line example with a box with rounded corners, in the
+printed manual.
+
+
+
address@hidden Lists and Tables
address@hidden Lists and Tables
address@hidden Making lists and tables
address@hidden Lists and tables, making
address@hidden Tables and lists, making
+
+Texinfo has several ways of making lists and tables. Lists can be
+bulleted or numbered; two-column tables can highlight the items in
+the first column; multi-column tables are also supported.
+
address@hidden
+* Introducing Lists:: Texinfo formats lists for you.
+* itemize:: How to construct a simple list.
+* 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.
address@hidden menu
+
address@hidden Introducing Lists, itemize, Lists and Tables, Lists and Tables
address@hidden Introducing Lists
+
+Texinfo automatically indents the text in lists or tables, and numbers
+an enumerated list. This last feature is useful if you modify the
+list, since you do not need to renumber it address@hidden
+
+Numbered lists and tables begin with the appropriate @@-command at the
+beginning of a line, and end with the corresponding @code{@@end}
+command on a line by itself. The table and itemized-list commands
+also require that you write formatting information on the same line as
+the beginning @@address@hidden
+
+Begin an enumerated list, for example, with an @code{@@enumerate}
+command and end the list with an @code{@@end enumerate} command.
+Begin an itemized list with an @code{@@itemize} command, followed on
+the same line by a formatting command such as @code{@@bullet}, and end
+the list with an @code{@@end itemize} address@hidden
address@hidden end
+
+Precede each element of a list with an @code{@@item} or @code{@@itemx}
address@hidden
+
address@hidden 1
address@hidden
+Here is an itemized list of the different kinds of table and lists:@refill
+
address@hidden @bullet
address@hidden
+Itemized lists with and without bullets.
+
address@hidden
+Enumerated lists, using numbers or letters.
+
address@hidden
+Two-column tables with highlighting.
address@hidden itemize
+
address@hidden 1
address@hidden
+Here is an enumerated list with the same items:@refill
+
address@hidden
address@hidden
+Itemized lists with and without bullets.
+
address@hidden
+Enumerated lists, using numbers or letters.
+
address@hidden
+Two-column tables with highlighting.
address@hidden enumerate
+
address@hidden 1
address@hidden
+And here is a two-column table with the same items and their
address@hidden@@-commands}:@refill
+
address@hidden @code
address@hidden @@itemize
+Itemized lists with and without bullets.
+
address@hidden @@enumerate
+Enumerated lists, using numbers or letters.
+
address@hidden @@table
address@hidden @@ftable
address@hidden @@vtable
+Two-column tables, optionally with indexing.
address@hidden table
+
+
address@hidden itemize
address@hidden @code{@@itemize}: Making an Itemized List
address@hidden Itemization
address@hidden itemize
+
+The @code{@@itemize} command produces sequences of indented
+paragraphs, with a bullet or other mark inside the left margin
+at the beginning of each paragraph for which such a mark is address@hidden
+
address@hidden @code{@@w}, for blank items
+Begin an itemized list by writing @code{@@itemize} at the beginning of
+a line. Follow the command, on the same line, with a character or a
+Texinfo command that generates a mark. Usually, you will write
address@hidden@@bullet} after @code{@@itemize}, but you can use
address@hidden@@minus}, or any command or character that results in a single
+character in the Info file. If you don't want any mark at all, use
address@hidden@@w}. (When you write the mark command such as
address@hidden@@bullet} after an @code{@@itemize} command, you may omit the
address@hidden@address@hidden) If you don't specify a mark command, the
default is
address@hidden@@bullet}.
+
+Write the text of the indented paragraphs themselves after the
address@hidden@@itemize}, up to another line that says @code{@@end
address@hidden
+
address@hidden item
+Before each paragraph for which a mark in the margin is desired, write a
+line that says just @code{@@item}. It is ok to have text following the
address@hidden@@item}.
+
+Usually, you should put a blank line before an @code{@@item}. This
+puts a blank line in the Info file. (@TeX{} inserts the proper
+interline whitespace in either case.) Except when the entries are
+very brief, these blank lines make the list look address@hidden
+
+Here is an example of the use of @code{@@itemize}, followed by the
+output it produces. @code{@@bullet} produces an @samp{*} in Info and a
+round dot in @TeX{}.
+
address@hidden
address@hidden
+@@itemize @@bullet
+@@item
+Some text for foo.
+
+@@item
+Some text
+for bar.
+@@end itemize
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
address@hidden @bullet
address@hidden
+Some text for foo.
+
address@hidden
+Some text
+for bar.
address@hidden itemize
address@hidden quotation
+
+Itemized lists may be embedded within other itemized lists. Here is a
+list marked with dashes embedded in a list marked with bullets:@refill
+
address@hidden
address@hidden
+@@itemize @@bullet
+@@item
+First item.
+
+@@itemize @@minus
+@@item
+Inner item.
+
+@@item
+Second inner item.
+@@end itemize
+
+@@item
+Second outer item.
+@@end itemize
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
address@hidden @bullet
address@hidden
+First item.
+
address@hidden @minus
address@hidden
+Inner item.
+
address@hidden
+Second inner item.
address@hidden itemize
+
address@hidden
+Second outer item.
address@hidden itemize
address@hidden quotation
+
+
address@hidden enumerate
address@hidden @code{@@enumerate}: Making a Numbered or Lettered List
address@hidden Enumeration
address@hidden enumerate
+
address@hidden@@enumerate} is like @code{@@itemize} (@pxref{itemize,,
address@hidden@@itemize}}), except that the labels on the items are
+successive integers or letters instead of bullets.
+
+Write the @code{@@enumerate} command at the beginning of a line. The
+command does not require an argument, but accepts either a number or a
+letter as an option. Without an argument, @code{@@enumerate} starts the
+list with the number @samp{1}. With a numeric argument, such as
address@hidden, the command starts the list with that number. With an upper
+or lower case letter, such as @samp{a} or @samp{A}, the command starts
+the list with that letter.
+
+Write the text of the enumerated list in the same way you write an
+itemized list: put @code{@@item} on a line of its own before the start
+of each paragraph that you want enumerated. Do not write any other text
+on the line beginning with @code{@@item}.
+
+You should put a blank line between entries in the list.
+This generally makes it easier to read the Info file.
+
address@hidden 1500
+Here is an example of @code{@@enumerate} without an argument:
+
address@hidden
address@hidden
+@@enumerate
+@@item
+Underlying causes.
+
+@@item
+Proximate causes.
+@@end enumerate
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
address@hidden
+Underlying causes.
+
address@hidden
+Proximate causes.
address@hidden enumerate
address@hidden 1
+Here is an example with an argument of @kbd{3}:@refill
address@hidden 1
address@hidden
address@hidden
+@@enumerate 3
+@@item
+Predisposing causes.
+
+@@item
+Precipitating causes.
+
+@@item
+Perpetuating causes.
+@@end enumerate
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden 3
address@hidden
+Predisposing causes.
+
address@hidden
+Precipitating causes.
+
address@hidden
+Perpetuating causes.
address@hidden enumerate
address@hidden 1
+Here is a brief summary of the alternatives. The summary is constructed
+using @code{@@enumerate} with an argument of @address@hidden
address@hidden 1
address@hidden a
address@hidden
address@hidden@@enumerate}
+
+Without an argument, produce a numbered list, starting with the number
address@hidden
+
address@hidden
address@hidden@@enumerate @var{positive-integer}}
+
+With a (positive) numeric argument, start a numbered list with that
+number. You can use this to continue a list that you interrupted with
+other address@hidden
+
address@hidden
address@hidden@@enumerate @var{upper-case-letter}}
+
+With an upper case letter as argument, start a list
+in which each item is marked
+by a letter, beginning with that upper case address@hidden
+
address@hidden
address@hidden@@enumerate @var{lower-case-letter}}
+
+With a lower case letter as argument, start a list
+in which each item is marked by
+a letter, beginning with that lower case address@hidden
address@hidden enumerate
+
+You can also nest enumerated lists, as in an address@hidden
+
address@hidden Two-column Tables, Multi-column Tables, enumerate, Lists and
Tables
address@hidden Making a Two-column Table
address@hidden Tables, making two-column
address@hidden table
+
address@hidden@@table} is similar to @code{@@itemize} (@pxref{itemize,,
address@hidden@@itemize}}), but allows you to specify a name or heading line for
+each item. The @code{@@table} command is used to produce two-column
+tables, and is especially useful for glossaries, explanatory
+exhibits, and command-line option summaries.
+
address@hidden
+* table:: How to construct a two-column table.
+* ftable vtable:: Automatic indexing for two-column tables.
+* itemx:: How to put more entries in the first column.
address@hidden menu
+
address@hidden table, ftable vtable, Two-column Tables, Two-column Tables
address@hidden Using the @code{@@table} Command
+
+Use the @code{@@table} command to produce two-column address@hidden
+
+Write the @code{@@table} command at the beginning of a line and follow
+it on the same line with an argument that is a Texinfo ``indicating''
+command such as @code{@@code}, @code{@@samp}, @code{@@var}, or
address@hidden@@kbd} (@pxref{Indicating}). Although these commands are usually
+followed by arguments in braces, in this case you use the command name
+without an argument because @code{@@item} will supply the argument.
+This command will be applied to the text that goes into the first column
+of each item and determines how it will be highlighted. For example,
address@hidden@@code} will cause the text in the first column to be highlighted
+with an @code{@@code} command. (We recommend @code{@@code} for
address@hidden@@table}'s of command-line options.)
+
address@hidden asis
+You may also choose to use the @code{@@asis} command as an argument to
address@hidden@@table}. @code{@@asis} is a command that does nothing; if you
+use this command after @code{@@table}, @TeX{} and the Info formatting
+commands output the first column entries without added highlighting
+(``as is'')address@hidden
+
+(The @code{@@table} command may work with other commands besides those
+listed here. However, you can only use commands that normally take
+arguments in braces.)@refill
+
address@hidden item
+Begin each table entry with an @code{@@item} command at the beginning
+of a line. Write the first column text on the same line as the
address@hidden@@item} command. Write the second column text on the line
+following the @code{@@item} line and on subsequent lines. (You do not
+need to type anything for an empty second column entry.) You may
+write as many lines of supporting text as you wish, even several
+paragraphs. But only text on the same line as the @code{@@item} will
+be placed in the first column, including any footnote.
+
+Normally, you should put a blank line before an @code{@@item} line.
+This puts a blank like in the Info file. Except when the entries are
+very brief, a blank line looks address@hidden
+
address@hidden 1500
+The following table, for example, highlights the text in the first
+column with an @code{@@samp} command:@refill
+
address@hidden
address@hidden
+@@table @@samp
+@@item foo
+This is the text for
+@@address@hidden@}.
+
+@@item bar
+Text for @@address@hidden@}.
+@@end table
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden @samp
address@hidden foo
+This is the text for
address@hidden
address@hidden bar
+Text for @samp{bar}.
address@hidden table
+
+If you want to list two or more named items with a single block of
+text, use the @code{@@itemx} command. (@xref{itemx, ,
address@hidden@@itemx}}.)@refill
+
+
address@hidden ftable vtable
address@hidden @code{@@ftable} and @code{@@vtable}
address@hidden Tables with indexes
address@hidden Indexing table entries automatically
address@hidden ftable
address@hidden vtable
+
+The @code{@@ftable} and @code{@@vtable} commands are the same as the
address@hidden@@table} command except that @code{@@ftable} automatically enters
+each of the items in the first column of the table into the index of
+functions and @code{@@vtable} automatically enters each of the items in
+the first column of the table into the index of variables. This
+simplifies the task of creating indices. Only the items on the same
+line as the @code{@@item} commands are indexed, and they are indexed in
+exactly the form that they appear on that line. @xref{Indices},
+for more information about address@hidden
+
+Begin a two-column table using @code{@@ftable} or @code{@@vtable} by
+writing the @@-command at the beginning of a line, followed on the same
+line by an argument that is a Texinfo command such as @code{@@code},
+exactly as you would for an @code{@@table} command; and end the table
+with an @code{@@end ftable} or @code{@@end vtable} command on a line by
+itself.
+
+See the example for @code{@@table} in the previous section.
+
address@hidden itemx
address@hidden @code{@@itemx}
address@hidden Two named items for @code{@@table}
address@hidden itemx
+
+Use the @code{@@itemx} command inside a table when you have two or more
+first column entries for the same item, each of which should appear on a
+line of its own. Use @code{@@itemx} for all but the first entry;
address@hidden@@itemx} should always follow an @code{@@item} command. The
address@hidden@@itemx} command works exactly like @code{@@item} except that it
+does not generate extra vertical space above the first column text.
+
+For example,
+
address@hidden
address@hidden
+@@table @@code
+@@item upcase
+@@itemx downcase
+These two functions accept a character or a string as
+argument, and return the corresponding upper case (lower
+case) character or string.
+@@end table
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden @code
address@hidden upcase
address@hidden downcase
+These two functions accept a character or a string as
+argument, and return the corresponding upper case (lower
+case) character or address@hidden
address@hidden table
+
address@hidden
+(Note also that this example illustrates multi-line supporting text in
+a two-column table.)@refill
+
+
address@hidden Multi-column Tables, , Two-column Tables, Lists and Tables
address@hidden Multi-column Tables
address@hidden Tables, making multi-column
address@hidden multitable
+
address@hidden@@multitable} allows you to construct tables with any number of
+columns, with each column having any width you like.
+
+You define the column widths on the @code{@@multitable} line itself, and
+write each row of the actual table following an @code{@@item} command,
+with columns separated by an @code{@@tab} command. Finally, @code{@@end
+multitable} completes the table. Details in the sections below.
+
address@hidden
+* Multitable Column Widths:: Defining multitable column widths.
+* Multitable Rows:: Defining multitable rows, with examples.
address@hidden menu
+
address@hidden Multitable Column Widths
address@hidden Multitable Column Widths
address@hidden Multitable column widths
address@hidden Column widths, defining for multitables
address@hidden Widths, defining multitable column
+
+You can define the column widths for a multitable in two ways: as
+fractions of the line length; or with a prototype row. Mixing the two
+methods is not supported. In either case, the widths are defined
+entirely on the same line as the @code{@@multitable} command.
+
address@hidden
address@hidden
address@hidden columnfractions
address@hidden Line length, column widths as fraction of
+To specify column widths as fractions of the line length, write
address@hidden@@columnfractions} and the decimal numbers (presumably less than
+1) after the @code{@@multitable} command, as in:
+
address@hidden
+@@multitable @@columnfractions .33 .33 .33
address@hidden example
+
address@hidden The fractions need not add up exactly to 1.0, as these do
+not. This allows you to produce tables that do not need the full line
+length. You can use a leading zero if you wish.
+
address@hidden
address@hidden Prototype row, column widths defined by
+To specify a prototype row, write the longest entry for each column
+enclosed in braces after the @code{@@multitable} command. For example:
+
address@hidden
+@@multitable @{some text for column address@hidden @{for column address@hidden
address@hidden example
+
address@hidden
+The first column will then have the width of the typeset `some text for
+column one', and the second column the width of `for column two'.
+
+The prototype entries need not appear in the table itself.
+
+Although we used simple text in this example, the prototype entries can
+contain Texinfo commands; markup commands such as @code{@@code} are
+particularly likely to be useful.
+
address@hidden enumerate
+
+
address@hidden Multitable Rows, , Multitable Column Widths, Multi-column Tables
address@hidden Multitable Rows
address@hidden Multitable rows
address@hidden Rows, of a multitable
+
address@hidden item
address@hidden tab
+After the @code{@@multitable} command defining the column widths (see
+the previous section), you begin each row in the body of a multitable
+with @code{@@item}, and separate the column entries with @code{@@tab}.
+Line breaks are not special within the table body, and you may break
+input lines in your source file as necessary.
+
+Here is a complete example of a multi-column table (the text is from
address@hidden GNU Emacs Manual}, @pxref{Split Window,, Splitting Windows,
+emacs, The GNU Emacs Manual}):
+
address@hidden
+@@multitable @@columnfractions .15 .45 .4
+@@item Key @@tab Command @@tab Description
+@@item C-x 2
+@@tab @@address@hidden@}
+@@tab Split the selected window into two windows,
+with one above the other.
+@@item C-x 3
+@@tab @@address@hidden@}
+@@tab Split the selected window into two windows
+positioned side by side.
+@@item C-Mouse-2
+@@tab
+@@tab In the mode line or scroll bar of a window,
+split that window.
+@@end multitable
address@hidden example
+
address@hidden produces:
+
address@hidden @columnfractions .15 .45 .4
address@hidden Key @tab Command @tab Description
address@hidden C-x 2
address@hidden @code{split-window-vertically}
address@hidden Split the selected window into two windows,
+with one above the other.
address@hidden C-x 3
address@hidden @code{split-window-horizontally}
address@hidden Split the selected window into two windows
+positioned side by side.
address@hidden C-Mouse-2
address@hidden
address@hidden In the mode line or scroll bar of a window,
+split that window.
address@hidden multitable
+
+
address@hidden Indices, Insertions, Lists and Tables, Top
address@hidden node-name, next, previous, up
address@hidden Indices
address@hidden Indices
+
+Using Texinfo, you can generate indices without having to sort and
+collate entries manually. In an index, the entries are listed in
+alphabetical order, together with information on how to find the
+discussion of each entry. In a printed manual, this information
+consists of page numbers. In an Info file, this information is a menu
+entry leading to the first node address@hidden
+
+Texinfo provides several predefined kinds of index: an index
+for functions, an index for variables, an index for concepts, and so
+on. You can combine indices or use them for other than their
+canonical purpose. If you wish, you can define your own address@hidden
+
address@hidden
+* Index Entries:: Choose different words for index entries.
+* Predefined Indices:: Use different indices for different kinds
+ of entry.
+* Indexing Commands:: How to make an index entry.
+* Combining Indices:: How to combine indices.
+* New Indices:: How to define your own indices.
address@hidden menu
+
address@hidden Index Entries, Predefined Indices, Indices, Indices
address@hidden node-name, next, previous, up
address@hidden Making Index Entries
address@hidden Index entries, making
address@hidden Entries, making index
+
+When you are making index entries, it is good practice to think of the
+different ways people may look for something. Different people
address@hidden not} think of the same words when they look something up. A
+helpful index will have items indexed under all the different words
+that people may use. For example, one reader may think it obvious that
+the two-letter names for indices should be listed under ``Indices,
+two-letter names'', since the word ``Index'' is the general concept.
+But another reader may remember the specific concept of two-letter
+names and search for the entry listed as ``Two letter names for
+indices''. A good index will have both entries and will help both
address@hidden
+
+Like typesetting, the construction of an index is a highly skilled,
+professional art, the subtleties of which are not appreciated until you
+need to do it address@hidden
+
address@hidden Indices & Menus}, for information about printing an index
+at the end of a book or creating an index menu in an Info address@hidden
+
address@hidden Predefined Indices, Indexing Commands, Index Entries, Indices
address@hidden node-name, next, previous, up
address@hidden Predefined Indices
+
+Texinfo provides six predefined indices:@refill
+
address@hidden @bullet
address@hidden
+A @dfn{concept index} listing concepts that are address@hidden
+
address@hidden
+A @dfn{function index} listing functions (such as entry points of
+libraries)address@hidden
+
address@hidden
+A @dfn{variables index} listing variables (such as global variables
+of libraries)address@hidden
+
address@hidden
+A @dfn{keystroke index} listing keyboard address@hidden
+
address@hidden
+A @dfn{program index} listing names of address@hidden
+
address@hidden
+A @dfn{data type index} listing data types (such as structures defined in
+header files)address@hidden
address@hidden itemize
+
address@hidden
+Not every manual needs all of these, and most manuals use two or three
+of them. This manual has two indices: a
+concept index and an @@-command index (that is actually the function
+index but is called a command index in the chapter heading). Two or
+more indices can be combined into one using the @code{@@synindex} or
address@hidden@@syncodeindex} commands. @xref{Combining address@hidden
+
address@hidden Indexing Commands, Combining Indices, Predefined Indices, Indices
address@hidden node-name, next, previous, up
address@hidden Defining the Entries of an Index
address@hidden Defining indexing entries
address@hidden Index entries
address@hidden Entries for an index
address@hidden Specifying index entries
address@hidden Creating index entries
+
+The data to make an index come from many individual indexing commands
+scattered throughout the Texinfo source file. Each command says to add
+one entry to a particular index; after formatting, the index will give
+the current page number or node name as the address@hidden
+
+An index entry consists of an indexing command at the beginning of a
+line followed, on the rest of the line, by the address@hidden
+
+For example, this section begins with the following five entries for
+the concept index:@refill
+
address@hidden
+@@cindex Defining indexing entries
+@@cindex Index entries
+@@cindex Entries for an index
+@@cindex Specifying index entries
+@@cindex Creating index entries
address@hidden example
+
+Each predefined index has its own indexing address@hidden@@cindex}
+for the concept index, @code{@@findex} for the function index, and so
address@hidden
+
address@hidden Writing index entries
address@hidden Index entry writing
+Concept index entries consist of text. The best way to write an index
+is to choose entries that are terse yet clear. If you can do this,
+the index often looks better if the entries are not capitalized, but
+written just as they would appear in the middle of a sentence.
+(Capitalize proper names and acronyms that always call for upper case
+letters.) This is the case convention we use in most GNU manuals'
+indices.
+
+If you don't see how to make an entry terse yet clear, make it longer
+and clear---not terse and confusing. If many of the entries are several
+words long, the index may look better if you use a different convention:
+to capitalize the first word of each entry. But do not capitalize a
+case-sensitive name such as a C or Lisp function name or a shell
+command; that would be a spelling error.
+
+Whichever case convention you use, please use it consistently!
+
+Entries in indices other than the concept index are symbol names in
+programming languages, or program names; these names are usually
+case-sensitive, so use upper and lower case as required for them.
+
+By default, entries for a concept index are printed in a small roman
+font and entries for the other indices are printed in a small
address@hidden@@code} font. You may change the way part of an entry is
+printed with the usual Texinfo commands, such as @code{@@file} for
+file names and @code{@@emph} for emphasis (@pxref{Marking
+Text})address@hidden
address@hidden Index font types
+
address@hidden Predefined indexing commands
address@hidden Indexing commands, predefined
+The six indexing commands for predefined indices are:
+
address@hidden @code
address@hidden @@cindex @var{concept}
address@hidden cindex
+Make an entry in the concept index for @address@hidden
+
address@hidden @@findex @var{function}
address@hidden findex
+Make an entry in the function index for @address@hidden
+
address@hidden @@vindex @var{variable}
address@hidden vindex
+Make an entry in the variable index for @address@hidden
+
address@hidden @@kindex @var{keystroke}
address@hidden kindex
+Make an entry in the key index for @address@hidden
+
address@hidden @@pindex @var{program}
address@hidden pindex
+Make an entry in the program index for @address@hidden
+
address@hidden @@tindex @var{data type}
address@hidden tindex
+Make an entry in the data type index for @var{data address@hidden
address@hidden table
+
address@hidden
address@hidden:} Do not use a colon in an index entry. In Info, a
+colon separates the menu entry name from the node name, so a colon in
+the entry itself confuses Info. @xref{Menu Parts, , The Parts of a
+Menu}, for more information about the structure of a menu entry.
address@hidden quotation
+
+You are not actually required to use the predefined indices for their
+canonical purposes. For example, suppose you wish to index some C
+preprocessor macros. You could put them in the function index along
+with actual functions, just by writing @code{@@findex} commands for
+them; then, when you print the ``Function Index'' as an unnumbered
+chapter, you could give it the title `Function and Macro Index' and
+all will be consistent for the reader. Or you could put the macros in
+with the data types by writing @code{@@tindex} commands for them, and
+give that index a suitable title so the reader will understand.
+(@xref{Printing Indices & Menus}.)@refill
+
address@hidden Combining Indices, New Indices, Indexing Commands, Indices
address@hidden node-name, next, previous, up
address@hidden Combining Indices
address@hidden Combining indices
address@hidden Indices, combining them
+
+Sometimes you will want to combine two disparate indices such as functions
+and concepts, perhaps because you have few enough of one of them that
+a separate index for them would look address@hidden
+
+You could put functions into the concept index by writing
address@hidden@@cindex} commands for them instead of @code{@@findex} commands,
+and produce a consistent manual by printing the concept index with the
+title `Function and Concept Index' and not printing the `Function
+Index' at all; but this is not a robust procedure. It works only if
+your document is never included as part of another
+document that is designed to have a separate function index; if your
+document were to be included with such a document, the functions from
+your document and those from the other would not end up together.
+Also, to make your function names appear in the right font in the
+concept index, you would need to enclose every one of them between
+the braces of @code{@@address@hidden
+
address@hidden
+* syncodeindex:: How to merge two indices, using @code{@@code}
+ font for the merged-from index.
+* synindex:: How to merge two indices, using the
+ default font of the merged-to index.
address@hidden menu
+
address@hidden syncodeindex
address@hidden @code{@@syncodeindex}
address@hidden syncodeindex
+
+When you want to combine functions and concepts into one index, you
+should index the functions with @code{@@findex} and index the concepts
+with @code{@@cindex}, and use the @code{@@syncodeindex} command to
+redirect the function index entries into the concept address@hidden
address@hidden syncodeindex
+
+The @code{@@syncodeindex} command takes two arguments; they are the name
+of the index to redirect, and the name of the index to redirect it to.
+The template looks like this:@refill
+
address@hidden
+@@syncodeindex @var{from} @var{to}
address@hidden example
+
address@hidden Predefined names for indices
address@hidden Two letter names for indices
address@hidden Indices, two letter names
address@hidden Names for indices
+For this purpose, the indices are given two-letter names:@refill
+
address@hidden @samp
address@hidden cp
+concept index
address@hidden fn
+function index
address@hidden vr
+variable index
address@hidden ky
+key index
address@hidden pg
+program index
address@hidden tp
+data type index
address@hidden table
+
+Write an @code{@@syncodeindex} command before or shortly after the
+end-of-header line at the beginning of a Texinfo file. For example,
+to merge a function index with a concept index, write the
+following:@refill
+
address@hidden
+@@syncodeindex fn cp
address@hidden example
+
address@hidden
+This will cause all entries designated for the function index to merge
+in with the concept index address@hidden
+
+To merge both a variables index and a function index into a concept
+index, write the following:@refill
+
address@hidden
address@hidden
+@@syncodeindex vr cp
+@@syncodeindex fn cp
address@hidden group
address@hidden example
+
address@hidden Fonts for indices
+The @code{@@syncodeindex} command puts all the entries from the `from'
+index (the redirected index) into the @code{@@code} font, overriding
+whatever default font is used by the index to which the entries are
+now directed. This way, if you direct function names from a function
+index into a concept index, all the function names are printed in the
address@hidden@@code} font as you would address@hidden
+
address@hidden synindex, , syncodeindex, Combining Indices
address@hidden @code{@@synindex}
address@hidden synindex
+
+The @code{@@synindex} command is nearly the same as the
address@hidden@@syncodeindex} command, except that it does not put the
+`from' index entries into the @code{@@code} font; rather it puts
+them in the roman font. Thus, you use @code{@@synindex} when you
+merge a concept index into a function address@hidden
+
address@hidden Indices & Menus}, for information about printing an index
+at the end of a book or creating an index menu in an Info address@hidden
+
address@hidden New Indices, , Combining Indices, Indices
address@hidden Defining New Indices
address@hidden Defining new indices
address@hidden Indices, defining new
address@hidden New index defining
address@hidden defindex
address@hidden defcodeindex
+
+In addition to the predefined indices, you may use the
address@hidden@@defindex} and @code{@@defcodeindex} commands to define new
+indices. These commands create new indexing @@-commands with which
+you mark index entries. The @code{@@defindex }command is used like
+this:@refill
+
address@hidden
+@@defindex @var{name}
address@hidden example
+
+The name of an index should be a two letter word, such as @samp{au}.
+For example:@refill
+
address@hidden
+@@defindex au
address@hidden example
+
+This defines a new index, called the @samp{au} index. At the same
+time, it creates a new indexing command, @code{@@auindex}, that you
+can use to make index entries. Use the new indexing command just as
+you would use a predefined indexing address@hidden
+
+For example, here is a section heading followed by a concept index
+entry and two @samp{au} index address@hidden
+
address@hidden
+@@section Cognitive Semantics
+@@cindex kinesthetic image schemas
+@@auindex Johnson, Mark
+@@auindex Lakoff, George
address@hidden example
+
address@hidden
+(Evidently, @samp{au} serves here as an abbreviation for ``author''.)
+Texinfo constructs the new indexing command by concatenating the name
+of the index with @samp{index}; thus, defining an @samp{au} index
+leads to the automatic creation of an @code{@@auindex} address@hidden
+
+Use the @code{@@printindex} command to print the index, as you do with
+the predefined indices. For example:@refill
+
address@hidden
address@hidden
+@@node Author Index, Subject Index, , Top
+@@unnumbered Author Index
+
+@@printindex au
address@hidden group
address@hidden example
+
+The @code{@@defcodeindex} is like the @code{@@defindex} command, except
+that, in the printed output, it prints entries in an @code{@@code} font
+instead of a roman font. Thus, it parallels the @code{@@findex} command
+rather than the @code{@@cindex} address@hidden
+
+You should define new indices within or right after the end-of-header
+line of a Texinfo file, before any @code{@@synindex} or
address@hidden@@syncodeindex} commands (@pxref{Texinfo File Header}).
+
+
address@hidden Insertions
address@hidden Special Insertions
address@hidden Inserting special characters and symbols
address@hidden Special insertions
+
+Texinfo provides several commands for inserting characters that have
+special meaning in Texinfo, such as braces, and for other graphic
+elements that do not correspond to simple characters you can type.
+
+
address@hidden
+* Braces Atsigns:: How to insert braces, @samp{@@}.
+* Inserting Space:: How to insert the right amount of space
+ within a sentence.
+* Inserting Accents:: How to insert accents and special characters.
+* Dots Bullets:: How to insert dots and bullets.
+* TeX and copyright:: How to insert the @TeX{} logo
+ and the copyright symbol.
+* pounds:: How to insert the pounds currency symbol.
+* minus:: How to insert a minus sign.
+* math:: How to format a mathematical expression.
+* Glyphs:: How to indicate results of evaluation,
+ expansion of macros, errors, etc.
+* Footnotes:: How to include footnotes.
+* Images:: How to include graphics.
address@hidden menu
+
+
address@hidden Braces Atsigns, Inserting Space, Insertions, Insertions
address@hidden Inserting @@ and Braces
address@hidden Inserting @@, braces
address@hidden Braces, inserting
address@hidden Special characters, commands to insert
address@hidden Commands to insert special characters
+
address@hidden@@} and curly braces are special characters in Texinfo. To insert
+these characters so they appear in text, you must put an @samp{@@} in
+front of these characters to prevent Texinfo from misinterpreting
+them.
+
+Do not put braces after any of these commands; they are not
+necessary.
+
address@hidden
+* Inserting An Atsign:: How to insert @samp{@@}.
+* Inserting Braces:: How to insert @address@hidden and
@address@hidden
address@hidden menu
+
address@hidden Inserting An Atsign, Inserting Braces, Braces Atsigns, Braces
Atsigns
address@hidden Inserting @samp{@@} with @@@@
address@hidden @@ @r{(literal @samp{@@})}
+
address@hidden@@@@} stands for a single @samp{@@} in either printed or Info
+output.
+
+Do not put braces after an @code{@@@@} command.
+
+
address@hidden Inserting Braces
address@hidden Inserting @address@hidden and @address@hidden @@@{ and @@@}
address@hidden @{ @r{(literal @address@hidden)}
address@hidden @} @r{(literal @address@hidden)}
+
address@hidden@@@{} stands for a single @address@hidden in either printed or
Info
+output.
+
address@hidden@@@}} stands for a single @address@hidden in either printed or
Info
+output.
+
+Do not put braces after either an @code{@@@{} or an @code{@@@}}
+command.
+
+
address@hidden Inserting Space
address@hidden Inserting Space
+
address@hidden Inserting space
address@hidden Spacing, inserting
+The following sections describe commands that control spacing of various
+kinds within and after sentences.
+
address@hidden
+* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
+* Ending a Sentence:: Sometimes it does.
+* Multiple Spaces:: Inserting multiple spaces.
+* dmn:: How to format a dimension.
address@hidden menu
+
+
address@hidden Not Ending a Sentence
address@hidden Not Ending a Sentence
+
address@hidden Not ending a sentence
address@hidden Sentence non-ending punctuation
address@hidden Periods, inserting
+Depending on whether a period or exclamation point or question mark is
+inside or at the end of a sentence, less or more space is inserted after
+a period in a typeset manual. Since it is not always possible
+to determine when a period ends a sentence and when it is used
+in an abbreviation, special commands are needed in some circumstances.
+Usually, Texinfo can guess how to handle periods, so you do not need to
+use the special commands; you just enter a period as you would if you
+were using a typewriter, which means you put two spaces after the
+period, question mark, or exclamation mark that ends a sentence.
+
address@hidden <colon> @r{(suppress widening)}
+Use the @code{@@:}@: command after a period, question mark,
+exclamation mark, or colon that should not be followed by extra space.
+For example, use @code{@@:}@: after periods that end abbreviations
+which are not at the ends of sentences.
+
+For example,
+
address@hidden
+The s.o.p.@@: has three parts @dots{}
+The s.o.p. has three parts @dots{}
address@hidden example
+
address@hidden
+produces
+
address@hidden
+The s.o.p.@: has three parts @address@hidden
+The s.o.p. has three parts @dots{}
address@hidden quotation
+
address@hidden
+(Incidentally, @samp{s.o.p.} is an abbreviation for ``Standard Operating
+Procedure''.)
+
address@hidden@@:} has no effect on the Info output. Do not put braces after
address@hidden@@:}.
+
+
address@hidden Ending a Sentence, Multiple Spaces, Not Ending a Sentence,
Inserting Space
address@hidden Ending a Sentence
+
address@hidden Ending a Sentence
address@hidden Sentence ending punctuation
+
address@hidden . @r{(end of sentence)}
address@hidden ! @r{(end of sentence)}
address@hidden ? @r{(end of sentence)}
+Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an
+exclamation point, and @code{@@?}@: instead of a question mark at the end
+of a sentence that ends with a single capital letter. Otherwise, @TeX{}
+will think the letter is an abbreviation and will not insert the correct
+end-of-sentence spacing. Here is an example:
+
address@hidden
+Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@.
+Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+Give it to M.I.B. and to address@hidden Also, give it to address@hidden@*
+Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
address@hidden quotation
+
+In the Info file output, @code{@@.}@: is equivalent to a simple
address@hidden; likewise for @code{@@!}@: and @code{@@?}@:.
+
+The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to
+work well with the Emacs sentence motion commands (@pxref{Sentences,,,
+emacs, The GNU Emacs Manual}).
+
+Do not put braces after any of these commands.
+
+
address@hidden Multiple Spaces, dmn, Ending a Sentence, Inserting Space
address@hidden Multiple Spaces
+
address@hidden Multiple spaces
address@hidden Whitespace, inserting
address@hidden Space, inserting horizontal
address@hidden (space)
address@hidden (tab)
address@hidden (newline)
+
+Ordinarily, @TeX{} collapses multiple whitespace characters (space, tab,
+and newline) into a single space. Info output, on the other hand,
+preserves whitespace as you type it, except for changing a newline into
+a space; this is why it is important to put two spaces at the end of
+sentences in Texinfo documents.
+
+Occasionally, you may want to actually insert several consecutive
+spaces, either for purposes of example (what your program does with
+multiple spaces as input), or merely for purposes of appearance in
+headings or lists. Texinfo supports three commands:
address@hidden@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all of
+which insert a single space into the output. (Here,
address@hidden@@@kbd{SPACE}} represents an @samp{@@} character followed by a
+space, i.e., @samp{@@ }, and @kbd{TAB} and @kbd{NL} represent the tab
+character and end-of-line, i.e., when @samp{@@} is the last character on
+a line.)
+
+For example,
address@hidden
+Spacey@@ @@ @@ @@
+example.
address@hidden example
+
address@hidden produces
+
address@hidden
+Spacey@ @ @ @
+example.
address@hidden example
+
+Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by
address@hidden@@multitable} (@pxref{Multi-column Tables}).
+
+Do not follow any of these commands with braces.
+
+To produce a non-breakable space, see @ref{w, non-breakable space}.
+
+
address@hidden dmn
address@hidden @code{@@address@hidden@address@hidden: Format a Dimension
address@hidden Thin space between number, dimension
address@hidden Dimension formatting
address@hidden Format a dimension
address@hidden dmn
+
+At times, you may want to write @address@hidden or
address@hidden@dmn{in}} with little or no space between the number and the
+abbreviation for the dimension. You can use the @code{@@dmn} command
+to do this. On seeing the command, @TeX{} inserts just enough space
+for proper typesetting; the Info formatting commands insert no space
+at all, since the Info file does not require it.
+
+To use the @code{@@dmn} command, write the number and then follow it
+immediately, with no intervening space, by @code{@@dmn}, and then by
+the dimension within braces. For example,
+
address@hidden
+A4 paper is 8.27@@address@hidden@} wide.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+A4 paper is address@hidden wide.
address@hidden quotation
+
+Not everyone uses this style. Some people prefer @address@hidden in.@@:}}
+or @address@hidden inches}} to @samp{8.27@@address@hidden@}} in the Texinfo
file.
+In these cases, however, the formatters may insert a line break between
+the number and the dimension, so use @code{@@w} (@pxref{w}). Also, if
+you write a period after an abbreviation within a sentence, you should
+write @samp{@@:} after the period to prevent @TeX{} from inserting extra
+whitespace, as shown here. @xref{Not Ending a Sentence}.
+
+
address@hidden Inserting Accents
address@hidden Inserting Accents
+
address@hidden Inserting accents
address@hidden Accents, inserting
address@hidden Floating accents, inserting
+
+Here is a table with the commands Texinfo provides for inserting
+floating accents. The commands with non-alphabetic names do not take
+braces around their argument (which is taken to be the next character).
+(Exception: @code{@@,} @emph{does} take braces around its argument.)
+This is so as to make the source as convenient to type and read as
+possible, since accented characters are very common in some languages.
+
address@hidden " @r{(umlaut accent)}
address@hidden Umlaut accent
address@hidden ' @r{(umlaut accent)}
address@hidden Acute accent
address@hidden = @r{(macron accent)}
address@hidden Macron accent
address@hidden ^ @r{(circumflex accent)}
address@hidden Circumflex accent
address@hidden ` @r{(grave accent)}
address@hidden Grave accent
address@hidden ~ @r{(tilde accent)}
address@hidden Tilde accent
address@hidden , @r{(cedilla accent)}
address@hidden Cedilla accent
address@hidden dotaccent
address@hidden Dot accent
address@hidden H @r{(Hungarian umlaut accent)}
address@hidden Hungarian umlaut accent
address@hidden ringaccent
address@hidden Ring accent
address@hidden tieaccent
address@hidden Tie-after accent
address@hidden u @r{(breve accent)}
address@hidden Breve accent
address@hidden ubaraccent
address@hidden Underbar accent
address@hidden udotaccent
address@hidden Underdot accent
address@hidden v @r{(check accent)}
address@hidden Check accent
address@hidden {@@address@hidden@}} {Output} {macron/overbar accent}
address@hidden Command @tab Output @tab What
address@hidden @t{@@"o} @tab @"o @tab umlaut accent
address@hidden @t{@@'o} @tab @'o @tab acute accent
address@hidden @t{@@,@address@hidden @tab @,{c} @tab cedilla
accent
address@hidden @t{@@=o} @tab @=o @tab macron/overbar
accent
address@hidden @t{@@^o} @tab @^o @tab circumflex accent
address@hidden @t{@@`o} @tab @`o @tab grave accent
address@hidden @t{@@~o} @tab @~o @tab tilde accent
address@hidden @t{@@address@hidden@}} @tab @dotaccent{o} @tab overdot accent
address@hidden @t{@@address@hidden@}} @tab @H{o} @tab long
Hungarian umlaut
address@hidden @t{@@address@hidden@}} @tab @ringaccent{o} @tab ring accent
address@hidden @t{@@address@hidden@}} @tab @tieaccent{oo} @tab tie-after accent
address@hidden @t{@@address@hidden@}} @tab @u{o} @tab breve
accent
address@hidden @t{@@address@hidden@}} @tab @ubaraccent{o} @tab underbar accent
address@hidden @t{@@address@hidden@}} @tab @udotaccent{o} @tab underdot accent
address@hidden @t{@@address@hidden@}} @tab @v{o} @tab hacek
or check accent
address@hidden multitable
+
+This table lists the Texinfo commands for inserting other characters
+commonly used in languages other than English.
+
address@hidden questiondown
address@hidden @questiondown{}
address@hidden exclamdown
address@hidden @exclamdown{}
address@hidden aa
address@hidden @aa{}
address@hidden AA
address@hidden @AA{}
address@hidden ae
address@hidden @ae{}
address@hidden AE
address@hidden @AE{}
address@hidden dotless
address@hidden @dotless{i}
address@hidden @dotless{j}
address@hidden Dotless i, j
address@hidden l
address@hidden @l{}
address@hidden L
address@hidden @L{}
address@hidden o
address@hidden @o{}
address@hidden O
address@hidden @O{}
address@hidden oe
address@hidden @oe{}
address@hidden OE
address@hidden @OE{}
address@hidden ss
address@hidden @ss{}
address@hidden Es-zet
address@hidden Sharp S
address@hidden German S
address@hidden {x@@address@hidden@}} {oe,OE} {es-zet or sharp S}
address@hidden @t{@@address@hidden@}} @tab @exclamdown{} @tab upside-down !
address@hidden @t{@@address@hidden@}} @tab @questiondown{} @tab upside-down ?
address@hidden @t{@@address@hidden@},@@address@hidden@}} @tab @aa{},@AA{}
@tab a,A with circle
address@hidden @t{@@address@hidden@},@@address@hidden@}} @tab @ae{},@AE{}
@tab ae,AE ligatures
address@hidden @t{@@address@hidden@}} @tab @dotless{i} @tab dotless i
address@hidden @t{@@address@hidden@}} @tab @dotless{j} @tab dotless j
address@hidden @t{@@address@hidden@},@@address@hidden@}} @tab @l{},@L{}
@tab suppressed-L,l
address@hidden @t{@@address@hidden@},@@address@hidden@}} @tab @o{},@O{}
@tab O,o with slash
address@hidden @t{@@address@hidden@},@@address@hidden@}} @tab @oe{},@OE{}
@tab oe,OE ligatures
address@hidden @t{@@address@hidden@}} @tab @ss{} @tab
es-zet or sharp S
address@hidden multitable
+
+
address@hidden Dots Bullets
address@hidden Inserting Ellipsis and Bullets
address@hidden Dots, inserting
address@hidden Bullets, inserting
address@hidden Ellipsis, inserting
address@hidden Inserting ellipsis
address@hidden Inserting dots
address@hidden Special typesetting commands
address@hidden Typesetting commands for dots, etc.
+
+An @dfn{ellipsis} (a line of dots) is not typeset as a string of
+periods, so a special command is used for ellipsis in Texinfo. The
address@hidden@@bullet} command is special, too. Each of these commands is
+followed by a pair of braces, @address@hidden@}}, without any whitespace
+between the name of the command and the braces. (You need to use braces
+with these commands because you can use them next to other text; without
+the braces, the formatters would be confused. @xref{Command Syntax, ,
+@@-Command Syntax}, for further information.)@refill
+
address@hidden
+* dots:: How to insert dots @dots{}
+* bullet:: How to insert a bullet.
address@hidden menu
+
+
address@hidden dots
address@hidden @code{@@address@hidden@} (@dots{}) and @code{@@address@hidden@}
(@enddots{})
address@hidden dots
address@hidden enddots
address@hidden Inserting dots
address@hidden Dots, inserting
+
+Use the @code{@@address@hidden@}} command to generate an ellipsis, which is
+three dots in a row, appropriately spaced, like this: address@hidden'. Do
+not simply write three periods in the input file; that would work for
+the Info file output, but would produce the wrong amount of space
+between the periods in the printed manual.
+
+Similarly, the @code{@@address@hidden@}} command generates an
+end-of-sentence ellipsis (four dots) @enddots{}
+
+
+
address@hidden bullet
address@hidden @code{@@address@hidden@} (@bullet{})
address@hidden bullet
+
+Use the @code{@@address@hidden@}} command to generate a large round dot, or
+the closest possible thing to one. In Info, an asterisk is address@hidden
+
+Here is a bullet: @bullet{}
+
+When you use @code{@@bullet} in @code{@@itemize}, you do not need to
+type the braces, because @code{@@itemize} supplies them.
+(@xref{itemize, , @code{@@itemize}}.)@refill
+
+
address@hidden TeX and copyright, pounds, Dots Bullets, Insertions
address@hidden Inserting @TeX{} and the Copyright Symbol
+
+The logo address@hidden' is typeset in a special fashion and it needs an
+@@-command. The copyright symbol, address@hidden', is also special.
+Each of these commands is followed by a pair of braces, @address@hidden@}},
+without any whitespace between the name of the command and the
address@hidden
+
address@hidden
+* tex:: How to insert the @TeX{} logo.
+* copyright symbol:: How to use @code{@@address@hidden@}.
address@hidden menu
+
+
address@hidden tex
address@hidden @code{@@address@hidden@} (@TeX{})
address@hidden tex (command)
+
+Use the @code{@@address@hidden@}} command to generate address@hidden'. In a
printed
+manual, this is a special logo that is different from three ordinary
+letters. In Info, it just looks like @samp{TeX}. The
address@hidden@@address@hidden@}} command is unique among Texinfo commands in
that the
address@hidden and the @samp{X} are in upper address@hidden
+
+
address@hidden copyright symbol
address@hidden @code{@@address@hidden@} (@copyright{})
address@hidden copyright
+
+Use the @code{@@address@hidden@}} command to generate address@hidden'. In
+a printed manual, this is a @samp{c} inside a circle, and in Info,
+this is @samp{(C)address@hidden
+
+
address@hidden pounds, minus, TeX and copyright, Insertions
address@hidden @code{@@address@hidden@} (@pounds{}): Pounds Sterling
address@hidden pounds
+
+Use the @code{@@address@hidden@}} command to generate address@hidden'. In a
+printed manual, this is the symbol for the currency pounds sterling.
+In Info, it is a @samp{#}. Other currency symbols are unfortunately not
+available.
+
+
address@hidden minus, math, pounds, Insertions
address@hidden @code{@@address@hidden@} (@minus{}): Inserting a Minus Sign
address@hidden minus
+
address@hidden em-dash
address@hidden hyphen
+Use the @code{@@address@hidden@}} command to generate a minus sign. In a
+fixed-width font, this is a single hyphen, but in a proportional font,
+the symbol is the customary length for a minus sign---a little longer
+than a hyphen, shorter than an em-dash:
+
address@hidden
address@hidden@minus{}} is a minus sign generated with
@samp{@@address@hidden@}},
+
+`-' is a hyphen generated with the character @samp{-},
+
+`---' is an em-dash for text.
address@hidden display
+
address@hidden
+In the fixed-width font used by Info, @code{@@address@hidden@}} is the same
+as a hyphen.
+
+You should not use @code{@@address@hidden@}} inside @code{@@code} or
address@hidden@@example} because the width distinction is not made in the
+fixed-width font they use.
+
+When you use @code{@@minus} to specify the mark beginning each entry in
+an itemized list, you do not need to type the braces
+(@pxref{itemize, , @code{@@itemize}}.)
+
+
address@hidden math
address@hidden @code{@@math}: Inserting Mathematical Expressions
address@hidden math
address@hidden Mathematical expressions
address@hidden Formulas, mathematical
+
+You can write a short mathematical expression with the @code{@@math}
+command. Write the mathematical expression between braces, like this:
+
address@hidden
+@@address@hidden(a + b)(a + b) = a^2 + 2ab + address@hidden
address@hidden example
+
address@hidden This produces the following in Info:
+
address@hidden
+(a + b)(a + b) = a^2 + 2ab + b^2
address@hidden example
+
+Thus, the @code{@@math} command has no effect on the Info output.
+
address@hidden@@math} implies @code{@@tex}. This not only makes it possible to
+write superscripts and subscripts (as in the above example), but also
+allows you to use any of the plain @TeX{} math control sequences. It's
+conventional to use @samp{\} instead of @samp{@@} for these commands.
+As in:
address@hidden
+@@address@hidden 2\pi \equiv \cos address@hidden
address@hidden example
+
address@hidden which looks like the input in Info and HTML:
address@hidden
+\sin 2\pi \equiv \cos 3\pi
address@hidden example
+
address@hidden \ @r{(literal \ in @code{@@math})}
+Since @samp{\} is an escape character inside @code{@@math}, you can use
address@hidden@@\} to get a literal backslash (@code{\\} will work in @TeX{},
+but you'll get the literal @samp{\\} in Info). @code{@@\} is not
+defined outside of @code{@@math}, since a @samp{\} ordinarily produces a
+literal @samp{\}.
+
+
address@hidden Displayed equations
address@hidden Equations, displayed
+For displayed equations, you must at present use @TeX{} directly
+(@pxref{Raw Formatter Commands}).
+
+
address@hidden Glyphs
address@hidden Glyphs for Examples
address@hidden Glyphs
address@hidden Examples, glyphs for
+
+In Texinfo, code is often illustrated in examples that are delimited
+by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and
address@hidden@@end lisp}. In such examples, you can indicate the results of
+evaluation or an expansion using @address@hidden or
address@hidden@expansion{}}. Likewise, there are commands to insert glyphs
+to indicate
+printed output, error messages, equivalence of expressions, and the
+location of address@hidden
+
+The glyph-insertion commands do not need to be used within an example, but
+most often they are. Every glyph-insertion command is followed by a pair of
+left- and right-hand address@hidden
+
address@hidden
+* Glyphs Summary::
+* result:: How to show the result of expression.
+* expansion:: How to indicate an expansion.
+* Print Glyph:: How to indicate printed output.
+* Error Glyph:: How to indicate an error message.
+* Equivalence:: How to indicate equivalence.
+* Point Glyph:: How to indicate the location of point.
address@hidden menu
+
+
address@hidden Glyphs Summary
address@hidden Glyphs Summary
+
+Here are the different glyph commands:@refill
+
address@hidden @asis
address@hidden @result{}
address@hidden@@address@hidden@}} points to the result of an address@hidden
+
address@hidden @expansion{}
address@hidden@@address@hidden@}} shows the results of a macro address@hidden
+
address@hidden @print{}
address@hidden@@address@hidden@}} indicates printed address@hidden
+
address@hidden @error{}
address@hidden@@address@hidden@}} indicates that the following text is an error
address@hidden
+
address@hidden @equiv{}
address@hidden@@address@hidden@}} indicates the exact equivalence of two
address@hidden
+
address@hidden @point{}
address@hidden@@address@hidden@}} shows the location of address@hidden
address@hidden table
+
address@hidden
+* result::
+* expansion::
+* Print Glyph::
+* Error Glyph::
+* Equivalence::
+* Point Glyph::
address@hidden menu
+
+
address@hidden result
address@hidden @code{@@address@hidden@}} (@result{}): Indicating Evaluation
address@hidden Result of an expression
address@hidden Indicating evaluation
address@hidden Evaluation glyph
address@hidden Value of an expression, indicating
address@hidden result
+
+Use the @code{@@address@hidden@}} command to indicate the result of
+evaluating an address@hidden
+
+The @code{@@address@hidden@}} command is displayed as @address@hidden in Info
+and as a double stemmed arrow in the printed address@hidden
+
+Thus, the following,
+
address@hidden
+(cdr '(1 2 3))
+ @result{} (2 3)
address@hidden lisp
+
address@hidden
+may be read as address@hidden(cdr '(1 2 3))} evaluates to @code{(2 3)}''.
+
+
address@hidden expansion, Print Glyph, result, Glyphs
address@hidden @code{@@address@hidden@}} (@expansion{}): Indicating an Expansion
address@hidden Expansion, indicating it
address@hidden expansion
+
+When an expression is a macro call, it expands into a new expression.
+You can indicate the result of the expansion with the
address@hidden@@address@hidden@}} address@hidden
+
+The @code{@@address@hidden@}} command is displayed as @address@hidden
+in Info and as a long arrow with a flat base in the printed address@hidden
+
address@hidden 700
+For example, the following
+
address@hidden
address@hidden
+@@lisp
+(third '(a b c))
+ @@address@hidden@} (car (cdr (cdr '(a b c))))
+ @@address@hidden@} c
+@@end lisp
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+(third '(a b c))
+ @expansion{} (car (cdr (cdr '(a b c))))
+ @result{} c
address@hidden group
address@hidden lisp
+
address@hidden
+which may be read as:
+
address@hidden
address@hidden(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))};
+the result of evaluating the expression is @code{c}.
address@hidden quotation
+
address@hidden
+Often, as in this case, an example looks better if the
address@hidden@@address@hidden@}} and @code{@@address@hidden@}} commands are
indented
+five address@hidden
+
+
address@hidden Print Glyph, Error Glyph, expansion, Glyphs
address@hidden @code{@@address@hidden@}} (@print{}): Indicating Printed Output
address@hidden Printed output, indicating it
address@hidden print
+
+Sometimes an expression will print output during its execution. You
+can indicate the printed output with the @code{@@address@hidden@}}
address@hidden
+
+The @code{@@address@hidden@}} command is displayed as @address@hidden in Info
+and similarly, as a horizontal dash butting against a vertical bar, in
+the printed address@hidden
+
+In the following example, the printed text is indicated with
address@hidden@print{}}, and the value of the expression follows on the
+last address@hidden
+
address@hidden
address@hidden
+(progn (print 'foo) (print 'bar))
+ @print{} foo
+ @print{} bar
+ @result{} bar
address@hidden group
address@hidden lisp
+
address@hidden
+In a Texinfo source file, this example is written as follows:
+
address@hidden
address@hidden
+@@lisp
+(progn (print 'foo) (print 'bar))
+ @@address@hidden@} foo
+ @@address@hidden@} bar
+ @@address@hidden@} bar
+@@end lisp
address@hidden group
address@hidden lisp
+
+
address@hidden Error Glyph, Equivalence, Print Glyph, Glyphs
address@hidden @code{@@address@hidden@}} (@error{}): Indicating an Error Message
address@hidden Error message, indicating it
address@hidden error
+
+A piece of code may cause an error when you evaluate it. You can
+designate the error message with the @code{@@address@hidden@}} address@hidden
+
+The @code{@@address@hidden@}} command is displayed as @address@hidden in Info
+and as the word `error' in a box in the printed address@hidden
+
address@hidden 700
+Thus,
+
address@hidden
+@@lisp
+(+ 23 'x)
+@@address@hidden@} Wrong type argument: integer-or-marker-p, x
+@@end lisp
address@hidden example
+
address@hidden
+produces
+
address@hidden
+(+ 23 'x)
address@hidden Wrong type argument: integer-or-marker-p, x
address@hidden lisp
+
address@hidden
+This indicates that the following error message is printed
+when you evaluate the expression:
+
address@hidden
+Wrong type argument: integer-or-marker-p, x
address@hidden lisp
+
address@hidden@error{}} itself is not part of the error message.
+
+
address@hidden Equivalence, Point Glyph, Error Glyph, Glyphs
address@hidden @code{@@address@hidden@}} (@equiv{}): Indicating Equivalence
address@hidden Equivalence, indicating it
address@hidden equiv
+
+Sometimes two expressions produce identical results. You can indicate the
+exact equivalence of two forms with the @code{@@address@hidden@}}
address@hidden
+
+The @code{@@address@hidden@}} command is displayed as @address@hidden in Info
+and as a three parallel horizontal lines in the printed address@hidden
+
+Thus,
+
address@hidden
+@@lisp
+(make-sparse-keymap) @@address@hidden@} (list 'keymap)
+@@end lisp
address@hidden example
+
address@hidden
+produces
+
address@hidden
+(make-sparse-keymap) @equiv{} (list 'keymap)
address@hidden lisp
+
address@hidden
+This indicates that evaluating @code{(make-sparse-keymap)} produces
+identical results to evaluating @code{(list 'keymap)}.
+
+
address@hidden Point Glyph
address@hidden @code{@@address@hidden@}} (@point{}): Indicating Point in a
Buffer
address@hidden Point, indicating in a buffer
address@hidden point
+
+Sometimes you need to show an example of text in an Emacs buffer. In
+such examples, the convention is to include the entire contents of the
+buffer in question between two lines of dashes containing the buffer
address@hidden
+
+You can use the @samp{@@address@hidden@}} command to show the location of point
+in the text in the buffer. (The symbol for point, of course, is not
+part of the text in the buffer; it indicates the place @emph{between}
+two characters where point is located.)@refill
+
+The @code{@@address@hidden@}} command is displayed as @address@hidden in Info
+and as a small five pointed star in the printed address@hidden
+
+The following example shows the contents of buffer @file{foo} before
+and after evaluating a Lisp command to insert the word @address@hidden
+
address@hidden
address@hidden
+---------- Buffer: foo ----------
+This is the @point{}contents of foo.
+---------- Buffer: foo ----------
+
address@hidden group
address@hidden example
+
address@hidden
address@hidden
+(insert "changed ")
+ @result{} nil
+---------- Buffer: foo ----------
+This is the changed @point{}contents of foo.
+---------- Buffer: foo ----------
+
address@hidden group
address@hidden example
+
+In a Texinfo source file, the example is written like this:@refill
+
address@hidden
+@@example
+---------- Buffer: foo ----------
+This is the @@address@hidden@}contents of foo.
+---------- Buffer: foo ----------
+
+(insert "changed ")
+ @@address@hidden@} nil
+---------- Buffer: foo ----------
+This is the changed @@address@hidden@}contents of foo.
+---------- Buffer: foo ----------
+@@end example
address@hidden example
+
+
address@hidden Footnotes
address@hidden Footnotes
address@hidden Footnotes
address@hidden footnote
+
+A @dfn{footnote} is for a reference that documents or elucidates the
+primary address@hidden footnote should complement or expand upon
+the primary text, but a reader should not need to read a footnote to
+understand the primary text. For a thorough discussion of footnotes,
+see @cite{The Chicago Manual of Style}, which is published by the
+University of Chicago Press.}
+
address@hidden
+* Footnote Commands:: How to write a footnote in Texinfo.
+* Footnote Styles:: Controlling how footnotes appear in Info.
address@hidden menu
+
+
address@hidden Footnote Commands
address@hidden Footnote Commands
+
+In Texinfo, footnotes are created with the @code{@@footnote} command.
+This command is followed immediately by a left brace, then by the text
+of the footnote, and then by a terminating right brace. Footnotes may
+be of any length (they will be broken across pages if necessary), but
+are usually short. The template is:
+
address@hidden
+ordinary text@@address@hidden@var{text of address@hidden
address@hidden example
+
+As shown here, the @code{@@footnote} command should come right after the
+text being footnoted, with no intervening space; otherwise, the footnote
+marker might end up starting a line.
+
+For example, this clause is followed by a sample address@hidden
+is the sample footnote.}; in the Texinfo source, it looks like
+this:
+
address@hidden
address@hidden sample footnote@@address@hidden is the sample
address@hidden; in the Texinfo address@hidden
address@hidden example
+
+As you can see, the source includes two punctuation marks next to each
+other; in this case, @address@hidden;} is the sequence. This is normal (the
+first ends the footnote and the second belongs to the sentence being
+footnoted), so don't worry that it looks odd.
+
+In a printed manual or book, the reference mark for a footnote is a
+small, superscripted number; the text of the footnote appears at the
+bottom of the page, below a horizontal line.
+
+In Info, the reference mark for a footnote is a pair of parentheses
+with the footnote number between them, like this: @samp{(1)}. The
+reference mark is followed by a cross-reference link to the footnote's
+text.
+
+In the HTML output, footnote references are marked with a small,
+superscripted number which is rendered as a hypertext link to the
+footnote text.
+
+By the way, footnotes in the argument of an @code{@@item} command for a
address@hidden@@table} must be on the same line as the @code{@@item}
+(as usual). @xref{Two-column Tables}.
+
+
address@hidden Footnote Styles
address@hidden Footnote Styles
+
+Info has two footnote styles, which determine where the text of the
+footnote is located:@refill
+
address@hidden @bullet
address@hidden @address@hidden node footnote style
address@hidden
+In the `End' node style, all the footnotes for a single node
+are placed at the end of that node. The footnotes are separated from
+the rest of the node by a line of dashes with the word
address@hidden within it. Each footnote begins with an
address@hidden(@var{n})} reference address@hidden
+
address@hidden 700
address@hidden
+Here is an example of a single footnote in the end of node style:@refill
+
address@hidden
address@hidden
+ --------- Footnotes ---------
+
+(1) Here is a sample footnote.
address@hidden group
address@hidden example
+
address@hidden @address@hidden footnote style
address@hidden
+In the `Separate' node style, all the footnotes for a single
+node are placed in an automatically constructed node of
+their own. In this style, a ``footnote reference'' follows
+each @samp{(@var{n})} reference mark in the body of the
+node. The footnote reference is actually a cross reference
+which you use to reach the footnote address@hidden
+
+The name of the node with the footnotes is constructed
+by appending @address@hidden to the name of the node
+that contains the footnotes. (Consequently, the footnotes'
+node for the @file{Footnotes} node is
address@hidden@file{Footnotes-Footnotes}}!) The footnotes' node has an
+`Up' node pointer that leads back to its parent address@hidden
+
address@hidden
+Here is how the first footnote in this manual looks after being
+formatted for Info in the separate node style:@refill
+
address@hidden
address@hidden
+File: texinfo.info Node: Overview-Footnotes, Up: Overview
+
+(1) The first syllable of "Texinfo" is pronounced like "speck", not
+"hex". @dots{}
address@hidden group
address@hidden smallexample
address@hidden itemize
+
+A Texinfo file may be formatted into an Info file with either footnote
address@hidden
+
address@hidden footnotestyle
+Use the @code{@@footnotestyle} command to specify an Info file's
+footnote style. Write this command at the beginning of a line followed
+by an argument, either @samp{end} for the end node style or
address@hidden for the separate node style.
+
address@hidden 700
+For example,
+
address@hidden
+@@footnotestyle end
address@hidden example
address@hidden
+or
address@hidden
+@@footnotestyle separate
address@hidden example
+
+Write an @code{@@footnotestyle} command before or shortly after the
+end-of-header line at the beginning of a Texinfo file. (If you
+include the @code{@@footnotestyle} command between the start-of-header
+and end-of-header lines, the region formatting commands will format
+footnotes as specified.)@refill
+
+If you do not specify a footnote style, the formatting commands use
+their default style. Currently, @code{texinfo-format-buffer} and
address@hidden use the `separate' style and
address@hidden uses the `end' address@hidden
+
address@hidden !!! note: makeinfo's --footnote-style option overrides
footnotestyle
+This chapter contains two address@hidden
+
+
address@hidden this should be described with figures when we have them
address@hidden perhaps in the quotation/example chapter.
address@hidden Images
address@hidden Inserting Images
+
address@hidden Images, inserting
address@hidden Pictures, inserting
address@hidden image
+
+You can insert an image given in an external file with the
address@hidden@@image} command:
+
address@hidden
+@@address@hidden@var{filename}, @address@hidden@r{]}, @address@hidden@r{]},
@address@hidden@r{]}, @address@hidden@address@hidden
address@hidden example
+
address@hidden Formats for images
address@hidden Image formats
+The @var{filename} argument is mandatory, and must not have an
+extension, because the different processors support different formats:
address@hidden @bullet
address@hidden
address@hidden reads the file @address@hidden (Encapsulated PostScript
+format).
address@hidden
address@hidden address@hidden, and images}
address@hidden reads @address@hidden (Adobe's Portable Document Format).
address@hidden
address@hidden uses @address@hidden verbatim for
+Info output (more or less as if it was an @code{@@example}).
address@hidden
address@hidden
+uses the optional fifth argument to @code{@@image} for the extension if
+you supply it. For example:
+
address@hidden XPM image format
address@hidden
+@@address@hidden,,,,address@hidden
address@hidden example
+
address@hidden
+will cause @samp{makeinfo --html} to try @file{foo.xpm}.
+
address@hidden GIF, unsupported due to patents
address@hidden PNG image format
address@hidden JPG image format
+If you do not supply the optional fifth argument, @samp{makeinfo
+---html} first tries @address@hidden; if that does not exist,
+it tries @address@hidden If that does not exist either, it
+complains. (We cannot support GIF format directly due to software
+patents.)
address@hidden itemize
+
address@hidden Width of images
address@hidden Height of images
address@hidden Aspect ratio of images
address@hidden Distorting images
+The optional @var{width} and @var{height} arguments specify the size to
+scale the image to (they are ignored for Info output). If neither is
+specified, the image is presented in its natural size (given in the
+file); if only one is specified, the other is scaled proportionately;
+and if both are specified, both are respected, thus possibly distorting
+the original image by changing its aspect ratio.
+
address@hidden Dimensions and image sizes
+The @var{width} and @var{height} may be specified using any valid @TeX{}
+dimension, namely:
+
address@hidden @asis
address@hidden pt
address@hidden Points (dimension)
+point (72.27pt = 1in)
address@hidden pc
address@hidden Picas
+pica (1pc = 12pt)
address@hidden bp
address@hidden Big points
+big point (72bp = 1in)
address@hidden in
address@hidden Inches
+inch
address@hidden cm
address@hidden Centimeters
+centimeter (2.54cm = 1in)
address@hidden mm
address@hidden Millimeters
+millimeter (10mm = 1cm)
address@hidden dd
address@hidden address@hidden points
address@hidden point (1157dd = 1238pt)
address@hidden cc
address@hidden Ciceros
+cicero (1cc = 12dd)
address@hidden sp
address@hidden Scaled points
+scaled point (65536sp = 1pt)
address@hidden table
+
address@hidden ridt.eps
+For example, the following will scale a file @file{ridt.eps} to one
+inch vertically, with the width scaled proportionately:
+
address@hidden
+@@address@hidden,,address@hidden
address@hidden example
+
address@hidden epsf.tex
+For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be
+installed somewhere that @TeX{} can find it. (The standard location is
address@hidden@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a
+root of your @TeX{} directory tree.) This file is included in the
+Texinfo distribution and is also available from
address@hidden://tug.org/tex/epsf.tex}, among other places.
+
address@hidden@@image} can be used within a line as well as for displayed
+figures. Therefore, if you intend it to be displayed, be sure to leave
+a blank line before the command, or the output will run into the
+preceding text.
+
address@hidden alt attribute for images
address@hidden alternate text for images
+When producing html, @code{makeinfo} sets the @dfn{alt attribute} for
+inline images to the optional fourth argument to @code{@@image}, if
+supplied. If not supplied, @code{makeinfo} uses the full file name of
+the image being displayed.
+
+
address@hidden Breaks
address@hidden Making and Preventing Breaks
address@hidden Making line and page breaks
address@hidden Preventing line and page breaks
+
address@hidden Line breaks
+Usually, a Texinfo file is processed both by @TeX{} and by one of the
+Info formatting commands. Line, paragraph, or page breaks sometimes
+occur in the `wrong' place in one or other form of output. You must
+ensure that text looks right both in the printed manual and in the
+Info file.
+
address@hidden White space, excessive
address@hidden Page breaks
+For example, in a printed manual, page breaks may occur awkwardly in
+the middle of an example; to prevent this, you can hold text together
+using a grouping command that keeps the text from being split across
+two pages. Conversely, you may want to force a page break where none
+would occur normally. Fortunately, problems like these do not often
+arise. When they do, use the break, break prevention, or pagination
+commands.
+
address@hidden
+* Break Commands:: Cause and prevent splits.
+* Line Breaks:: How to force a single line to use two lines.
+* - and hyphenation:: How to tell @TeX{} about hyphenation points.
+* w:: How to prevent unwanted line breaks.
+* sp:: How to insert blank lines.
+* page:: How to force the start of a new page.
+* group:: How to prevent unwanted page breaks.
+* need:: Another way to prevent unwanted page breaks.
address@hidden menu
+
+
address@hidden Break Commands, Line Breaks, Breaks, Breaks
address@hidden Break Commands
+
+The break commands create or allow line and paragraph breaks:@refill
+
address@hidden @code
address@hidden @@*
+Force a line break.
+
address@hidden @@sp @var{n}
+Skip @var{n} blank address@hidden
+
address@hidden @@-
+Insert a discretionary hyphen.
+
address@hidden @@address@hidden@var{hy-phen-a-ted address@hidden
+Define hyphen points in @var{hy-phen-a-ted words}.
address@hidden table
+
+The line-break-prevention command holds text together all on one
+line:@refill
+
address@hidden @code
address@hidden @@address@hidden@address@hidden
+Prevent @var{text} from being split and hyphenated across two address@hidden
address@hidden table
+
+The pagination commands apply only to printed output, since Info
+files do not have address@hidden
+
address@hidden @code
address@hidden @@page
+Start a new page in the printed address@hidden
+
address@hidden @@group
+Hold text together that must appear on one printed address@hidden
+
address@hidden @@need @var{mils}
+Start a new printed page if not enough space on this address@hidden
address@hidden table
+
address@hidden Line Breaks
address@hidden @code{@@*}: Generate Line Breaks
address@hidden * @r{(force line break)}
address@hidden Line breaks
address@hidden Breaks in a line
+
+The @code{@@*} command forces a line break in both the printed manual and
+in address@hidden
+
address@hidden 700
+For example,
+
address@hidden
+This line @@* is broken @@*in two places.
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+This line
+ is broken
+in two places.
address@hidden group
address@hidden example
+
address@hidden
+(Note that the space after the first @code{@@*} command is faithfully
+carried down to the next line.)@refill
+
address@hidden 800
+The @code{@@*} command is often used in a file's copyright page:@refill
+
address@hidden
address@hidden
+This is edition 2.0 of the Texinfo documentation,@@*
+and is for @dots{}
address@hidden group
address@hidden example
+
address@hidden
+In this case, the @code{@@*} command keeps @TeX{} from stretching the
+line across the whole page in an ugly address@hidden
+
address@hidden
address@hidden note:} Do not write braces after an @code{@@*} command;
+they are not address@hidden
+
+Do not write an @code{@@refill} command at the end of a paragraph
+containing an @code{@@*} command; it will cause the paragraph to be
+refilled after the line break occurs, negating the effect of the line
address@hidden
address@hidden quotation
+
+
address@hidden - and hyphenation
address@hidden @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate
+
address@hidden - @r{(discretionary hyphen)}
address@hidden hyphenation
address@hidden Hyphenation, helping @TeX{} do
address@hidden Fine-tuning, and hyphenation
+
+Although @TeX{}'s hyphenation algorithm is generally pretty good, it
+does miss useful hyphenation points from time to time. (Or, far more
+rarely, insert an incorrect hyphenation.) So, for documents with an
+unusual vocabulary or when fine-tuning for a printed edition, you may
+wish to help @TeX{} out. Texinfo supports two commands for this:
+
address@hidden @code
address@hidden @@-
+Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does
+not have to) hyphenate. This is especially useful when you notice an
+overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull
+hboxes}). @TeX{} will not insert any hyphenation points itself into a
+word containing @code{@@-}.
+
address@hidden @@address@hidden@var{hy-phen-a-ted address@hidden
+Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you
+put a @samp{-} at each hyphenation point. For example:
address@hidden
+@@address@hidden address@hidden
address@hidden example
address@hidden @TeX{} only uses the specified hyphenation points when the
+words match exactly, so give all necessary variants.
address@hidden table
+
+Info output is not hyphenated, so these commands have no effect there.
+
address@hidden w
address@hidden @code{@@address@hidden@address@hidden: Prevent Line Breaks
address@hidden w @r{(prevent line break)}
address@hidden Line breaks, preventing
address@hidden Hyphenation, preventing
+
address@hidden@@address@hidden@address@hidden outputs @var{text} and prohibits
line breaks
+within @address@hidden
+
+You can use the @code{@@w} command to prevent @TeX{} from automatically
+hyphenating a long name or phrase that happens to fall near the end of a
+line. For example:
+
address@hidden
+You can copy GNU software from @@address@hidden@@address@hidden@address@hidden
address@hidden example
+
address@hidden
+produces
+
address@hidden
+You can copy GNU software from @address@hidden
address@hidden quotation
+
address@hidden Non-breakable space
address@hidden Unbreakable space
address@hidden Tied space
+You can also use @code{@@w} to produce a non-breakable space:
+
address@hidden
+None of the formatters will break at this@@address@hidden @}space.
address@hidden example
+
+
address@hidden sp
address@hidden @code{@@sp} @var{n}: Insert Blank Lines
address@hidden sp @r{(line spacing)}
address@hidden Space, inserting vertical
address@hidden Blank lines
address@hidden Line spacing
+
+A line beginning with and containing only @code{@@sp @var{n}}
+generates @var{n} blank lines of space in both the printed manual and
+the Info file. @code{@@sp} also forces a paragraph break. For
+example,
+
address@hidden
+@@sp 2
address@hidden example
+
address@hidden
+generates two blank lines.
+
+The @code{@@sp} command is most often used in the title address@hidden
+
+
+
address@hidden page
address@hidden @code{@@page}: Start a New Page
address@hidden Page breaks
address@hidden page
+
+A line containing only @code{@@page} starts a new page in a printed
+manual. The command has no effect on Info files since they are not
+paginated. An @code{@@page} command is often used in the @code{@@titlepage}
+section of a Texinfo file to start the copyright page.
+
+
address@hidden group, need, page, Breaks
address@hidden node-name, next, previous, up
address@hidden @code{@@group}: Prevent Page Breaks
address@hidden Group (hold text together vertically)
address@hidden Holding text together vertically
address@hidden Vertically holding text together
address@hidden group
+
+The @code{@@group} command (on a line by itself) is used inside an
address@hidden@@example} or similar construct to begin an unsplittable vertical
+group, which will appear entirely on one page in the printed output.
+The group is terminated by a line containing only @code{@@end group}.
+These two lines produce no output of their own, and in the Info file
+output they have no effect at address@hidden
+
address@hidden Once said that these environments
address@hidden turn off vertical spacing between ``paragraphs''.
address@hidden Also, quotation used to work, but doesn't in texinfo-2.72
+Although @code{@@group} would make sense conceptually in a wide
+variety of contexts, its current implementation works reliably only
+within @code{@@example} and variants, and within @code{@@display},
address@hidden@@format}, @code{@@flushleft} and @code{@@flushright}.
address@hidden and Examples}. (What all these commands have in
+common is that each line of input produces a line of output.) In
+other contexts, @code{@@group} can cause anomalous vertical
address@hidden
+
address@hidden 750
+This formatting requirement means that you should write:
+
address@hidden
address@hidden
+@@example
+@@group
address@hidden
+@@end group
+@@end example
address@hidden group
address@hidden example
+
address@hidden
+with the @code{@@group} and @code{@@end group} commands inside the
address@hidden@@example} and @code{@@end example} commands.
+
+The @code{@@group} command is most often used to hold an example
+together on one page. In this Texinfo manual, more than 100 examples
+contain text that is enclosed between @code{@@group} and @code{@@end
+group}.
+
+If you forget to end a group, you may get strange and unfathomable
+error messages when you run @TeX{}. This is because @TeX{} keeps
+trying to put the rest of the Texinfo file onto the one page and does
+not start to generate error messages until it has processed
+considerable text. It is a good rule of thumb to look for a missing
address@hidden@@end group} if you get incomprehensible error messages in
address@hidden@refill
+
address@hidden need, , group, Breaks
address@hidden node-name, next, previous, up
address@hidden @code{@@need @var{mils}}: Prevent Page Breaks
address@hidden Need space at page bottom
address@hidden need
+
+A line containing only @code{@@need @var{n}} starts
+a new page in a printed manual if fewer than @var{n} mils (thousandths
+of an inch) remain on the current page. Do not use
+braces around the argument @var{n}. The @code{@@need} command has no
+effect on Info files since they are not address@hidden
+
address@hidden 800
+This paragraph is preceded by an @code{@@need} command that tells
address@hidden to start a new page if fewer than 800 mils (eight-tenths
+inch) remain on the page. It looks like this:@refill
+
address@hidden
address@hidden
+@@need 800
+This paragraph is preceded by @dots{}
address@hidden group
address@hidden example
+
+The @code{@@need} command is useful for preventing orphans (single
+lines at the bottoms of printed pages)address@hidden
+
+
address@hidden Definition Commands
address@hidden Definition Commands
address@hidden Definition commands
+
+The @code{@@deffn} command and the other @dfn{definition commands}
+enable you to describe functions, variables, macros, commands, user
+options, special forms and other such artifacts in a uniform
address@hidden
+
+In the Info file, a definition causes the entity
+category---`Function', `Variable', or whatever---to appear at the
+beginning of the first line of the definition, followed by the
+entity's name and arguments. In the printed manual, the command
+causes @TeX{} to print the entity's name and its arguments on the left
+margin and print the category next to the right margin. In both
+output formats, the body of the definition is indented. Also, the
+name of the entity is entered into the appropriate index:
address@hidden@@deffn} enters the name into the index of functions,
address@hidden@@defvr} enters it into the index of variables, and so
address@hidden
+
+A manual need not and should not contain more than one definition for
+a given name. An appendix containing a summary should use
address@hidden@@table} rather than the definition address@hidden
+
address@hidden
+* Def Cmd Template:: How to structure a description using a
+ definition command.
+* Optional Arguments:: How to handle optional and repeated arguments.
+* deffnx:: How to group two or more `first' lines.
+* Def Cmds in Detail:: All the definition commands.
+* Def Cmd Conventions:: Conventions for writing definitions.
+* Sample Function Definition::
address@hidden menu
+
address@hidden Def Cmd Template, Optional Arguments, Definition Commands,
Definition Commands
address@hidden The Template for a Definition
address@hidden Definition template
address@hidden Template for a definition
+
+The @code{@@deffn} command is used for definitions of entities that
+resemble functions. To write a definition using the @code{@@deffn}
+command, write the @code{@@deffn} command at the beginning of a line
+and follow it on the same line by the category of the entity, the name
+of the entity itself, and its arguments (if any). Then write the body
+of the definition on succeeding lines. (You may embed examples in the
+body.) Finally, end the definition with an @code{@@end deffn} command
+written on a line of its own. (The other definition commands follow
+the same format.)@refill
+
+The template for a definition looks like this:
+
address@hidden
address@hidden
+@@deffn @var{category} @var{name} @address@hidden
address@hidden
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden 700
address@hidden
+For example,
+
address@hidden
address@hidden
+@@deffn Command forward-word count
+This command moves point forward @@address@hidden@} words
+(or backward if @@address@hidden@} is negative). @dots{}
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden Command forward-word count
+This function moves point forward @var{count} words
+(or backward if @var{count} is negative). @dots{}
address@hidden deffn
address@hidden quotation
+
+Capitalize the category name like a title. If the name of the
+category contains spaces, as in the phrase `Interactive Command',
+write braces around it. For example:@refill
+
address@hidden
address@hidden
+@@deffn @{Interactive address@hidden isearch-forward
address@hidden
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden
+Otherwise, the second word will be mistaken for the name of the
address@hidden
+
+Some of the definition commands are more general than others. The
address@hidden@@deffn} command, for example, is the general definition command
+for functions and the like---for entities that may take arguments. When
+you use this command, you specify the category to which the entity
+belongs. The @code{@@deffn} command possesses three predefined,
+specialized variations, @code{@@defun}, @code{@@defmac}, and
address@hidden@@defspec}, that specify the category for you: ``Function'',
+``Macro'', and ``Special Form'' respectively. (In Lisp, a special form
+is an entity much like a function.) The @code{@@defvr} command also is
+accompanied by several predefined, specialized variations for describing
+particular kinds of address@hidden
+
+The template for a specialized definition, such as @code{@@defun}, is
+similar to the template for a generalized definition, except that you
+do not need to specify the category:@refill
+
address@hidden
address@hidden
+@@defun @var{name} @address@hidden
address@hidden
+@@end defun
address@hidden group
address@hidden example
+
address@hidden
+Thus,
+
address@hidden
address@hidden
+@@defun buffer-end flag
+This function returns @@address@hidden(point-min)@} if @@address@hidden@}
+is less than 1, @@address@hidden(point-max)@} otherwise.
address@hidden
+@@end defun
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden buffer-end flag
+This function returns @code{(point-min)} if @var{flag} is less than 1,
address@hidden(point-max)} otherwise. @dots{}
address@hidden defun
address@hidden quotation
+
address@hidden
address@hidden Function Definition, Sample Function Definition, A Sample
+Function Definition}, for a more detailed example of a function
+definition, including the use of @code{@@example} inside the
address@hidden
+
+The other specialized commands work like @code{@@address@hidden
+
address@hidden Macros in definition commands
+Note that, due to implementation difficulties, macros are not expanded
+in @code{@@deffn} and all the other definition commands.
+
address@hidden Optional Arguments, deffnx, Def Cmd Template, Definition Commands
address@hidden Optional and Repeated Arguments
address@hidden Optional and repeated arguments
address@hidden Repeated and optional arguments
address@hidden Arguments, repeated and optional
address@hidden Syntax, optional & repeated arguments
address@hidden Meta-syntactic chars for arguments
+
+Some entities take optional or repeated arguments, which may be
+specified by a distinctive glyph that uses square brackets and
+ellipses. For @w{example}, a special form often breaks its argument list
+into separate arguments in more complicated ways than a
+straightforward address@hidden
+
address@hidden The following looks better in Info (no `r', `samp' and `code'):
+An argument enclosed within square brackets is optional.
+Thus, address@hidden means that @var{optional-arg} is optional.
+An argument followed by an ellipsis is optional
+and may be repeated more than once.
address@hidden This is consistent with Emacs Lisp Reference manual
+Thus, @address@hidden stands for zero or more arguments.
+Parentheses are used when several arguments are grouped
+into additional levels of list structure in Lisp.
+
+Here is the @code{@@defspec} line of an example of an imaginary
+special form:@refill
+
address@hidden
address@hidden foobar (@var{var} address@hidden @var{to} address@hidden)
@address@hidden
address@hidden defspec
address@hidden
+\vskip \parskip
address@hidden tex
address@hidden quotation
+
address@hidden
+In this example, the arguments @var{from} and @var{to} are optional,
+but must both be present or both absent. If they are present,
address@hidden may optionally be specified as well. These arguments are
+grouped with the argument @var{var} into a list, to distinguish them
+from @var{body}, which includes all remaining elements of the
address@hidden
+
+In a Texinfo source file, this @code{@@defspec} line is written like
+this (except it would not be split over two lines, as it is in this
+example)address@hidden
+
address@hidden
address@hidden
+@@defspec foobar (@@address@hidden@} [@@address@hidden@} @@address@hidden@}
+ [@@address@hidden@}]]) @@address@hidden@}@@address@hidden@}
address@hidden group
address@hidden example
+
address@hidden
+The function is listed in the Command and Variable Index under
address@hidden@refill
+
address@hidden deffnx, Def Cmds in Detail, Optional Arguments, Definition
Commands
address@hidden Two or More `First' Lines
address@hidden Two `First' Lines for @code{@@deffn}
address@hidden Grouping two definitions together
address@hidden Definitions grouped together
address@hidden deffnx
+
+To create two or more `first' or header lines for a definition, follow
+the first @code{@@deffn} line by a line beginning with @code{@@deffnx}.
+The @code{@@deffnx} command works exactly like @code{@@deffn}
+except that it does not generate extra vertical white space between it
+and the preceding address@hidden
+
address@hidden 1000
+For example,
+
address@hidden
address@hidden
+@@deffn @{Interactive address@hidden isearch-forward
+@@deffnx @{Interactive address@hidden isearch-backward
+These two search commands are similar except @dots{}
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden {Interactive Command} isearch-forward
address@hidden {Interactive Command} isearch-backward
+These two search commands are similar except @dots{}
address@hidden deffn
+
+Each definition command has an `x' form: @code{@@defunx},
address@hidden@@defvrx}, @code{@@deftypefunx}, etc.
+
+The `x' forms work just like @code{@@itemx}; see @ref{itemx, , @code{@@itemx}}.
+
address@hidden Def Cmds in Detail, Def Cmd Conventions, deffnx, Definition
Commands
address@hidden The Definition Commands
+
+Texinfo provides more than a dozen definition commands, all of which
+are described in this address@hidden
+
+The definition commands automatically enter the name of the entity in
+the appropriate index: for example, @code{@@deffn}, @code{@@defun},
+and @code{@@defmac} enter function names in the index of functions;
address@hidden@@defvr} and @code{@@defvar} enter variable names in the index
+of address@hidden
+
+Although the examples that follow mostly illustrate Lisp, the commands
+can be used for other programming address@hidden
+
address@hidden
+* 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.
+* Abstract Objects:: Commands for object-oriented programming.
+* Data Types:: The definition command for data types.
address@hidden menu
+
address@hidden Functions Commands, Variables Commands, Def Cmds in Detail, Def
Cmds in Detail
address@hidden Functions and Similar Entities
+
+This section describes the commands for describing functions and similar
+entities:@refill
+
address@hidden @code
address@hidden deffn
address@hidden @@deffn @var{category} @var{name} @address@hidden
+The @code{@@deffn} command is the general definition command for
+functions, interactive commands, and similar entities that may take
+arguments. You must choose a term to describe the category of entity
+being defined; for example, ``Function'' could be used if the entity is
+a function. The @code{@@deffn} command is written at the beginning of a
+line and is followed on the same line by the category of entity being
+described, the name of this particular entity, and its arguments, if
+any. Terminate the definition with @code{@@end deffn} on a line of its
address@hidden
+
address@hidden 750
+For example, here is a definition:
+
address@hidden
address@hidden
+@@deffn Command forward-char nchars
+Move point forward @@address@hidden@} characters.
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden
+This shows a rather terse definition for a ``command'' named
address@hidden with one argument, @var{nchars}.
+
address@hidden@@deffn} prints argument names such as @var{nchars} in italics or
+upper case, as if @code{@@var} had been used, because we think of these
+names as metasyntactic variables---they stand for the actual argument
+values. Within the text of the description, write an argument name
+explicitly with @code{@@var} to refer to the value of the argument. In
+the example above, we used @samp{@@address@hidden@}} in this way.
+
+The template for @code{@@deffn} is:
+
address@hidden
address@hidden
+@@deffn @var{category} @var{name} @address@hidden
address@hidden
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden defun
address@hidden @@defun @var{name} @address@hidden
+The @code{@@defun} command is the definition command for functions.
address@hidden@@defun} is equivalent to @samp{@@deffn Function
address@hidden@refill
+
address@hidden 800
address@hidden
+For example,
+
address@hidden
address@hidden
+@@defun set symbol new-value
+Change the value of the symbol @@address@hidden@}
+to @@address@hidden@}.
+@@end defun
address@hidden group
address@hidden example
+
address@hidden
+shows a rather terse definition for a function @code{set} whose
+arguments are @var{symbol} and @var{new-value}. The argument names on
+the @code{@@defun} line automatically appear in italics or upper case as
+if they were enclosed in @code{@@var}. Terminate the definition with
address@hidden@@end defun} on a line of its address@hidden
+
+The template is:
+
address@hidden
address@hidden
+@@defun @var{function-name} @address@hidden
address@hidden
+@@end defun
address@hidden group
address@hidden example
+
address@hidden@@defun} creates an entry in the index of functions.
+
address@hidden defmac
address@hidden @@defmac @var{name} @address@hidden
+The @code{@@defmac} command is the definition command for macros.
address@hidden@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and
+works like @code{@@address@hidden
+
address@hidden defspec
address@hidden @@defspec @var{name} @address@hidden
+The @code{@@defspec} command is the definition command for special
+forms. (In Lisp, a special form is an entity much like a function,
address@hidden Forms,,, elisp, GNU Emacs Lisp Reference Manual}.)
address@hidden@@defspec} is equivalent to @samp{@@deffn @{Special address@hidden
address@hidden and works like @code{@@address@hidden
address@hidden table
+
address@hidden Variables Commands, Typed Functions, Functions Commands, Def
Cmds in Detail
address@hidden Variables and Similar Entities
+
+Here are the commands for defining variables and similar
+entities:@refill
+
address@hidden @code
address@hidden defvr
address@hidden @@defvr @var{category} @var{name}
+The @code{@@defvr} command is a general definition command for
+something like a variable---an entity that records a value. You must
+choose a term to describe the category of entity being defined; for
+example, ``Variable'' could be used if the entity is a variable.
+Write the @code{@@defvr} command at the beginning of a line and
+follow it on the same line by the category of the entity and the
+name of the entity.
+
+Capitalize the category name like a title. If the name of the category
+contains spaces, as in the name ``User Option'', enclose it in braces.
+Otherwise, the second word will be mistaken for the name of the entity.
+For example,
+
address@hidden
address@hidden
+@@defvr @{User address@hidden fill-column
+This buffer-local variable specifies
+the maximum width of filled lines.
address@hidden
+@@end defvr
address@hidden group
address@hidden example
+
+Terminate the definition with @code{@@end defvr} on a line of its
address@hidden
+
+The template is:
+
address@hidden
address@hidden
+@@defvr @var{category} @var{name}
address@hidden
+@@end defvr
address@hidden group
address@hidden example
+
address@hidden@@defvr} creates an entry in the index of variables for
@var{name}.
+
address@hidden defvar
address@hidden @@defvar @var{name}
+The @code{@@defvar} command is the definition command for variables.
address@hidden@@defvar} is equivalent to @samp{@@defvr Variable
address@hidden@refill
+
address@hidden 750
+For example:
+
address@hidden
address@hidden
+@@defvar kill-ring
address@hidden
+@@end defvar
address@hidden group
address@hidden example
+
+The template is:
+
address@hidden
address@hidden
+@@defvar @var{name}
address@hidden
+@@end defvar
address@hidden group
address@hidden example
+
address@hidden@@defvar} creates an entry in the index of variables for
address@hidden@refill
+
address@hidden defopt
address@hidden @@defopt @var{name}
address@hidden User options, marking
+The @code{@@defopt} command is the definition command for @dfn{user
+options}, i.e., variables intended for users to change according to
+taste; Emacs has many such (@pxref{Variables,,, emacs, The GNU Emacs
+Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User
address@hidden @dots{}} and works like @code{@@address@hidden
address@hidden table
+
+
address@hidden Typed Functions, Typed Variables, Variables Commands, Def Cmds
in Detail
address@hidden Functions in Typed Languages
+
+The @code{@@deftypefn} command and its variations are for describing
+functions in languages in which you must declare types of variables and
+functions, such as C and C++.
+
address@hidden @code
address@hidden deftypefn
address@hidden @@deftypefn @var{category} @var{data-type} @var{name}
@address@hidden
+The @code{@@deftypefn} command is the general definition command for
+functions and similar entities that may take arguments and that are
+typed. The @code{@@deftypefn} command is written at the beginning of
+a line and is followed on the same line by the category of entity
+being described, the type of the returned value, the name of this
+particular entity, and its arguments, if address@hidden
+
address@hidden 800
address@hidden
+For example,
+
address@hidden
address@hidden
+@@deftypefn @{Library address@hidden int foobar
+ (int @@address@hidden@}, float @@address@hidden@})
address@hidden
+@@end deftypefn
address@hidden group
address@hidden example
+
address@hidden 1000
address@hidden
+(where the text before the address@hidden'', shown above as two lines, would
+actually be a single line in a real Texinfo file) produces the following
+in Info:
+
address@hidden
address@hidden
+-- Library Function: int foobar (int FOO, float BAR)
address@hidden
address@hidden group
address@hidden smallexample
+
+This means that @code{foobar} is a ``library function'' that returns an
address@hidden, and its arguments are @var{foo} (an @code{int}) and
address@hidden (a @code{float})address@hidden
+
+The argument names that you write in @code{@@deftypefn} are not subject
+to an implicit @code{@@var}---since the actual names of the arguments in
address@hidden@@deftypefn} are typically scattered among data type names and
+keywords, Texinfo cannot find them without help. Instead, you must write
address@hidden@@var} explicitly around the argument names. In the example
+above, the argument names are @samp{foo} and @address@hidden
+
+The template for @code{@@deftypefn} is:@refill
+
address@hidden
address@hidden
+@@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{}
address@hidden
+@@end deftypefn
address@hidden group
address@hidden example
+
address@hidden
+Note that if the @var{category} or @var{data type} is more than one
+word then it must be enclosed in braces to make it a single address@hidden
+
+If you are describing a procedure in a language that has packages,
+such as Ada, you might consider using @code{@@deftypefn} in a manner
+somewhat contrary to the convention described in the preceding
address@hidden
+
address@hidden 800
address@hidden
+For example:
+
address@hidden
address@hidden
+@@deftypefn stacks private push
+ (@@address@hidden@}:in out stack;
+ @@address@hidden@}:in integer)
address@hidden
+@@end deftypefn
address@hidden group
address@hidden example
+
address@hidden
+(The @code{@@deftypefn} arguments are shown split into three lines, but
+would be a single line in a real Texinfo file.)
+
+In this instance, the procedure is classified as belonging to the
+package @code{stacks} rather than classified as a `procedure' and its
+data type is described as @code{private}. (The name of the procedure
+is @code{push}, and its arguments are @var{s} and @var{n}.)@refill
+
address@hidden@@deftypefn} creates an entry in the index of functions for
address@hidden@refill
+
address@hidden @@deftypefun @var{data-type} @var{name} @address@hidden
address@hidden deftypefun
+The @code{@@deftypefun} command is the specialized definition command
+for functions in typed languages. The command is equivalent to
address@hidden@@deftypefn Function @address@hidden
+
address@hidden 800
address@hidden
+Thus,
+
address@hidden
address@hidden
+@@deftypefun int foobar (int @@address@hidden@}, float @@address@hidden@})
address@hidden
+@@end deftypefun
address@hidden group
address@hidden smallexample
+
address@hidden
+produces the following in Info:
+
address@hidden
address@hidden
+-- Function: int foobar (int FOO, float BAR)
address@hidden
address@hidden group
address@hidden example
+
address@hidden 800
+The template is:
+
address@hidden
address@hidden
+@@deftypefun @var{type} @var{name} @address@hidden
address@hidden
+@@end deftypefun
address@hidden group
address@hidden example
+
address@hidden@@deftypefun} creates an entry in the index of functions for
address@hidden@refill
+
address@hidden table
+
+
address@hidden Typed Variables, Abstract Objects, Typed Functions, Def Cmds in
Detail
address@hidden Variables in Typed Languages
+
+Variables in typed languages are handled in a manner similar to
+functions in typed languages. @xref{Typed Functions}. The general
+definition command @code{@@deftypevr} corresponds to
address@hidden@@deftypefn} and the specialized definition command
address@hidden@@deftypevar} corresponds to @code{@@address@hidden
+
address@hidden @code
address@hidden deftypevr
address@hidden @@deftypevr @var{category} @var{data-type} @var{name}
+The @code{@@deftypevr} command is the general definition command for
+something like a variable in a typed language---an entity that records
+a value. You must choose a term to describe the category of the
+entity being defined; for example, ``Variable'' could be used if the
+entity is a address@hidden
+
+The @code{@@deftypevr} command is written at the beginning of a line
+and is followed on the same line by the category of the entity
+being described, the data type, and the name of this particular
address@hidden
+
address@hidden 800
address@hidden
+For example:
+
address@hidden
address@hidden
+@@deftypevr @{Global address@hidden int enable
address@hidden
+@@end deftypevr
address@hidden group
address@hidden example
+
address@hidden
+produces the following in Info:
+
address@hidden
address@hidden
+-- Global Flag: int enable
address@hidden
address@hidden group
address@hidden example
+
address@hidden 800
+The template is:
+
address@hidden
+@@deftypevr @var{category} @var{data-type} @var{name}
address@hidden
+@@end deftypevr
address@hidden example
+
address@hidden@@deftypevr} creates an entry in the index of variables for
address@hidden@refill
+
address@hidden deftypevar
address@hidden @@deftypevar @var{data-type} @var{name}
+The @code{@@deftypevar} command is the specialized definition command
+for variables in typed languages. @code{@@deftypevar} is equivalent
+to @samp{@@deftypevr Variable @address@hidden
+
address@hidden 800
address@hidden
+For example:
+
address@hidden
address@hidden
+@@deftypevar int fubar
address@hidden
+@@end deftypevar
address@hidden group
address@hidden example
+
address@hidden
+produces the following in Info:
+
address@hidden
address@hidden
+-- Variable: int fubar
address@hidden
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+The template is:
+
address@hidden
address@hidden
+@@deftypevar @var{data-type} @var{name}
address@hidden
+@@end deftypevar
address@hidden group
address@hidden example
+
address@hidden@@deftypevar} creates an entry in the index of variables for
address@hidden@refill
address@hidden table
+
address@hidden Abstract Objects
address@hidden Object-Oriented Programming
+
+Here are the commands for formatting descriptions about abstract
+objects, such as are used in object-oriented programming. A class is
+a defined type of abstract object. An instance of a class is a
+particular object that has the type of the class. An instance
+variable is a variable that belongs to the class but for which each
+instance has its own address@hidden
+
+In a definition, if the name of a class is truly a name defined in the
+programming system for a class, then you should write an @code{@@code}
+around it. Otherwise, it is printed in the usual text address@hidden
+
address@hidden @code
address@hidden defcv
address@hidden @@defcv @var{category} @var{class} @var{name}
+The @code{@@defcv} command is the general definition command for
+variables associated with classes in object-oriented programming. The
address@hidden@@defcv} command is followed by three arguments: the category of
+thing being defined, the class to which it belongs, and its
+name. Thus,@refill
+
address@hidden
address@hidden
+@@defcv @{Class address@hidden Window border-pattern
address@hidden
+@@end defcv
address@hidden group
address@hidden example
+
address@hidden
+illustrates how you would write the first line of a definition of the
address@hidden class option of the class @address@hidden
+
+The template is:
address@hidden
address@hidden
+@@defcv @var{category} @var{class} @var{name}
address@hidden
+@@end defcv
address@hidden group
address@hidden example
+
address@hidden@@defcv} creates an entry in the index of variables.
+
address@hidden defivar
address@hidden @@defivar @var{class} @var{name}
+The @code{@@defivar} command is the definition command for instance
+variables in object-oriented programming. @code{@@defivar} is
+equivalent to @samp{@@defcv @{Instance address@hidden @address@hidden
+
+The template is:
address@hidden
address@hidden
+@@defivar @var{class} @var{instance-variable-name}
address@hidden
+@@end defivar
address@hidden group
address@hidden example
+
address@hidden@@defivar} creates an entry in the index of variables.
+
address@hidden deftypeivar
address@hidden @@deftypeivar @var{class} @var{data-type} @var{name}
+The @code{@@deftypeivar} command is the definition command for typed
+instance variables in object-oriented programming. It is similar to
address@hidden@@defivar} with the addition of the @var{data-type} parameter to
+specify the type of the instance variable. @code{@@deftypeivar} creates an
+entry in the index of variables.
+
address@hidden defop
address@hidden @@defop @var{category} @var{class} @var{name} @address@hidden
+The @code{@@defop} command is the general definition command for
+entities that may resemble methods in object-oriented programming.
+These entities take arguments, as functions do, but are associated with
+particular classes of address@hidden
+
+For example, some systems have constructs called @dfn{wrappers} that
+are associated with classes as methods are, but that act more like
+macros than like functions. You could use @code{@@defop Wrapper} to
+describe one of address@hidden
+
+Sometimes it is useful to distinguish methods and @dfn{operations}.
+You can think of an operation as the specification for a method.
+Thus, a window system might specify that all window classes have a
+method named @code{expose}; we would say that this window system
+defines an @code{expose} operation on windows in general. Typically,
+the operation has a name and also specifies the pattern of arguments;
+all methods that implement the operation must accept the same
+arguments, since applications that use the operation do so without
+knowing which method will implement address@hidden
+
+Often it makes more sense to document operations than methods. For
+example, window application developers need to know about the
address@hidden operation, but need not be concerned with whether a
+given class of windows has its own method to implement this operation.
+To describe this operation, you would write:@refill
+
address@hidden
+@@defop Operation windows expose
address@hidden example
+
+The @code{@@defop} command is written at the beginning of a line and
+is followed on the same line by the overall name of the category of
+operation, the name of the class of the operation, the name of the
+operation, and its arguments, if address@hidden
+
+The template is:
address@hidden
address@hidden
+@@defop @var{category} @var{class} @var{name} @address@hidden
address@hidden
+@@end defop
address@hidden group
address@hidden example
+
address@hidden@@defop} creates an entry, such as address@hidden on
address@hidden', in the index of address@hidden
+
address@hidden deftypeop
address@hidden @@deftypeop @var{category} @var{class} @var{data-type}
@var{name} @address@hidden
+The @code{@@deftypeop} command is the definition command for typed
+operations in object-oriented programming. It is similar to
address@hidden@@defop} with the addition of the @var{data-type} parameter to
+specify the return type of the method. @code{@@deftypeop} creates an
+entry in the index of functions.
+
address@hidden @@defmethod @var{class} @var{name} @address@hidden
address@hidden defmethod
+The @code{@@defmethod} command is the definition command for methods
+in object-oriented programming. A method is a kind of function that
+implements an operation for a particular class of objects and its
+subclasses.
+
address@hidden@@defmethod} is equivalent to @samp{@@defop Method @dots{}}.
+The command is written at the beginning of a line and is followed by
+the name of the class of the method, the name of the method, and its
+arguments, if address@hidden
+
address@hidden
+For example:
address@hidden
address@hidden
+@@defmethod @code{bar-class} bar-method argument
address@hidden
+@@end defmethod
address@hidden group
address@hidden example
+
address@hidden
+illustrates the definition for a method called @code{bar-method} of
+the class @code{bar-class}. The method takes an address@hidden
+
+The template is:
+
address@hidden
address@hidden
+@@defmethod @var{class} @var{method-name} @address@hidden
address@hidden
+@@end defmethod
address@hidden group
address@hidden example
+
address@hidden@@defmethod} creates an entry, such as address@hidden on
address@hidden', in the index of address@hidden
+
+
address@hidden @@deftypemethod @var{class} @var{data-type} @var{name}
@address@hidden
address@hidden defmethod
+The @code{@@deftypemethod} command is the definition command for methods
+in object-oriented typed languages, such as C++ and Java. It is similar
+to the @code{@@defmethod} command with the addition of the
address@hidden parameter to specify the return type of the method.
+
address@hidden table
+
+
address@hidden Data Types
address@hidden Data Types
+
+Here is the command for data types:@refill
+
address@hidden @code
address@hidden deftp
address@hidden @@deftp @var{category} @var{name} @address@hidden
+The @code{@@deftp} command is the generic definition command for data
+types. The command is written at the beginning of a line and is
+followed on the same line by the category, by the name of the type
+(which is a word like @code{int} or @code{float}), and then by names of
+attributes of objects of that type. Thus, you could use this command
+for describing @code{int} or @code{float}, in which case you could use
address@hidden type} as the category. (A data type is a category of
+certain objects for purposes of deciding which operations can be
+performed on them.)@refill
+
+In Lisp, for example, @dfn{pair} names a particular data
+type, and an object of that type has two slots called the
address@hidden and the @sc{cdr}. Here is how you would write the first line
+of a definition of @address@hidden
+
address@hidden
address@hidden
+@@deftp @{Data address@hidden pair car cdr
address@hidden
+@@end deftp
address@hidden group
address@hidden example
+
address@hidden 950
+The template is:
+
address@hidden
address@hidden
+@@deftp @var{category} @var{name-of-type} @address@hidden
address@hidden
+@@end deftp
address@hidden group
address@hidden example
+
address@hidden@@deftp} creates an entry in the index of data types.
address@hidden table
+
address@hidden Def Cmd Conventions, Sample Function Definition, Def Cmds in
Detail, Definition Commands
address@hidden Conventions for Writing Definitions
address@hidden Definition conventions
address@hidden Conventions for writing definitions
+
+When you write a definition using @code{@@deffn}, @code{@@defun}, or
+one of the other definition commands, please take care to use
+arguments that indicate the meaning, as with the @var{count} argument
+to the @code{forward-word} function. Also, if the name of an argument
+contains the name of a type, such as @var{integer}, take care that the
+argument actually is of that address@hidden
+
address@hidden Sample Function Definition, , Def Cmd Conventions, Definition
Commands
address@hidden A Sample Function Definition
address@hidden Function definitions
address@hidden Command definitions
address@hidden Macro definitions
address@hidden Sample function definition
+
+A function definition uses the @code{@@defun} and @code{@@end defun}
+commands. The name of the function follows immediately after the
address@hidden@@defun} command and it is followed, on the same line, by the
+parameter address@hidden
+
+Here is a definition from @ref{Calling Functions,,, elisp, The GNU Emacs
+Lisp Reference Manual}.
+
address@hidden
address@hidden apply function &rest arguments
address@hidden calls @var{function} with @var{arguments}, just
+like @code{funcall} but with one difference: the last of
address@hidden is a list of arguments to give to
address@hidden, rather than a single argument. We also say
+that this list is @dfn{appended} to the other arguments.
+
address@hidden returns the result of calling @var{function}.
+As with @code{funcall}, @var{function} must either be a Lisp
+function or a primitive function; special forms and macros
+do not make sense in @code{apply}.
+
address@hidden
+(setq f 'list)
+ @result{} list
+(apply f 'x 'y 'z)
address@hidden Wrong type argument: listp, z
+(apply '+ 1 2 '(3 4))
+ @result{} 10
+(apply '+ '(1 2 3 4))
+ @result{} 10
+
+(apply 'append '((a b c) nil (x y z) nil))
+ @result{} (a b c x y z)
address@hidden example
+
+An interesting example of using @code{apply} is found in the description
+of @address@hidden
address@hidden defun
address@hidden quotation
+
address@hidden 1200
+In the Texinfo source file, this example looks like this:
+
address@hidden
address@hidden
+@@defun apply function &rest arguments
+@@address@hidden@} calls @@address@hidden@} with
+@@address@hidden@}, just like @@address@hidden@} but with one
+difference: the last of @@address@hidden@} is a list of
+arguments to give to @@address@hidden@}, rather than a single
+argument. We also say that this list is @@address@hidden@}
+to the other arguments.
address@hidden group
+
address@hidden
+@@address@hidden@} returns the result of calling
+@@address@hidden@}. As with @@address@hidden@},
+@@address@hidden@} must either be a Lisp function or a
+primitive function; special forms and macros do not make
+sense in @@address@hidden@}.
address@hidden group
+
address@hidden
+@@example
+(setq f 'list)
+ @@address@hidden@} list
+(apply f 'x 'y 'z)
+@@address@hidden@} Wrong type argument: listp, z
+(apply '+ 1 2 '(3 4))
+ @@address@hidden@} 10
+(apply '+ '(1 2 3 4))
+ @@address@hidden@} 10
+
+(apply 'append '((a b c) nil (x y z) nil))
+ @@address@hidden@} (a b c x y z)
+@@end example
address@hidden group
+
address@hidden
+An interesting example of using @@address@hidden@} is found
+in the description of @@address@hidden@}.
+@@end defun
address@hidden group
address@hidden example
+
address@hidden
+In this manual, this function is listed in the Command and Variable
+Index under @address@hidden
+
+Ordinary variables and user options are described using a format like
+that for functions except that variables do not take arguments.
+
+
address@hidden Conditionals
address@hidden Conditionally Visible Text
address@hidden Conditionally visible text
address@hidden Text, conditionally visible
address@hidden Visibility of conditional text
address@hidden If text conditionally visible
+
+Sometimes it is good to use different text for different output formats.
+For example, you can use the @dfn{conditional commands} to specify
+different text for the printed manual and the Info output.
+
+Conditional commands may not be nested.
+
+The conditional commands comprise the following categories.
+
address@hidden @bullet
address@hidden Commands for HTML, Info, or @TeX{}.
address@hidden Commands for not HTML, Info, or @TeX{}.
address@hidden Raw @TeX{} or HTML commands.
address@hidden
+Substituting text for all formats, and testing if a flag is set or clear.
address@hidden itemize
+
address@hidden
+* Conditional Commands:: Specifying text for HTML, Info, or @TeX{}.
+* Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}.
+* Raw Formatter Commands:: Using raw @TeX{} or HTML commands.
+* set clear value:: Designating which text to format (for
+ all output formats); and how to set a
+ flag to a string that you can insert.
address@hidden menu
+
+
address@hidden Conditional Commands
address@hidden Conditional Commands
+
+Texinfo has a pair of commands for each output format, to allow
+conditional inclusion of text for a particular output format.
+
address@hidden ifinfo
address@hidden@@ifinfo} begins segments of text that should be ignored by @TeX{}
+when it typesets the printed manual. The segment of text appears only
+in the Info file and (for historical compatibility) the plain text
+output. The @code{@@ifinfo} command should appear on a line by itself;
+end the Info-only text with a line containing @code{@@end ifinfo} by
+itself.
+
address@hidden iftex
address@hidden ifhtml
address@hidden ifplaintext
+The @code{@@iftex} and @code{@@end iftex} commands are analogous to the
address@hidden@@ifinfo} and @code{@@end ifinfo} commands; they specify text that
+will appear in the printed manual but not in the Info file. Likewise
+for @code{@@ifhtml} and @code{@@end ifhtml}, which specify text to
+appear only in HTML output. And for @code{@@ifplaintext} and
address@hidden@@end ifplaintext}, which specify text to appear only in plain
+text output.
+
+For example,
+
address@hidden
+@@iftex
+This text will appear only in the printed manual.
+@@end iftex
+@@ifinfo
+However, this text will appear only in Info (or plain text).
+@@end ifinfo
+@@ifhtml
+And this text will only appear in HTML.
+@@end ifhtml
+@@ifplaintext
+Whereas this text will only appear in plain text.
+@@end ifplaintext
address@hidden example
+
address@hidden
+The preceding example produces the following line:
+However, this text will appear only in Info (or plain text).
+And this text will only appear in HTML.
+
address@hidden
+Notice that you only see one of the input lines, depending on which
+version of the manual you are reading.
+
+
address@hidden Conditional Not Commands
address@hidden Conditional Not Commands
address@hidden ifnothtml
address@hidden ifnotinfo
address@hidden ifnotplaintext
address@hidden ifnottex
+
+You can specify text to be included in any output format @emph{other}
+than some given one with the @code{@@address@hidden commands:
address@hidden
+@@ifnothtml @dots{} @@end ifnothtml
+@@ifnotinfo @dots{} @@end ifnotinfo
+@@ifnotplaintext @dots{} @@end ifnotplaintext
+@@ifnottex @dots{} @@end ifnottex
address@hidden example
address@hidden
+(The @code{@@address@hidden command and the @code{@@end} command must
+appear on lines by themselves in your actual source file.)
+
+If the output file is @emph{not} being made for the given format, the
+region is included. Otherwise, it is ignored.
+
+With one exception (for historical compatibility): @code{@@ifnotinfo}
+text is omitted for both Info and plain text output, not just Info. To
+specify text which appears only in Info and not in plain text, use
address@hidden@@ifnotplaintext}, like this:
address@hidden
+This will be in Info, but not plain text.
address@hidden example
+
+The regions delimited by these commands are ordinary Texinfo source as
+with @code{@@iftex}, not raw formatter source as with @code{@@tex}
+(@pxref{Raw Formatter Commands}).
+
+
address@hidden Raw Formatter Commands
address@hidden Raw Formatter Commands
address@hidden @TeX{} commands, using ordinary
address@hidden HTML commands, using ordinary
address@hidden Raw formatter commands
address@hidden Ordinary @TeX{} commands, using
address@hidden Ordinary HTML commands, using
address@hidden Commands using raw @TeX{}
address@hidden Commands using raw HTML
address@hidden plain @TeX{}
+
+Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, you
+can embed some raw @TeX{} commands. Info will ignore these commands
+since they are only in that part of the file which is seen by @TeX{}.
+You can write the @TeX{} commands as you would write them in a normal
address@hidden file, except that you must replace the @samp{\} used by @TeX{}
+with an @samp{@@}. For example, in the @code{@@titlepage} section of a
+Texinfo file, you can use the @TeX{} command @code{@@vskip} to format
+the copyright page. (The @code{@@titlepage} command causes Info to
+ignore the region automatically, as it does with the @code{@@iftex}
+command.)
+
+However, many features of plain @TeX{} will not work, as they are
+overridden by Texinfo features.
+
address@hidden tex
+You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{}
+commands, by delineating a region with the @code{@@tex} and @code{@@end
+tex} commands. (The @code{@@tex} command also causes Info to ignore the
+region, like the @code{@@iftex} command.) The sole exception is that the
address@hidden@@} character still introduces a command, so that @code{@@end tex}
+can be recognized properly.
+
address@hidden Mathematical expressions
+For example, here is a mathematical expression written in
+plain @TeX{}:
+
address@hidden
+@@tex
+$$ \chi^2 = address@hidden@}^N
+ \left (y_i - (a + b x_i)
+ \over \sigma_i\right)^2 $$
+@@end tex
address@hidden example
+
address@hidden
+The output of this example will appear only in a printed manual. If
+you are reading this in Info, you will not see the equation that appears
+in the printed manual.
+
address@hidden
+$$ \chi^2 = \sum_{i=1}^N
+ \left(y_i - (a + b x_i)
+ \over \sigma_i\right)^2 $$
address@hidden tex
+
address@hidden ifhtml
address@hidden html
+Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to delimit
+a region to be included in HTML output only, and @code{@@html @dots{}
+@@end html} for a region of raw HTML (again, except that @code{@@} is
+still the escape character, so the @code{@@end} command can be
+recognized.)
+
+
address@hidden set clear value
address@hidden @code{@@set}, @code{@@clear}, and @code{@@value}
+
+You can direct the Texinfo formatting commands to format or ignore parts
+of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset},
+and @code{@@ifclear} address@hidden
+
+Brief descriptions:
+
address@hidden @code
address@hidden @@set @var{flag} address@hidden
+Set the variable @var{flag}, to the optional @var{value} if specifed.
+
address@hidden @@clear @var{flag}
+Undefine the variable @var{flag}, whether or not it was previously defined.
+
address@hidden @@ifset @var{flag}
+If @var{flag} is set, text through the next @code{@@end ifset} command
+is formatted. If @var{flag} is clear, text through the following
address@hidden@@end ifset} command is ignored.
+
address@hidden @@ifclear @var{flag}
+If @var{flag} is set, text through the next @code{@@end ifclear} command
+is ignored. If @var{flag} is clear, text through the following
address@hidden@@end ifclear} command is formatted.
address@hidden table
+
address@hidden
+* set value:: Expand a flag variable to a string.
+* ifset ifclear:: Format a region if a flag is set.
+* value Example:: An easy way to update edition information.
address@hidden menu
+
+
address@hidden set value
address@hidden @code{@@set} and @code{@@value}
address@hidden value
+
+You use the @code{@@set} command to specify a value for a flag, which is
+later expanded by the @code{@@value} command.
+
+A @dfn{flag} is an identifier. In general, it is best to use only
+letters and numerals in a flag name, not @samp{-} or @samp{_}---they
+will work in some contexts, but not all, due to limitations in @TeX{}.
+
+The value is the remainder of the input line, and can contain anything.
+
+Write the @code{@@set} command like this:
+
address@hidden
+@@set foo This is a string.
address@hidden example
+
address@hidden
+This sets the value of the flag @code{foo} to ``This is a string.''.
+
+The Texinfo formatters then replace an @code{@@address@hidden@address@hidden
+command with the string to which @var{flag} is set. Thus, when
address@hidden is set as shown above, the Texinfo formatters convert this:
+
address@hidden
address@hidden
+@@address@hidden@}
address@hidden @r{to this:}
+This is a string.
address@hidden group
address@hidden example
+
+You can write an @code{@@value} command within a paragraph; but you
+must write an @code{@@set} command on a line of its own.
+
+If you write the @code{@@set} command like this:
+
address@hidden
+@@set foo
address@hidden example
+
address@hidden
+without specifying a string, the value of @code{foo} is the empty string.
+
+If you clear a previously set flag with @code{@@clear @var{flag}}, a
+subsequent @code{@@address@hidden@}} command will report an error.
+
+For example, if you set @code{foo} as follows:@refill
+
address@hidden
+@@set how-much very, very, very
address@hidden example
+
address@hidden
+then the formatters transform
+
address@hidden
address@hidden
+It is a @@address@hidden@} wet day.
address@hidden @r{into}
+It is a very, very, very wet day.
address@hidden group
address@hidden example
+
+If you write
+
address@hidden
+@@clear how-much
address@hidden example
+
address@hidden
+then the formatters transform
+
address@hidden
address@hidden
+It is a @@address@hidden@} wet day.
address@hidden @r{into}
+It is a @{No value for "how-much"@} wet day.
address@hidden group
address@hidden example
+
+
address@hidden ifset ifclear
address@hidden @code{@@ifset} and @code{@@ifclear}
+
address@hidden ifset
+When a @var{flag} is set, the Texinfo formatting commands format text
+between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end
+ifset} commands. When the @var{flag} is cleared, the Texinfo formatting
+commands do @emph{not} format the text. @code{@@ifclear} operates
+analogously.
+
+Write the conditionally formatted text between @code{@@ifset @var{flag}}
+and @code{@@end ifset} commands, like this:
+
address@hidden
address@hidden
+@@ifset @var{flag}
address@hidden
+@@end ifset
address@hidden group
address@hidden example
+
+For example, you can create one document that has two variants, such as
+a manual for a `large' and `small' model:
+
address@hidden shrubbery
address@hidden
+You can use this machine to dig up shrubs
+without hurting them.
+
+@@set large
+
+@@ifset large
+It can also dig up fully grown trees.
+@@end ifset
+
+Remember to replant promptly @dots{}
address@hidden example
+
address@hidden
+In the example, the formatting commands will format the text between
address@hidden@@ifset large} and @code{@@end ifset} because the @code{large}
+flag is set.
+
+When @var{flag} is cleared, the Texinfo formatting commands do
address@hidden format the text between @code{@@ifset @var{flag}} and
address@hidden@@end ifset}; that text is ignored and does not appear in either
+printed or Info output.
+
+For example, if you clear the flag of the preceding example by writing
+an @code{@@clear large} command after the @code{@@set large} command
+(but before the conditional text), then the Texinfo formatting commands
+ignore the text between the @code{@@ifset large} and @code{@@end ifset}
+commands. In the formatted output, that text does not appear; in both
+printed and Info output, you see only the lines that say, ``You can use
+this machine to dig up shrubs without hurting them. Remember to replant
+promptly @dots{}''.
+
address@hidden ifclear
+If a flag is cleared with an @code{@@clear @var{flag}} command, then
+the formatting commands format text between subsequent pairs of
address@hidden@@ifclear} and @code{@@end ifclear} commands. But if the flag
+is set with @code{@@set @var{flag}}, then the formatting commands do
address@hidden format text between an @code{@@ifclear} and an @code{@@end
+ifclear} command; rather, they ignore that text. An @code{@@ifclear}
+command looks like this:
+
address@hidden
+@@ifclear @var{flag}
address@hidden example
+
+
address@hidden value Example
address@hidden @code{@@value} Example
+
+You can use the @code{@@value} command to minimize the number of places
+you need to change when you record an update to a manual. @xref{GNU
+Sample Texts}, for an example of this same principle can work with
+Automake distributions, and full texts.
+
+Here is an example adapted from @ref{Top,, Overview, make, The GNU Make
+Manual}):
+
address@hidden
address@hidden
+Set the flags:
+
address@hidden
address@hidden
+@@set EDITION 0.35 Beta
+@@set VERSION 3.63 Beta
+@@set UPDATED 14 August 1992
+@@set UPDATE-MONTH August 1992
address@hidden group
address@hidden example
+
address@hidden
+Write text for the @code{@@copying} section (@pxref{copying}):
+
address@hidden
address@hidden
+@@copying
+This is Edition @@address@hidden@},
+last updated @@address@hidden@},
+of @@address@hidden GNU Make address@hidden,
+for @@address@hidden@}, version @@address@hidden@}.
+
+Copyright @dots{}
+
+Permission is granted @dots{}
+@@end copying
address@hidden group
address@hidden example
+
address@hidden
+Write text for the title page, for people reading the printed manual:
+
address@hidden
address@hidden
+@@titlepage
+@@title GNU Make
+@@subtitle A Program for Directing Recompilation
+@@subtitle Edition @@address@hidden@}, @dots{}
+@@subtitle @@address@hidden@}
+@@page
+@@insertcopying
address@hidden
+@@end titlepage
address@hidden group
address@hidden example
+
address@hidden
+(On a printed cover, a date listing the month and the year looks less
+fussy than a date listing the day as well as the month and year.)
+
address@hidden
+Write text for the Top node, for people reading the Info file:
+
address@hidden
address@hidden
+@@ifnottex
+@@node Top
+@@top Make
+
+@@insertcopying
address@hidden
+@@end ifnottex
address@hidden group
address@hidden example
+
+After you format the manual, the @code{@@value} constructs have been
+expanded, so the output contains text like this:
+
address@hidden
address@hidden
+This is Edition 0.35 Beta, last updated 14 August 1992,
+of `The GNU Make Manual', for `make', Version 3.63 Beta.
address@hidden group
address@hidden example
address@hidden enumerate
+
+When you update the manual, you change only the values of the flags; you
+do not need to edit the three sections.
+
+
address@hidden Internationalization
address@hidden Internationalization
+
address@hidden Internationalization
+Texinfo has some support for writing in languages other than English,
+although this area still needs considerable work.
+
+For a list of the various accented and special characters Texinfo
+supports, see @ref{Inserting Accents}.
+
address@hidden
+* documentlanguage:: Declaring the current language.
+* documentencoding:: Declaring the input encoding.
address@hidden menu
+
+
address@hidden documentlanguage
address@hidden @code{@@documentlanguage @var{cc}}: Set the Document Language
+
address@hidden documentlanguage
address@hidden Language, declaring
address@hidden Document language, declaring
+
+The @code{@@documentlanguage} command declares the current document
+language. Write it on a line by itself, with a two-letter ISO-639
+language code following (list is included below). If you have a
+multilingual document, the intent is to be able to use this command
+multiple times, to declare each language change. If the command is not
+used at all, the default is @code{en} for English.
+
address@hidden @address@hidden
+At present, this command is ignored in Info and HTML output. For
address@hidden, it causes the file @address@hidden to be read (if it
+exists). Such a file appropriately redefines the various English words
+used in @TeX{} output, such as `Chapter', `See', and so on.
+
address@hidden Hyphenation patterns, language-dependent
+It would be good if this command also changed @TeX{}'s ideas of the
+current hyphenation patterns (via the @TeX{} primitive
address@hidden), but this is unfortunately not currently implemented.
+
address@hidden ISO 639 codes
address@hidden Language codes
+Hereare the valid language codes, from ISO-639.
+
address@hidden @columnfractions .07 .26 .07 .26 .07 .26
address@hidden
address@hidden @tab Afar @tab
address@hidden @tab Abkhazian @tab
address@hidden @tab Afrikaans
address@hidden
address@hidden @tab Amharic @tab
address@hidden @tab Arabic @tab
address@hidden @tab Assamese
address@hidden
address@hidden @tab Aymara @tab
address@hidden @tab Azerbaijani @tab
address@hidden @tab Bashkir
address@hidden
address@hidden @tab Byelorussian @tab
address@hidden @tab Bulgarian @tab
address@hidden @tab Bihari
address@hidden
address@hidden @tab Bislama @tab
address@hidden @tab Bengali; Bangla @tab
address@hidden @tab Tibetan
address@hidden
address@hidden @tab Breton @tab
address@hidden @tab Catalan @tab
address@hidden @tab Corsican
address@hidden
address@hidden @tab Czech @tab
address@hidden @tab Welsh @tab
address@hidden @tab Danish
address@hidden
address@hidden @tab German @tab
address@hidden @tab Bhutani @tab
address@hidden @tab Greek
address@hidden
address@hidden @tab English @tab
address@hidden @tab Esperanto @tab
address@hidden @tab Spanish
address@hidden
address@hidden @tab Estonian @tab
address@hidden @tab Basque @tab
address@hidden @tab Persian
address@hidden
address@hidden @tab Finnish @tab
address@hidden @tab Fiji @tab
address@hidden @tab Faroese
address@hidden
address@hidden @tab French @tab
address@hidden @tab Frisian @tab
address@hidden @tab Irish
address@hidden
address@hidden @tab Scots Gaelic @tab
address@hidden @tab Galician @tab
address@hidden @tab Guarani
address@hidden
address@hidden @tab Gujarati @tab
address@hidden @tab Hausa @tab
address@hidden @tab Hebrew
address@hidden
address@hidden @tab Hindi @tab
address@hidden @tab Croatian @tab
address@hidden @tab Hungarian
address@hidden
address@hidden @tab Armenian @tab
address@hidden @tab Interlingua @tab
address@hidden @tab Indonesian
address@hidden
address@hidden @tab Interlingue @tab
address@hidden @tab Inupiak @tab
address@hidden @tab Icelandic
address@hidden
address@hidden @tab Italian @tab
address@hidden @tab Inuktitut @tab
address@hidden @tab Japanese
address@hidden
address@hidden @tab Javanese @tab
address@hidden @tab Georgian @tab
address@hidden @tab Kazakh
address@hidden
address@hidden @tab Greenlandic @tab
address@hidden @tab Cambodian @tab
address@hidden @tab Kannada
address@hidden
address@hidden @tab Kashmiri @tab
address@hidden @tab Korean @tab
address@hidden @tab Kurdish
address@hidden
address@hidden @tab Kirghiz @tab
address@hidden @tab Latin @tab
address@hidden @tab Lingala
address@hidden
address@hidden @tab Lithuanian @tab
address@hidden @tab Laothian @tab
address@hidden @tab Latvian, Lettish
address@hidden
address@hidden @tab Malagasy @tab
address@hidden @tab Maori @tab
address@hidden @tab Macedonian
address@hidden
address@hidden @tab Malayalam @tab
address@hidden @tab Mongolian @tab
address@hidden @tab Moldavian
address@hidden
address@hidden @tab Marathi @tab
address@hidden @tab Malay @tab
address@hidden @tab Maltese
address@hidden
address@hidden @tab Burmese @tab
address@hidden @tab Nauru @tab
address@hidden @tab Nepali
address@hidden
address@hidden @tab Dutch @tab
address@hidden @tab Norwegian @tab
address@hidden @tab Occitan
address@hidden
address@hidden @tab (Afan) Oromo @tab
address@hidden @tab Oriya @tab
address@hidden @tab Punjabi
address@hidden
address@hidden @tab Polish @tab
address@hidden @tab Pashto, Pushto @tab
address@hidden @tab Portuguese
address@hidden
address@hidden @tab Quechua @tab
address@hidden @tab Rhaeto-Romance @tab
address@hidden @tab Kirundi
address@hidden
address@hidden @tab Romanian @tab
address@hidden @tab Russian @tab
address@hidden @tab Kinyarwanda
address@hidden
address@hidden @tab Sanskrit @tab
address@hidden @tab Sindhi @tab
address@hidden @tab Sangro
address@hidden
address@hidden @tab Serbo-Croatian @tab
address@hidden @tab Sinhalese @tab
address@hidden @tab Slovak
address@hidden
address@hidden @tab Slovenian @tab
address@hidden @tab Samoan @tab
address@hidden @tab Shona
address@hidden
address@hidden @tab Somali @tab
address@hidden @tab Albanian @tab
address@hidden @tab Serbian
address@hidden
address@hidden @tab Siswati @tab
address@hidden @tab Sesotho @tab
address@hidden @tab Sundanese
address@hidden
address@hidden @tab Swedish @tab
address@hidden @tab Swahili @tab
address@hidden @tab Tamil
address@hidden
address@hidden @tab Telugu @tab
address@hidden @tab Tajik @tab
address@hidden @tab Thai
address@hidden
address@hidden @tab Tigrinya @tab
address@hidden @tab Turkmen @tab
address@hidden @tab Tagalog
address@hidden
address@hidden @tab Setswana @tab
address@hidden @tab Tonga @tab
address@hidden @tab Turkish
address@hidden
address@hidden @tab Tsonga @tab
address@hidden @tab Tatar @tab
address@hidden @tab Twi
address@hidden
address@hidden @tab Uighur @tab
address@hidden @tab Ukrainian @tab
address@hidden @tab Urdu
address@hidden
address@hidden @tab Uzbek @tab
address@hidden @tab Vietnamese @tab
address@hidden @tab Volapuk
address@hidden
address@hidden @tab Wolof @tab
address@hidden @tab Xhosa @tab
address@hidden @tab Yiddish
address@hidden
address@hidden @tab Yoruba @tab
address@hidden @tab Zhuang @tab
address@hidden @tab Chinese
address@hidden
address@hidden @tab Zulu
address@hidden multitable
+
+
address@hidden documentencoding
address@hidden @code{@@documentencoding @var{enc}}: Set Input Encoding
+
address@hidden documentencoding
address@hidden Encoding, declaring
address@hidden Input encoding, declaring
address@hidden Document input encoding
+
+The @code{@@documentencoding} command declares the input document
+encoding. Write it on a line by itself, with a valid encoding
+specification following, such as @samp{ISO-8859-1}.
+
address@hidden http-equiv, and charset
address@hidden meta HTML tag, and charset
+At present, this is used only in HTML output from @code{makeinfo}. If a
+document encoding @var{enc} is specified, it is used in a
address@hidden<meta>} tag included in the @samp{<head>} of the output:
+
address@hidden
+<meta http-equiv="Content-Type" content="text/html;
+ address@hidden">
address@hidden example
+
+
address@hidden Defining New Texinfo Commands
address@hidden Defining New Texinfo Commands
address@hidden Macros
address@hidden Defining new Texinfo commands
address@hidden New Texinfo commands, defining
address@hidden Texinfo commands, defining new
address@hidden User-defined Texinfo commands
+
+Texinfo provides several ways to define new commands:
+
address@hidden @bullet
address@hidden
+A Texinfo @dfn{macro} allows you to define a new Texinfo command as any
+sequence of text and/or existing commands (including other macros). The
+macro can have any number of @dfn{parameters}---text you supply each
+time you use the macro.
+
+Incidentally, these macros have nothing to do with the @code{@@defmac}
+command, which is for documenting macros in the subject of the manual
+(@pxref{Def Cmd Template}).
+
address@hidden
address@hidden@@alias} is a convenient way to define a new name for an existing
+command.
+
address@hidden
address@hidden@@definfoenclose} allows you to define new commands with
+customized output in the Info file.
+
address@hidden itemize
+
address@hidden
+* Defining Macros:: Defining and undefining new commands.
+* Invoking Macros:: Using a macro, once you've defined it.
+* Macro Details:: Beyond basic macro usage.
+* alias:: Command aliases.
+* definfoenclose:: Customized highlighting.
address@hidden menu
+
+
address@hidden Defining Macros
address@hidden Defining Macros
address@hidden Defining macros
address@hidden Macro definitions
+
address@hidden macro
+You use the Texinfo @code{@@macro} command to define a macro, like this:
+
address@hidden
+@@macro @address@hidden@var{param1}, @var{param2}, @address@hidden
address@hidden @dots{} address@hidden @dots{}
+@@end macro
address@hidden example
+
+The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to
+arguments supplied when the macro is subsequently used in the document
+(described in the next section).
+
+For a macro to work with @TeX{}, @var{macroname} must consist entirely
+of letters: no digits, hyphens, underscores, or other special characters.
+
+If a macro needs no parameters, you can define it either with an empty
+list (@samp{@@macro foo @address@hidden) or with no braces at all
(@samp{@@macro
+foo}).
+
address@hidden Body of a macro
address@hidden Mutually recursive macros
address@hidden Recursion, mutual
+The definition or @dfn{body} of the macro can contain most Texinfo
+commands, including previously-defined macros. Not-yet-defined macro
+invocations are not allowed; thus, it is not possible to have mutually
+recursive Texinfo macros. Also, a macro definition that defines another
+macro does not work in @TeX{} due to limitations in the design of
address@hidden@@macro}.
+
address@hidden Parameters to macros
+In the macro body, instances of a parameter name surrounded by
+backslashes, as in @address@hidden in the example above, are
+replaced by the corresponding argument from the macro invocation. You
+can use parameter names any number of times in the body, including zero.
+
address@hidden Backslash in macros
+To get a single @samp{\} in the macro expansion, use @samp{\\}. Any
+other use of @samp{\} in the body yields a warning.
+
address@hidden Spaces in macros
address@hidden Whitespace in macros
+The newlines after the @code{@@macro} line and before the @code{@@end
+macro} line are ignored, that is, not included in the macro body. All
+other whitespace is treated according to the usual Texinfo rules.
+
address@hidden Recursive macro invocations
address@hidden rmacro
+To allow a macro to be used recursively, that is, in an argument to a
+call to itself, you must define it with @samp{@@rmacro}, like this:
+
address@hidden
+@@rmacro rmac @address@hidden
+a\arg\b
+@@end rmacro
address@hidden
+@@address@hidden@@address@hidden@address@hidden
address@hidden example
+
+This produces the output `a1atextb2b'. With @samp{@@macro} instead of
address@hidden@@rmacro}, an error message is given.
+
address@hidden unmacro
address@hidden Macros, undefining
address@hidden Undefining macros
+You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}.
+It is not an error to undefine a macro that is already undefined.
+For example:
+
address@hidden
+@@unmacro foo
address@hidden example
+
+
address@hidden Invoking Macros
address@hidden Invoking Macros
address@hidden Invoking macros
address@hidden Expanding macros
address@hidden Running macros
address@hidden Macro invocation
+
+After a macro is defined (see the previous section), you can use
+(@dfn{invoke}) it in your document like this:
+
address@hidden
+@@@var{macroname} @address@hidden, @var{arg2}, @address@hidden
address@hidden example
+
address@hidden and the result will be just as if you typed the body of
address@hidden at that spot. For example:
+
address@hidden
+@@macro foo @{p, address@hidden
+Together: \p\ & \q\.
+@@end macro
+@@address@hidden, address@hidden
address@hidden example
+
address@hidden produces:
+
address@hidden
+Together: a & b.
address@hidden display
+
address@hidden Backslash, and macros
+Thus, the arguments and parameters are separated by commas and delimited
+by braces; any whitespace after (but not before) a comma is ignored.
+The braces are required in the invocation (but not the definition), even
+when the macro takes no arguments, consistent with all other Texinfo
+commands. For example:
+
address@hidden
+@@macro argless @address@hidden
+No arguments here.
+@@end macro
+@@address@hidden@}
address@hidden example
+
address@hidden produces:
+
address@hidden
+No arguments here.
address@hidden display
+
address@hidden Comma, in macro arguments
address@hidden Braces, in macro arguments
+To insert a comma, brace, or backslash in an argument, prepend a
+backslash, as in
+
address@hidden
+@@@var{macname} @address@hidden@}\,@}
address@hidden example
+
address@hidden
+which will pass the (almost certainly error-producing) argument
address@hidden@address@hidden,} to @var{macname}. However, commas in
parameters, even
+if escaped by a backslash, might cause trouble in @TeX{}.
+
+If the macro is defined to take a single argument, and is invoked
+without any braces, the entire rest of the line after the macro name is
+supplied as the argument. For example:
+
address@hidden
+@@macro bar @address@hidden
+Twice: \p\ & \p\.
+@@end macro
+@@bar aah
address@hidden example
+
address@hidden produces:
+
address@hidden Sorry for cheating, but let's not require macros to process the
manual.
address@hidden
+Twice: aah & aah.
address@hidden display
+
+If the macro is defined to take a single argument, and is invoked with
+braces, the braced text is passed as the argument, regardless of
+commas. For example:
+
address@hidden
+@@macro bar @address@hidden
+Twice: \p\ & \p\.
+@@end macro
+@@address@hidden,address@hidden
address@hidden example
+
address@hidden produces:
+
address@hidden
+Twice: a,b & a,b.
address@hidden display
+
+
address@hidden Macro Details
address@hidden Macro Details
address@hidden Macro details
address@hidden Details of macro usage
+
+Due to unavoidable disparities in the @TeX{} and @command{makeinfo}
+implementations, Texinfo macros have the following limitations.
+
address@hidden @bullet
address@hidden
+All macros are expanded inside at least one @TeX{} group. This means
+that @code{@@set} and other such commands will have no effect inside a
+macro.
+
address@hidden
+Macros containing a command which must be on a line by itself, such as a
+conditional, cannot be invoked in the middle of a line.
+
address@hidden
+Commas in macro arguments, even if escaped by a backslash, don't
+always work.
+
address@hidden
+The @TeX{} implementation cannot construct macros that define macros in
+the natural way. To do this, you must use conditionals and raw @TeX{}.
+For example:
+
address@hidden
+@@ifnottex
+@@macro ctor @{name, address@hidden
+@@macro \name\
+something involving \arg\ somehow
+@@end macro
+@@end macro
+@@end ifnottex
+@@tex
address@hidden,@}
+\gdef\ctorx#1,#2,@address@hidden involving #2 address@hidden@}
+@@end tex
address@hidden example
+
address@hidden
+It is best to avoid comments inside macro definitions.
+
address@hidden itemize
+
+If some macro feature causes errors when producing the printed version
+of a manual, try expanding the macros with @command{makeinfo} by
+invoking @command{texi2dvi} with the @samp{-e} option; see @ref{Format
+with texi2dvi}.
+
address@hidden alias
address@hidden @samp{@@alias @address@hidden
address@hidden Aliases, command
address@hidden Command aliases
address@hidden alias
+
+The @samp{@@alias} command defines a new command to be just like an
+existing one. This is useful for defining additional markup names, thus
+preserving semantic information in the input even though the output
+result may be the same.
+
+Write the @samp{@@alias} command on a line by itself, followed by the
+new command name, an equals sign, and the existing command name.
+Whitespace around the equals sign is ignored. Thus:
address@hidden
+@@alias @var{new} = @var{existing}
address@hidden example
+
+For example, if your document contains citations for both books and
+some other media (movies, for example), you might like to define a
+macro @code{@@address@hidden@}} that does the same thing as an ordinary
address@hidden@@address@hidden@}} but conveys the extra semantic information as
well.
+You'd do this as follows:
+
address@hidden
+@@alias moviecite = cite
address@hidden example
+
+Macros do not always have the same effect due to vagaries of argument
+parsing. Also, aliases are much simpler to define than macros. So the
+command is not redundant. (It was also heavily used in the Jargon File!)
+
+Aliases must not be recursive, directly or indirectly.
+
address@hidden definfoenclose
address@hidden @samp{definfoenclose}: Customized Highlighting
address@hidden Highlighting, customized
address@hidden Customized highlighting
address@hidden definfoenclose
+
+A @code{@@definfoenclose} command may be used to define a highlighting
+command for Info, but not for @TeX{}. A command defined using
address@hidden@@definfoenclose} marks text by enclosing it in strings that
+precede and follow the text. You can use this to get closer control of
+your Info output.
+
+Presumably, if you define a command with @code{@@definfoenclose} for Info,
+you will create a corresponding command for @TeX{}, either in
address@hidden, @file{texinfo.cnf}, or within an @samp{@@iftex} in
+your document.
+
+Write a @code{@@definfoenclose} command on a line and follow it with
+three arguments separated by commas. The first argument to
address@hidden@@definfoenclose} is the @@-command name (without the @code{@@});
+the second argument is the Info start delimiter string; and the third
+argument is the Info end delimiter string. The latter two arguments
+enclose the highlighted text in the Info file. A delimiter string may
+contain spaces. Neither the start nor end delimiter is required. If
+you do not want a start delimiter but do want an end delimiter, you must
+follow the command name with two commas in a row; otherwise, the Info
+formatting commands will naturally misinterpret the end delimiter string
+you intended as the start delimiter string.
+
+If you do a @code{@@definfoenclose} on the name of a pre-defined macro
+(such as @code{@@emph}, @code{@@strong}, @code{@@t}, or @code{@@i}), the
+enclosure definition will override the built-in definition.
+
+An enclosure command defined this way takes one argument in braces; this
+is intended for new markup commands (@pxref{Marking Text}).
+
address@hidden phoo
+For example, you can write:
+
address@hidden
+@@definfoenclose phoo,//,\\
address@hidden example
+
address@hidden
+near the beginning of a Texinfo file to define @code{@@phoo} as an Info
+formatting command that inserts `//' before and `\\' after the argument
+to @code{@@phoo}. You can then write @code{@@address@hidden@}} wherever you
+want `//bar\\' highlighted in Info.
+
+Also, for @TeX{} formatting, you could write
+
address@hidden
+@@iftex
+@@global@@let@@phoo=@@i
+@@end iftex
address@hidden example
+
address@hidden
+to define @code{@@phoo} as a command that causes @TeX{} to typeset the
+argument to @code{@@phoo} in italics.
+
+Each definition applies to its own formatter: one for @TeX{}, the other
+for @code{texinfo-format-buffer} or @code{texinfo-format-region}. The
address@hidden@@definfoenclose} command need not be within @samp{@@ifinfo}, but
+the raw @TeX{} commands do need to be in @samp{@@iftex}.
+
address@hidden headword
+Here is another example: write
+
address@hidden
+@@definfoenclose headword, , :
address@hidden example
+
address@hidden
+near the beginning of the file, to define @code{@@headword} as an Info
+formatting command that inserts nothing before and a colon after the
+argument to @code{@@headword}.
+
address@hidden@@definfoenclose} definitions must not be recursive, directly or
+indirectly.
+
+
address@hidden Hardcopy
address@hidden Formatting and Printing Hardcopy
address@hidden Format and print hardcopy
address@hidden Printing hardcopy
address@hidden Hardcopy, printing it
address@hidden Making a printed manual
address@hidden Sorting indices
address@hidden Indices, sorting
address@hidden @TeX{} index sorting
address@hidden texindex
+
+There are three major shell commands for making a printed manual from a
+Texinfo file: one for converting the Texinfo file into a file that will be
+printed, a second for sorting indices, and a third for printing the
+formatted document. When you use the shell commands, you can either
+work directly in the operating system shell or work within a shell
+inside GNU Emacs.
+
+If you are using GNU Emacs, you can use commands provided by Texinfo
+mode instead of shell commands. In addition to the three commands to
+format a file, sort the indices, and print the result, Texinfo mode
+offers key bindings for commands to recenter the output buffer, show the
+print queue, and delete a job from the print queue.
+
address@hidden
+* Use TeX:: Use @TeX{} to format for hardcopy.
+* Format with tex/texindex:: How to format with explicit shell commands.
+* Format with texi2dvi:: A simpler way to format.
+* Print with 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.
+* smallbook:: How to print small format books and manuals.
+* A4 Paper:: How to print on A4 or A5 paper.
+* 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.
address@hidden menu
+
address@hidden Use TeX
address@hidden Use @TeX{}
+
+The typesetting program called @TeX{} is used for formatting a Texinfo
+file. @TeX{} is a very powerful typesetting program and, if used correctly,
+does an exceptionally good job. (@xref{Obtaining TeX, , How to Obtain
address@hidden, for information on how to obtain @TeX{}.)
+
+The standalone @code{makeinfo} program and Emacs functions
address@hidden and @code{texinfo-format-buffer} commands
+read the very same @@-commands in the Texinfo file as does @TeX{}, but
+process them differently to make an Info file (@pxref{Creating an Info
+File}).
+
+
address@hidden Format with tex/texindex
address@hidden Format with @code{tex} and @code{texindex}
address@hidden Shell formatting with @code{tex} and @code{texindex}
address@hidden Formatting with @code{tex} and @code{texindex}
address@hidden DVI file
+
+Format the Texinfo file with the shell command @code{tex} followed by
+the name of the Texinfo file. For example:
+
address@hidden
+tex foo.texi
address@hidden example
+
address@hidden @TeX{} will produce a @dfn{DVI file} as well as several auxiliary
+files containing information for indices, cross references, etc. The
+DVI file (for @dfn{DeVice Independent} file) can be printed on virtually
+any device (see the following sections).
+
address@hidden texindex
+The @code{tex} formatting command itself does not sort the indices; it
+writes an output file of unsorted index data. (The @code{texi2dvi}
+command automatically generates indices; @pxref{Format with texi2dvi,,
+Format with @code{texi2dvi}}.) To generate a printed index after
+running the @code{tex} command, you first need a sorted index to work
+from. The @code{texindex} command sorts indices. (The source file
address@hidden comes as part of the standard Texinfo distribution,
+among other places.)@refill
+
address@hidden Names of index files
address@hidden Index file names
+The @code{tex} formatting command outputs unsorted index files under
+names that obey a standard convention: the name of your main input file
+with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c,
+Web2c}) extension removed, followed by the two letter names of indices.
+For example, the raw index output files for the input file
address@hidden would be @file{foo.cp}, @file{foo.vr}, @file{foo.fn},
address@hidden, @file{foo.pg} and @file{foo.ky}. Those are exactly the
+arguments to give to @code{texindex}.
+
address@hidden 1000
address@hidden Wildcards
address@hidden Globbing
+Instead of specifying all the unsorted index file names explicitly, you
+can use @samp{??} as shell wildcards and give the command in this
+form:
+
address@hidden
+texindex foo.??
address@hidden example
+
address@hidden
+This command will run @code{texindex} on all the unsorted index files,
+including any that you have defined yourself using @code{@@defindex}
+or @code{@@defcodeindex}. (You may execute @samp{texindex foo.??}
+even if there are similarly named files with two letter extensions
+that are not index files, such as @samp{foo.el}. The @code{texindex}
+command reports but otherwise ignores such files.)
+
+For each file specified, @code{texindex} generates a sorted index file
+whose name is made by appending @samp{s} to the input file name. The
address@hidden@@printindex} command looks for a file with that name
+(@pxref{Printing Indices & Menus}). @code{texindex} does not alter the
+raw index output file.
+
+After you have sorted the indices, you need to rerun the @code{tex}
+formatting command on the Texinfo file. This regenerates the DVI file,
+this time with up-to-date index entries.
+
+Finally, you may need to run @code{tex} one more time, to get the page
+numbers in the cross-references correct.
+
+To summarize, this is a five step process:
+
address@hidden
address@hidden
+Run @code{tex} on your Texinfo file. This generates a DVI file (with
+undefined cross-references and no indices), and the raw index files
+(with two letter extensions).
+
address@hidden
+Run @code{texindex} on the raw index files. This creates the
+corresponding sorted index files (with three letter extensions).
+
address@hidden
+Run @code{tex} again on your Texinfo file. This regenerates the DVI
+file, this time with indices and defined cross-references, but with page
+numbers for the cross-references from last time, generally incorrect.
+
address@hidden
+Sort the indices again, with @code{texindex}.
+
address@hidden
+Run @code{tex} one last time. This time the correct page numbers are
+written for the cross-references.
address@hidden enumerate
+
address@hidden texi2dvi
+Alternatively, it's a one-step process: run @code{texi2dvi}
+(@pxref{Format with texi2dvi}).
+
+You need not run @code{texindex} each time after you run @code{tex}. If
+you do not, on the next run, the @code{tex} formatting command will use
+whatever sorted index files happen to exist from the previous use of
address@hidden This is usually ok while you are debugging.
+
address@hidden Auxiliary files, avoiding
address@hidden novalidate
address@hidden Pointer validation, suppressing
address@hidden Chapters, formatting one at a time
+Sometimes you may wish to print a document while you know it is
+incomplete, or to print just one chapter of a document. In that case,
+the usual auxiliary files that @TeX{} creates and warnings @TeX{} gives
+when cross-references are not satisfied are just nuisances. You can
+avoid them with the @code{@@novalidate} command, which you must give
address@hidden the @code{@@setfilename} command
+(@pxref{setfilename,,@code{@@setfilename}}). Thus, the beginning of
+your file would look approximately like this:
+
address@hidden
+\input texinfo
+@@novalidate
+@@setfilename myfile.info
address@hidden
address@hidden example
+
address@hidden @code{@@novalidate} also turns off validation in
address@hidden, just like its @code{--no-validate} option
+(@pxref{Pointer Validation}).
+
+
address@hidden Format with texi2dvi
address@hidden Format with @code{texi2dvi}
address@hidden texi2dvi @r{(shell script)}
+
+The @code{texi2dvi} command automatically runs both @code{tex} and
address@hidden as many times as necessary to produce a DVI file with
+sorted indices and all cross-references resolved. It simplifies the
address@hidden@address@hidden@code{tex} sequence
+described in the previous section.
+
+To run @code{texi2dvi} on an input file @file{foo.texi}, do this (where
address@hidden } is your shell prompt):
+
address@hidden
+prompt$ @kbd{texi2dvi foo.texi}
address@hidden example
+
+As shown in this example, the input filenames to @code{texi2dvi} must
+include any extension (@samp{.texi}, @samp{.texinfo}, etc.). Under
+MS-DOS and perhaps in other circumstances, you may need to run @samp{sh
+texi2dvi foo.texi} instead of relying on the operating system to invoke
+the shell on the @samp{texi2dvi} script.
+
+Perhaps the most useful option to @code{texi2dvi} is
address@hidden@var{cmd}}. This inserts @var{cmd} on a line by itself
+after the @code{@@setfilename} in a temporary copy of the input file
+before running @TeX{}. With this, you can specify different printing
+formats, such as @code{@@smallbook} (@pxref{smallbook}),
address@hidden@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes}
+(@pxref{pagesizes}), without actually changing the document source.
+(You can also do this on a site-wide basis with @file{texinfo.cnf};
address@hidden for TeX,,Preparing for @TeX{}}).
+
+For a list of other options, run @samp{texi2dvi --help}.
+
+
address@hidden Print with lpr
address@hidden Shell Print Using @code{lpr -d}
address@hidden lpr @r{(DVI print command)}
+
+The precise command to print a DVI file depends on your system
+installation. Two common ones are @samp{dvips foo.dvi -o} and @samp{lpr
+-d foo.dvi}.
+
+For example, the following commands will (perhaps) suffice to sort the
+indices, format, and print the @cite{Bison Manual}:
+
address@hidden
address@hidden
+tex bison.texinfo
+texindex bison.??
+tex bison.texinfo
+lpr -d bison.dvi
address@hidden group
address@hidden example
+
address@hidden
+(Remember that the shell commands may be different at your site; but
+these are commonly used versions.)
+
+Using the @code{texi2dvi} shell script (see the previous section):
+
address@hidden
address@hidden
+texi2dvi bison.texinfo
+lpr -d bison.dvi
+# or perhaps dvips bison.dvi -o
address@hidden group
address@hidden example
+
address@hidden Shell printing, on MS-DOS/MS-Windows
address@hidden Printing DVI files, on MS-DOS/MS-Windows
address@hidden address@hidden, replacements on MS-DOS/MS-Windows}
address@hidden is a standard program on Unix systems, but it is usually
+absent on MS-DOS/MS-Windows. Some network packages come with a
+program named @code{lpr}, but these are usually limited to sending files
+to a print server over the network, and generally don't support the
address@hidden option. If you are unfortunate enough to work on one of these
+systems, you have several alternative ways of printing DVI files:
+
address@hidden @bullet{}
address@hidden Find and install a Unix-like @code{lpr} program, or its clone.
+If you can do that, you will be able to print DVI files just like
+described above.
+
address@hidden Send the DVI files to a network printer queue for DVI files.
+Some network printers have special queues for printing DVI files. You
+should be able to set up your network software to send files to that
+queue. In some cases, the version of @code{lpr} which comes with your
+network software will have a special option to send a file to specific
+queues, like this:
+
address@hidden
+lpr -Qdvi -hprint.server.domain bison.dvi
address@hidden example
+
address@hidden Convert the DVI file to a Postscript or PCL file and send it to
your
+local printer. @xref{dvips invocation,,, dvips, Dvips}, and the man
+pages for @code{dvilj}, for detailed description of these tools. Once
+the DVI file is converted to the format your local printer understands
+directly, just send it to the appropriate port, usually @samp{PRN}.
address@hidden itemize
+
+
address@hidden Within Emacs
address@hidden From an Emacs Shell
address@hidden Print, format from Emacs shell
address@hidden Format, print from Emacs shell
address@hidden Shell, format, print from
address@hidden Emacs shell, format, print from
address@hidden GNU Emacs shell, format, print from
+
+You can give formatting and printing commands from a shell within GNU
+Emacs. To create a shell within Emacs, type @kbd{M-x shell}. In this
+shell, you can format and print the document. @xref{Hardcopy, , Format
+and Print Hardcopy}, for details.
+
+You can switch to and from the shell buffer while @code{tex} is
+running and do other editing. If you are formatting a long document
+on a slow machine, this can be very address@hidden
+
+You can also use @code{texi2dvi} from an Emacs shell. For example,
+here is how to use @code{texi2dvi} to format and print @cite{Using and
+Porting GNU CC} from a shell within Emacs:
+
address@hidden
address@hidden
+texi2dvi gcc.texinfo
+lpr -d gcc.dvi
address@hidden group
address@hidden example
+
address@hidden Mode Printing}, for more information about formatting
+and printing in Texinfo address@hidden
+
+
address@hidden Texinfo Mode Printing, Compile-Command, Within Emacs, Hardcopy
address@hidden Formatting and Printing in Texinfo Mode
address@hidden Region printing in Texinfo mode
address@hidden Format and print in Texinfo mode
address@hidden Print and format in Texinfo mode
+
+Texinfo mode provides several predefined key commands for @TeX{}
+formatting and printing. These include commands for sorting indices,
+looking at the printer queue, killing the formatting job, and
+recentering the display of the buffer in which the operations
address@hidden
+
address@hidden @kbd
address@hidden C-c C-t C-b
address@hidden M-x texinfo-tex-buffer
+Run @code{texi2dvi} on the current address@hidden
+
address@hidden C-c C-t C-r
address@hidden M-x texinfo-tex-region
+Run @TeX{} on the current address@hidden
+
address@hidden C-c C-t C-i
address@hidden M-x texinfo-texindex
+Sort the indices of a Texinfo file formatted with
address@hidden@refill
+
address@hidden C-c C-t C-p
address@hidden M-x texinfo-tex-print
+Print a DVI file that was made with @code{texinfo-tex-region} or
address@hidden@refill
+
address@hidden C-c C-t C-q
address@hidden M-x tex-show-print-queue
+Show the print address@hidden
+
address@hidden C-c C-t C-d
address@hidden M-x texinfo-delete-from-print-queue
+Delete a job from the print queue; you will be prompted for the job
+number shown by a preceding @kbd{C-c C-t C-q} command
+(@code{texinfo-show-tex-print-queue})address@hidden
+
address@hidden C-c C-t C-k
address@hidden M-x tex-kill-job
+Kill the currently running @TeX{} job started by either
address@hidden or @code{texinfo-tex-buffer}, or any other
+process running in the Texinfo shell address@hidden
+
address@hidden C-c C-t C-x
address@hidden M-x texinfo-quit-job
+Quit a @TeX{} formatting job that has stopped because of an error by
+sending an @key{x} to it. When you do this, @TeX{} preserves a record
+of what it did in a @file{.log} address@hidden
+
address@hidden C-c C-t C-l
address@hidden M-x tex-recenter-output-buffer
+Redisplay the shell buffer in which the @TeX{} printing and formatting
+commands are run to show its most recent address@hidden
address@hidden table
+
address@hidden 1000
+Thus, the usual sequence of commands for formatting a buffer is as
+follows (with comments to the right):@refill
+
address@hidden
address@hidden
+C-c C-t C-b @r{Run @code{texi2dvi} on the buffer.}
+C-c C-t C-p @r{Print the DVI file.}
+C-c C-t C-q @r{Display the printer queue.}
address@hidden group
address@hidden example
+
+The Texinfo mode @TeX{} formatting commands start a subshell in Emacs
+called the @file{*tex-shell*}. The @code{texinfo-tex-command},
address@hidden, and @code{tex-dvi-print-command}
+commands are all run in this shell.
+
+You can watch the commands operate in the @samp{*tex-shell*} buffer,
+and you can switch to and from and use the @samp{*tex-shell*} buffer
+as you would any other shell address@hidden
+
address@hidden 1500
+The formatting and print commands depend on the values of several variables.
+The default values are:@refill
+
address@hidden
address@hidden
+ @r{Variable} @r{Default value}
+
+texinfo-texi2dvi-command "texi2dvi"
+texinfo-tex-command "tex"
+texinfo-texindex-command "texindex"
+texinfo-delete-from-print-queue-command "lprm"
+texinfo-tex-trailer "@@bye"
+tex-start-of-header "%**start"
+tex-end-of-header "%**end"
+tex-dvi-print-command "lpr -d"
+tex-show-queue-command "lpq"
address@hidden group
address@hidden example
+
+You can change the values of these variables with the @kbd{M-x
+edit-options} command (@pxref{Edit Options, , Editing Variable Values,
+emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command
+(@pxref{Examining, , Examining and Setting Variables, emacs, The GNU
+Emacs Manual}), or with your @file{.emacs} initialization file
+(@pxref{Init File, , , emacs, The GNU Emacs Manual})address@hidden
+
address@hidden Customize Emacs package (@t{Development/Docs/Texinfo})
+Beginning with version 20, GNU Emacs offers a user-friendly interface,
+called @dfn{Customize}, for changing values of user-definable variables.
address@hidden Customization, , Easy Customization Interface, emacs, The GNU
+Emacs Manual}, for more details about this. The Texinfo variables can
+be found in the @samp{Development/Docs/Texinfo} group, once you invoke
+the @kbd{M-x customize} command.
+
+
address@hidden Compile-Command
address@hidden Using the Local Variables List
address@hidden Local variables
address@hidden Compile command for formatting
address@hidden Format with the compile command
+
+Yet another way to apply the @TeX{} formatting command to a Texinfo file
+is to put that command in a @dfn{local variables list} at the end of the
+Texinfo file. You can then specify the @code{tex} or @code{texi2dvi}
+commands as a @code{compile-command} and have Emacs run it by typing
address@hidden compile}. This creates a special shell called the
address@hidden buffer in which Emacs runs the compile command.
+For example, at the end of the @file{gdb.texinfo} file, after the
address@hidden@@bye}, you could put the following:@refill
+
address@hidden
address@hidden
+Local Variables:
+compile-command: "texi2dvi gdb.texinfo"
+End:
address@hidden group
address@hidden example
+
address@hidden
+This technique is most often used by programmers who also compile programs
+this way; see @ref{Compilation, , , emacs, The GNU Emacs address@hidden
+
+
address@hidden Requirements Summary
address@hidden @TeX{} Formatting Requirements Summary
address@hidden Requirements for formatting
address@hidden Minimal requirements for formatting
address@hidden Formatting requirements
+
+Every Texinfo file that is to be input to @TeX{} must begin with a
address@hidden command and must contain an @code{@@setfilename} command:
+
address@hidden
+\input texinfo
+@@setfilename @address@hidden
address@hidden example
+
address@hidden
+The first command instructs @TeX{} to load the macros it needs to
+process a Texinfo file and the second command opens auxiliary files.
+
+Every Texinfo file must end with a line that terminates @TeX{}'s
+processing and forces out unfinished pages:
+
address@hidden
+@@bye
address@hidden example
+
+Strictly speaking, these lines are all a Texinfo file needs to be
+processed successfully by @TeX{}.
+
+Usually, however, the beginning includes an @code{@@settitle} command to
+define the title of the printed manual, an @code{@@setchapternewpage}
+command, a title page, a copyright page, and permissions. Besides an
address@hidden@@bye}, the end of a file usually includes indices and a table of
+contents. (And of course most manuals contain a body of text as well.)
+
+For more information, see:
address@hidden @bullet
address@hidden @ref{settitle, , @code{@@settitle}}
address@hidden @ref{setchapternewpage, , @code{@@setchapternewpage}}
address@hidden @ref{Headings, ,Page Headings}
address@hidden @ref{Titlepage & Copyright Page}
address@hidden @ref{Printing Indices & Menus}
address@hidden @ref{Contents}
address@hidden itemize
+
+
address@hidden Preparing for TeX
address@hidden Preparing for @TeX{}
address@hidden Preparing for @TeX{}
address@hidden @TeX{} input initialization
address@hidden @code{TEXINPUTS} environment variable
address@hidden TEXINPUTS
address@hidden @b{.profile} initialization file
address@hidden @b{.cshrc} initialization file
address@hidden Initialization file for @TeX{} input
+
address@hidden needs to know where to find the @file{texinfo.tex} file that the
address@hidden texinfo} command on the first line reads. The
address@hidden file tells @TeX{} how to handle @@-commands; it is
+included in all standard GNU distributions.
+
address@hidden address@hidden, installing}
+
+Usually, the installer has put the @file{texinfo.tex} file in the
+default directory that contains @TeX{} macros when GNU Texinfo, Emacs or
+other GNU software is installed. In this case, @TeX{} will find the
+file and you do not need to do anything special. If this has not been
+done, you can put @file{texinfo.tex} in the current directory when you
+run @TeX{}, and @TeX{} will find it there.
+
address@hidden address@hidden, installing}
+Also, you should install @file{epsf.tex}, if it is not already installed
+from another distribution. More details are at the end of the description
+of the @code{@@image} command (@pxref{Images}).
+
address@hidden address@hidden, installing}
+Likewise for @file{pdfcolor.tex}, if it is not already installed and you
+use pdftex.
+
address@hidden texinfo.cnf @r{installation}
address@hidden Customizing of @TeX{} for Texinfo
address@hidden Site-wide Texinfo configuration file
+Optionally, you may create an additional @file{texinfo.cnf}, and install
+it as well. This file is read by @TeX{} when the @code{@@setfilename}
+command is executed (@pxref{setfilename,, @code{@@setfilename}}). You can put
any
+commands you like there, according to local site-wide conventions. They
+will be read by @TeX{} when processing any Texinfo document. For
+example, if @file{texinfo.cnf} contains the line @samp{@@afourpaper}
+(@pxref{A4 Paper}), then all Texinfo documents will be processed with
+that page size in effect. If you have nothing to put in
address@hidden, you do not need to create it.
+
address@hidden TEXINPUTS
+If neither of the above locations for these system files suffice for
+you, you can specify the directories explicitly. For
address@hidden, you can do this by writing the complete path for the
+file after the @code{\input} command. Another way, that works for both
address@hidden and @file{texinfo.cnf} (and any other file @TeX{}
+might read), is to set the @code{TEXINPUTS} environment variable in your
address@hidden or @file{.profile} file.
+
+Which you use of @file{.cshrc} or @file{.profile} depends on
+whether you use a Bourne shell-compatible (@code{sh}, @code{bash},
address@hidden, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh})
+command interpreter. The latter read the @file{.cshrc} file for
+initialization information, and the former read @file{.profile}.
+
+In a @file{.cshrc} file, you could use the following @code{csh} command
+sequence:
+
address@hidden
+setenv TEXINPUTS .:/home/me/mylib:/usr/lib/tex/macros
address@hidden example
+
address@hidden 1000
+In a @file{.profile} file, you could use the following @code{sh} command
+sequence:
+
address@hidden
address@hidden
+TEXINPUTS=.:/home/me/mylib:/usr/lib/tex/macros
+export TEXINPUTS
address@hidden group
address@hidden example
+
+On MS-DOS/MS-Windows, you would say it like address@hidden the use
+of the @samp{;} character, instead of @samp{:}, as directory separator
+on these systems.}:
+
address@hidden
address@hidden
+set TEXINPUTS=.;d:/home/me/mylib;c:/usr/lib/tex/macros
address@hidden group
address@hidden example
+
address@hidden
+It is customary for DOS/Windows users to put such commands in the
address@hidden file, or in the Windows address@hidden
+
address@hidden
+These settings would cause @TeX{} to look for @file{\input} file first
+in the current directory, indicated by the @samp{.}, then in a
+hypothetical user's @file{me/mylib} directory, and finally in a system
+directory @file{/usr/lib/tex/macros}.
+
address@hidden Dumping a .fmt file
address@hidden Format file, dumping
+Finally, you may wish to dump a @file{.fmt} file (@pxref{Memory dumps,,,
+web2c, Web2c}) so that @TeX{} can load Texinfo faster. (The
+disadvantage is that then updating @file{texinfo.tex} requires
+redumping.) You can do this by running this command, assuming
address@hidden is findable by @TeX{}:
+
address@hidden
+initex texinfo @@dump
address@hidden example
+
+(@code{dump} is a @TeX{} primitive.) Then, move @file{texinfo.fmt} to
+wherever your @code{.fmt} files are found; typically, this will be in the
+subdirectory @file{web2c} of your @TeX{} installation.
+
+
address@hidden Overfull hboxes
address@hidden Overfull ``hboxes''
address@hidden Overfull @samp{hboxes}
address@hidden @samp{hboxes}, overfull
address@hidden Final output
+
address@hidden is sometimes unable to typeset a line without extending it into
+the right margin. This can occur when @TeX{} comes upon what it
+interprets as a long word that it cannot hyphenate, such as an
+electronic mail network address or a very long title. When this
+happens, @TeX{} prints an error message like this:
+
address@hidden
+Overfull @@hbox (20.76302pt too wide)
address@hidden example
+
address@hidden hbox
address@hidden
+(In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''.
address@hidden@@hbox} is a @TeX{} primitive not needed in the Texinfo language.)
+
address@hidden also provides the line number in the Texinfo source file and
+the text of the offending line, which is marked at all the places that
address@hidden considered hyphenation.
address@hidden with TeX, , Catching Errors with @TeX{} Formatting},
+for more information about typesetting errors.
+
+If the Texinfo file has an overfull hbox, you can rewrite the sentence
+so the overfull hbox does not occur, or you can decide to leave it. A
+small excursion into the right margin often does not matter and may not
+even be noticeable.
+
+If you have many overfull boxes and/or an antipathy to rewriting, you
+can coerce @TeX{} into greatly increasing the allowable interword
+spacing, thus (if you're lucky) avoiding many of the bad line breaks,
+like this:
+
address@hidden \emergencystretch
address@hidden
+@@tex
+\global\emergencystretch = .9\hsize
+@@end tex
address@hidden example
+
address@hidden
+(You should adjust the fraction as needed.) This huge value for
address@hidden cannot be the default, since then the typeset
+output would generally be of noticeably lower quality; the default
+is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension
+containing the current line width.
+
address@hidden Black rectangle in hardcopy
address@hidden Rectangle, black in hardcopy
address@hidden Box, ugly black in hardcopy
address@hidden Ugly black rectangles in hardcopy
+For what overfull boxes you have, however, @TeX{} will print a large,
+ugly, black rectangle beside the line that contains the overfull hbox
+unless told otherwise. This is so you will notice the location of the
+problem if you are correcting a draft.
+
address@hidden finalout
+To prevent such a monstrosity from marring your final printout, write
+the following in the beginning of the Texinfo file on a line of its own,
+before the @code{@@titlepage} command:
+
address@hidden
+@@finalout
address@hidden example
+
+
address@hidden smallbook
address@hidden Printing ``Small'' Books
address@hidden smallbook
address@hidden Small book size
address@hidden Book, printing small
address@hidden Page sizes for books
address@hidden Size of printed book
+
+By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch
+format. However, you can direct @TeX{} to typeset a document in a 7 by
+9.25 inch format that is suitable for bound books by inserting the
+following command on a line by itself at the beginning of the Texinfo
+file, before the title page:@refill
+
address@hidden
+@@smallbook
address@hidden example
+
address@hidden
+(Since many books are about 7 by 9.25 inches, this command might better
+have been called the @code{@@regularbooksize} command, but it came to be
+called the @code{@@smallbook} command by comparison to the 8.5 by 11 inch
format.)
+
+If you write the @code{@@smallbook} command between the
+start-of-header and end-of-header lines, the Texinfo mode @TeX{}
+region formatting command, @code{texinfo-tex-region}, will format the
+region in ``small'' book size (@pxref{Start of Header})address@hidden
+
address@hidden, for information about
+commands that make it easier to produce examples for a smaller manual.
+
address@hidden with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
address@hidden, for other ways to format with @code{@@smallbook} that do not
+require changing the source file.
+
+
address@hidden A4 Paper
address@hidden Printing on A4 Paper
address@hidden A4 paper, printing on
address@hidden A5 paper, printing on
address@hidden Paper size, A4
address@hidden European A4 paper
address@hidden afourpaper
+
+You can tell @TeX{} to format a document for printing on European size
+A4 paper (or A5) with the @code{@@afourpaper} (or @code{@@afivepaper})
+command. Write the command on a line by itself near the beginning of
+the Texinfo file, before the title page. For example, this is how you
+would write the header for this manual:
+
address@hidden
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename texinfo
+@@settitle Texinfo
+@@afourpaper
+@@c %**end of header
address@hidden group
address@hidden example
+
address@hidden with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
address@hidden, for other ways to format for different paper sizes that do not
+require changing the source file.
+
address@hidden afourlatex
address@hidden afourwide
+You may or may not prefer the formatting that results from the command
address@hidden@@afourlatex}. There's also @code{@@afourwide} for A4 paper in
+wide format.
+
address@hidden pagesizes
address@hidden @code{@@pagesizes} address@hidden, @var{height}]: Custom page
sizes
address@hidden pagesizes
address@hidden Custom page sizes
address@hidden Page sizes, customized
address@hidden Text width and height
address@hidden Width of text area
address@hidden Height of text area
address@hidden Depth of text area
+
+You can explicitly specify the height and (optionally) width of the main
+text area on the page with the @code{@@pagesizes} command. Write this
+on a line by itself near the beginning of the Texinfo file, before the
+title page. The height comes first, then the width if desired,
+separated by a comma. Examples:
+
address@hidden
+@@pagesizes 200mm,150mm @c for b5 paper
address@hidden example
address@hidden and
address@hidden
+@@pagesizes 11.5in @c for legal paper
address@hidden example
+
address@hidden B5 paper, printing on
address@hidden Legal paper, printing on
+This would be reasonable for printing on B5-size paper. To emphasize,
+this command specifies the size of the @emph{text area}, not the size of
+the paper (which is address@hidden by address@hidden for B5, address@hidden by
address@hidden for legal).
+
address@hidden Margins on page, not controllable
+To make more elaborate changes, such as changing any of the page
+margins, you must define a new command in @file{texinfo.tex} (or
address@hidden, @pxref{Preparing for TeX,,Preparing for @TeX{}}).
+
address@hidden with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
address@hidden, for other ways to specify @code{@@pagesizes} that do not
+require changing the source file.
+
address@hidden@@pagesizes} is ignored by @code{makeinfo}.
+
+
address@hidden Cropmarks and Magnification
address@hidden Cropmarks and Magnification
address@hidden cropmarks
address@hidden Cropmarks for printing
address@hidden Printing cropmarks
+You can (attempt to) direct @TeX{} to print cropmarks at the corners of
+pages with the @code{@@cropmarks} command. Write the @code{@@cropmarks}
+command on a line by itself between @code{@@iftex} and @code{@@end
+iftex} lines near the beginning of the Texinfo file, before the title
+page, like this:@refill
+
address@hidden
address@hidden
+@@iftex
+@@cropmarks
+@@end iftex
address@hidden group
address@hidden example
+
+This command is mainly for printers that typeset several pages on one
+sheet of film; but you can attempt to use it to mark the corners of a
+book set to 7 by 9.25 inches with the @code{@@smallbook} command.
+(Printers will not produce cropmarks for regular sized output that is
+printed on regular sized paper.) Since different printing machines work
+in different ways, you should explore the use of this command with a
+spirit of adventure. You may have to redefine the command in
address@hidden
+
address@hidden \mag @r{(raw @TeX{} magnification)}
address@hidden Magnified printing
address@hidden Larger or smaller pages
+You can attempt to direct @TeX{} to typeset pages larger or smaller than
+usual with the @code{\mag} @TeX{} command. Everything that is typeset
+is scaled proportionally larger or smaller. (@code{\mag} stands for
+``magnification''.) This is @emph{not} a Texinfo @@-command, but is a
+plain @TeX{} command that is prefixed with a backslash. You have to
+write this command between @code{@@tex} and @code{@@end tex}
+(@pxref{Raw Formatter Commands}).
+
+Follow the @code{\mag} command with an @samp{=} and then a number that
+is 1000 times the magnification you desire. For example, to print pages
+at 1.2 normal size, write the following near the beginning of the
+Texinfo file, before the title page:
+
address@hidden
address@hidden
+@@tex
+\mag=1200
+@@end tex
address@hidden group
address@hidden example
+
+With some printing technologies, you can print normal-sized copies that
+look better than usual by giving a larger-than-normal master to your
+print shop. They do the reduction, thus effectively increasing the
+resolution.
+
+Depending on your system, DVI files prepared with a
address@hidden may not print or may print only with certain
+magnifications. Be prepared to experiment.
+
+
address@hidden PDF Output
address@hidden PDF Output
address@hidden PDF output
+
address@hidden pdftex
+You can generate a PDF output file from Texinfo source by using the
address@hidden program to process your file instead of plain
address@hidden Just run @samp{pdftex foo.texi} instead of @samp{tex
+foo.texi}, or give the @samp{--pdf} option to @command{texi2dvi}.
+
address@hidden stands for `Portable Document Format'. It was invented by
+Adobe Systems some years ago for document interchange, based on their
+PostScript language. A @uref{http://www.foolabs.com/xpdf/, PDF reader}
+for the X window system is freely available, as is the
address@hidden://partners.adobe.com/asn/developer/technotes/, definition of
+the file format}. Since PDF is a binary format, there are no
address@hidden@@ifpdf} or @samp{@@pdf} commands as with the other output
+formats.
+
+Despite the `portable' in the name, PDF files are nowhere near as
+portable in practice as the plain ASCII formats (Info, HTML) that
+Texinfo supports (DVI portability is arguable). They also tend to be
+much larger and do not support the bitmap fonts used by @TeX{} (by
+default) very well. Nevertheless, a PDF file does preserve an actual
+printed document on a screen as faithfully as possible, so it has its place.
+
+PDF support in Texinfo is fairly rudimentary.
+
+
address@hidden Creating and Installing Info Files
address@hidden Creating and Installing Info Files
+
+This chapter describes how to create and install Info files. @xref{Info
+Files}, for general information about the file format itself.
+
address@hidden
+* Creating an Info File::
+* Installing an Info File::
address@hidden menu
+
+
address@hidden Creating an Info File
address@hidden Creating an Info File
address@hidden Creating an Info file
address@hidden Info, creating an online file
address@hidden Formatting a file for Info
+
address@hidden is a program that converts a Texinfo file into an Info
+file, HTML file, or plain text. @code{texinfo-format-region} and
address@hidden are GNU Emacs functions that convert
+Texinfo to Info.
+
+For information on installing the Info file in the Info system,
address@hidden an Info File}.
+
address@hidden
+* makeinfo advantages:: @code{makeinfo} provides better error checking.
+* Invoking makeinfo:: How to run @code{makeinfo} from a shell.
+* makeinfo options:: Specify fill-column and other options.
+* Pointer Validation:: How to check that pointers point somewhere.
+* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs.
+* 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.
+* makeinfo html:: Generating HTML output.
address@hidden menu
+
+
address@hidden makeinfo advantages
address@hidden @code{makeinfo} Preferred
+
+The @code{makeinfo} utility creates an Info file from a Texinfo source
+file more quickly than either of the Emacs formatting commands and
+provides better error messages. We recommend it. @code{makeinfo} is a
+C program that is independent of Emacs. You do not need to run Emacs to
+use @code{makeinfo}, which means you can use @code{makeinfo} on machines
+that are too small to run Emacs. You can run @code{makeinfo} in any one
+of three ways: from an operating system shell, from a shell inside
+Emacs, or by typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b}
+command in Texinfo mode in Emacs.
address@hidden
+
+The @code{texinfo-format-region} and the @code{texinfo-format-buffer}
+commands are useful if you cannot run @code{makeinfo}. Also, in some
+circumstances, they format short regions or buffers more quickly than
address@hidden@refill
+
address@hidden Invoking makeinfo
address@hidden Running @code{makeinfo} from a Shell
+
+To create an Info file from a Texinfo file, type @code{makeinfo}
+followed by the name of the Texinfo file. Thus, to create the Info
+file for Bison, type the following to the shell:
+
address@hidden
+makeinfo bison.texinfo
address@hidden example
+
+(You can run a shell inside Emacs by typing @kbd{M-x shell}.)@refill
+
+Sometimes you will want to specify options. For example, if you wish
+to discover which version of @code{makeinfo} you are using,
+type:@refill
+
address@hidden
+makeinfo --version
address@hidden example
+
address@hidden options}, for more information.
+
+
address@hidden makeinfo options
address@hidden Options for @code{makeinfo}
address@hidden @code{makeinfo} options
address@hidden Options for @code{makeinfo}
+
+The @code{makeinfo} command takes a number of options. Most often,
+options are used to set the value of the fill column and specify the
+footnote style. Each command line option is a word preceded by
address@hidden or a letter preceded by @samp{-}. You can use abbreviations
+for the long option names as long as they are address@hidden
+
+For example, you could use the following shell command to create an Info
+file for @file{bison.texinfo} in which each line is filled to only 68
+columns:@refill
+
address@hidden
+makeinfo --fill-column=68 bison.texinfo
address@hidden example
+
+You can write two or more options in sequence, like this:@refill
+
address@hidden
+makeinfo --no-split --fill-column=70 @dots{}
address@hidden example
+
address@hidden
+This would keep the Info file together as one possibly very long
+file and would also set the fill column to address@hidden
+
+The options are:
+
address@hidden @code
+
address@hidden -D @var{var}
address@hidden -D @var{var}
+Cause the variable @var{var} to be defined. This is equivalent to
address@hidden@@set @var{var}} in the Texinfo file (@pxref{set clear value}).
+
address@hidden --commands-in-node-names
address@hidden --commands-in-node-names
+Allow @code{@@}-commands in node names. This is not recommended, as it
+can probably never be implemented in @TeX{}. It also makes
address@hidden much slower. Also, this option is ignored when
address@hidden is used. @xref{Pointer Validation}, for more
+details.
+
address@hidden --docbook
address@hidden --docbook
+Generate DocBook output rather than Info.
+
address@hidden address@hidden
address@hidden -e @var{limit}
address@hidden address@hidden
address@hidden -e @var{limit}
+Set the maximum number of errors that @code{makeinfo} will report
+before exiting (on the assumption that continuing would be useless);
+default 100.
+
address@hidden address@hidden
address@hidden -f @var{width}
address@hidden address@hidden
address@hidden -f @var{width}
+Specify the maximum number of columns in a line; this is the right-hand
+edge of a line. Paragraphs that are filled will be filled to this
+width. (Filling is the process of breaking up and connecting lines so
+that lines are the same length as or shorter than the number specified
+as the fill column. Lines are broken between words.) The default value
+is 72. Ignored with @samp{--html}.
+
address@hidden address@hidden
address@hidden -s @var{style}
address@hidden address@hidden
address@hidden -s @var{style}
+Set the footnote style to @var{style}, either @samp{end} for the end
+node style (the default) or @samp{separate} for the separate node style.
+The value set by this option overrides the value set in a Texinfo file
+by an @code{@@footnotestyle} command (@pxref{Footnotes}). When the
+footnote style is @samp{separate}, @code{makeinfo} makes a new node
+containing the footnotes found in the current node. When the footnote
+style is @samp{end}, @code{makeinfo} places the footnote references at
+the end of the current node. Ignored with @samp{--html}.
+
address@hidden --force
address@hidden -F
address@hidden --force
address@hidden -F
+Ordinarily, if the input file has errors, the output files are not
+created. With this option, they are preserved.
+
address@hidden --help
address@hidden -h
address@hidden --help
address@hidden -h
+Print a usage message listing all available options, then exit successfully.
+
address@hidden --html
address@hidden --html
+Generate HTML output rather than Info. @xref{makeinfo html}. By
+default, the HTML output is split into one output file per source node,
+and the split output is written into a subdirectory with the name of the
+top-level info file.
+
address@hidden -I @var{dir}
address@hidden -I @var{dir}
+Append @var{dir} to the directory search list for finding files that
+are included using the @code{@@include} command. By default,
address@hidden searches only the current directory. If @var{dir} is
+not given, the current directory @file{.} is appended. Note that
address@hidden can actually be a list of several directories separated by the
+usual path separator character (@samp{:} on Unix, @samp{;} on
+MS-DOS/MS-Windows).
+
address@hidden address@hidden
address@hidden -E @var{file}
+Output the Texinfo source with all the macros expanded to the named
+file. Normally, the results of macro expansion are used internally by
address@hidden and then discarded. This option is used by
address@hidden if you are using an old version of @file{texinfo.tex}
+that does not support @code{@@macro}.
+
address@hidden --no-headers
address@hidden --no-headers
address@hidden Plain text output
address@hidden ASCII text output
address@hidden Generating plain text files
address@hidden @file{INSTALL} file, generating
address@hidden Node separators, omitting
address@hidden Menus, omitting
+For Info output, do not include menus or node separator lines in the
+output. This results in a simple plain text file that you can (for
+example) send in email without complications, or include in a
+distribution (as in an @file{INSTALL} file).
+
address@hidden Navigation links, omitting
+For HTML output, likewise omit menus. And if @samp{--no-split} is also
+specified, do not include a navigation links at the top of each node
+(these are never included in the default case of split output).
address@hidden html}.
+
+In both cases, write to standard output by default (can still be
+overridden by @option{-o}).
+
address@hidden --no-split
address@hidden --no-split
address@hidden Splitting of output files
address@hidden Output file splitting
+Suppress the splitting stage of @code{makeinfo}. By default, large
+output files (where the size is greater than 70k bytes) are split into
+smaller subfiles. For Info output, each one is approximately 50k bytes.
+For HTML output, each file contains one node (@pxref{makeinfo html}).
+
address@hidden --no-pointer-validate
address@hidden --no-validate
address@hidden --no-pointer-validate
address@hidden --no-validate
address@hidden Pointer validation, suppressing
+Suppress the pointer-validation phase of @code{makeinfo}. This can also
+be done with the @code{@@novalidate} command (@pxref{Use TeX,,Use
address@hidden). Normally, after a Texinfo file is processed, some consistency
+checks are made to ensure that cross references can be resolved, etc.
address@hidden Validation}.
+
address@hidden --no-warn
address@hidden --no-warn
+Suppress warning messages (but @emph{not} error messages). You might
+want this if the file you are creating has examples of Texinfo cross
+references within it, and the nodes that are referenced do not actually
+exist.
+
address@hidden --number-sections
address@hidden --number-sections
+Output chapter, section, and appendix numbers as in printed manuals.
+
address@hidden --no-number-footnotes
address@hidden --no-number-footnotes
+Suppress automatic footnote numbering. By default, @code{makeinfo}
+numbers each footnote sequentially in a single node, resetting the
+current footnote number to 1 at the start of each node.
+
address@hidden address@hidden
address@hidden -o @var{file}
address@hidden address@hidden
address@hidden -o @var{file}
+Specify that the output should be directed to @var{file} and not to the
+file name specified in the @code{@@setfilename} command found in the
+Texinfo source (@pxref{setfilename}). If @var{file} is @samp{-}, output
+goes to standard output and @samp{--no-split} is implied. For split
+HTML output, @var{file} is the name for the directory into which all
+HTML nodes are written (@pxref{makeinfo html}).
+
address@hidden -P @var{dir}
address@hidden -P @var{dir}
+Prepend @var{dir} to the directory search list for @code{@@include}.
+If @var{dir} is not given, the current directory @file{.} is prepended.
+See @samp{-I} for more details.
+
address@hidden address@hidden
address@hidden -p @var{indent}
address@hidden address@hidden
address@hidden -p @var{indent}
+Set the paragraph indentation style to @var{indent}. The value set by
+this option overrides the value set in a Texinfo file by an
address@hidden@@paragraphindent} command (@pxref{paragraphindent}). The value
+of @var{indent} is interpreted as follows:
+
address@hidden @asis
address@hidden @samp{asis}
+Preserve any existing indentation at the starts of paragraphs.
+
address@hidden @samp{0} or @samp{none}
+Delete any existing indentation.
+
address@hidden @var{num}
+Indent each paragraph by @var{num} spaces.
address@hidden table
+
address@hidden address@hidden
address@hidden -r @var{limit}
address@hidden address@hidden
address@hidden -r @var{limit}
+Set the value of the number of references to a node that
address@hidden will make without reporting a warning. If a node has more
+than this number of references in it, @code{makeinfo} will make the
+references but also report a warning. The default is 1000.
+
address@hidden -U @var{var}
+Cause @var{var} to be undefined. This is equivalent to
address@hidden@@clear @var{var}} in the Texinfo file (@pxref{set clear value}).
+
address@hidden --verbose
address@hidden --verbose
+Cause @code{makeinfo} to display messages saying what it is doing.
+Normally, @code{makeinfo} only outputs messages if there are errors or
+warnings.
+
address@hidden --version
address@hidden -V
address@hidden --version
address@hidden -V
+Print the version number, then exit successfully.
+
address@hidden --xml
address@hidden --xml
+Generate XML output rather than Info.
+
address@hidden table
+
+
address@hidden Pointer Validation
address@hidden Pointer Validation
address@hidden Pointer validation with @code{makeinfo}
address@hidden Validation of pointers
+
+If you do not suppress pointer validation with the @samp{--no-validate}
+option or the @code{@@novalidate} command in the source file (@pxref{Use
+TeX,,Use @TeX{}}), @code{makeinfo} will check the validity of the final
+Info file. Mostly, this means ensuring that nodes you have referenced
+really exist. Here is a complete list of what is checked:
+
address@hidden
address@hidden
+If a `Next', `Previous', or `Up' node reference is a reference to a
+node in the current file and is not an external reference such as to
address@hidden(dir)}, then the referenced node must address@hidden
+
address@hidden
+In every node, if the `Previous' node is different from the `Up' node,
+then the node pointed to by the `Previous' field must have a `Next'
+field which points back to this address@hidden
+
address@hidden
+Every node except the `Top' node must have an `Up' address@hidden
+
address@hidden
+The node referenced by an `Up' pointer must itself reference the current
+node through a menu item, unless the node referenced by `Up'
+has the form `(@var{file})'.
+
address@hidden
+If the `Next' reference of a node is not the same as the `Next' reference
+of the `Up' reference, then the node referenced by the `Next' pointer
+must have a `Previous' pointer that points back to the current node.
+This rule allows the last node in a section to point to the first node
+of the next address@hidden
+
address@hidden
+Every node except `Top' should be referenced by at least one other node,
+either via the `Previous' or `Next' links, or via a menu or a
address@hidden
address@hidden enumerate
+
address@hidden @@-commands in @@node, limited support
+Some Texinfo documents might fail during the validation phase because
+they use commands like @code{@@value} and @code{@@definfoenclose} in
+node definitions and cross-references inconsistently. Consider the
+following example:
+
address@hidden
address@hidden
+@@set nodename Node 1
+
+@@node @@address@hidden@}, Node 2, Top, Top
+
+This is node 1.
+
+@@node Node 2, , Node 1, Top
+
+This is node 2.
address@hidden group
address@hidden example
+
address@hidden
+Here, the node ``Node 1'' was referenced both verbatim and through
address@hidden@@value}.
+
+By default, @code{makeinfo} fails such cases, because node names are not
+fully expanded until they are written to the output file. You should
+always try to reference nodes consistently; e.g., in the above example,
+the second @code{@@node} line should have also used @code{@@value}.
+However, if, for some reason, you @emph{must} reference node names
+inconsistently, and @code{makeinfo} fails to validate the file, you can
+use the @samp{--commands-in-node-names} option to force @code{makeinfo}
+to perform the expensive expansion of all node names it finds in the
+document. This might considerably slow down the program, though;
+twofold increase in conversion time was measured for large documents
+such as the Jargon file.
+
address@hidden @@value in @@node lines
+The support for @code{@@}-commands in @code{@@node} directives is not
+general enough to be freely used. For example, if the example above
+redefined @code{nodename} somewhere in the document, @code{makeinfo}
+will fail to convert it, even if invoked with the
address@hidden option.
+
address@hidden has no effect if the @samp{--no-validate}
+option is given.
+
+
address@hidden makeinfo in Emacs
address@hidden Running @code{makeinfo} inside Emacs
address@hidden Running @code{makeinfo} in Emacs
address@hidden @code{makeinfo} inside Emacs
address@hidden Shell, running @code{makeinfo} in
+
+You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the
address@hidden or the @code{makeinfo-buffer} commands. In
+Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c
+C-m C-b} by address@hidden
+
address@hidden @kbd
address@hidden C-c C-m C-r
address@hidden M-x makeinfo-region
+Format the current region for address@hidden
address@hidden makeinfo-region
+
address@hidden C-c C-m C-b
address@hidden M-x makeinfo-buffer
+Format the current buffer for address@hidden
address@hidden makeinfo-buffer
address@hidden table
+
+When you invoke either @code{makeinfo-region} or
address@hidden, Emacs prompts for a file name, offering the
+name of the visited file as the default. You can edit the default
+file name in the minibuffer if you wish, before pressing @key{RET} to
+start the @code{makeinfo} address@hidden
+
+The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands
+run the @code{makeinfo} program in a temporary shell buffer. If
address@hidden finds any errors, Emacs displays the error messages in
+the temporary address@hidden
+
address@hidden Errors, parsing
address@hidden Parsing errors
address@hidden next-error
+You can parse the error messages by typing @kbd{C-x `}
+(@code{next-error}). This causes Emacs to go to and position the
+cursor on the line in the Texinfo source that @code{makeinfo} thinks
+caused the error. @xref{Compilation, , Running @code{make} or
+Compilers Generally, emacs, The GNU Emacs Manual}, for more
+information about using the @code{next-error} address@hidden
+
+In addition, you can kill the shell in which the @code{makeinfo}
+command is running or make the shell buffer display its most recent
address@hidden
+
address@hidden @kbd
address@hidden C-c C-m C-k
address@hidden M-x makeinfo-kill-job
address@hidden makeinfo-kill-job
+Kill the current running @code{makeinfo} job
+(from @code{makeinfo-region} or @code{makeinfo-buffer})address@hidden
+
address@hidden C-c C-m C-l
address@hidden M-x makeinfo-recenter-output-buffer
address@hidden makeinfo-recenter-output-buffer
+Redisplay the @code{makeinfo} shell buffer to display its most recent
address@hidden
address@hidden table
+
address@hidden
+(Note that the parallel commands for killing and recentering a @TeX{}
+job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode
+Printing}.)@refill
+
+You can specify options for @code{makeinfo} by setting the
address@hidden variable with either the @kbd{M-x
+edit-options} or the @kbd{M-x set-variable} command, or by setting the
+variable in your @file{.emacs} initialization address@hidden
+
+For example, you could write the following in your @file{.emacs} file:@refill
+
address@hidden
address@hidden
+(setq makeinfo-options
+ "--paragraph-indent=0 --no-split
+ --fill-column=70 --verbose")
address@hidden group
address@hidden example
+
address@hidden If you write these three cross references using xref, you see
address@hidden three references to the same named manual, which looks strange.
address@hidden
+For more information, address@hidden
address@hidden Options, , Editing Variable Values, emacs, The GNU Emacs
Manual},@*
address@hidden, , Examining and Setting Variables, emacs, The GNU Emacs
Manual},@*
address@hidden File, , , emacs, The GNU Emacs Manual}, address@hidden
address@hidden options, , Options for @code{makeinfo}}.
+
address@hidden texinfo-format commands
address@hidden node-name, next, previous, up
address@hidden The @address@hidden Commands
address@hidden texinfo-format-region
address@hidden texinfo-format-buffer
+
+In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
+file with the @code{texinfo-format-region} command. This formats the
+current region and displays the formatted text in a temporary buffer
+called @samp{*Info address@hidden
+
+Similarly, you can format a buffer with the
address@hidden command. This command creates a new
+buffer and generates the Info file in it. Typing @kbd{C-x C-s} will
+save the Info file under the name specified by the
address@hidden@@setfilename} line which must be near the beginning of the
+Texinfo address@hidden
+
address@hidden @kbd
address@hidden C-c C-e C-r
address@hidden @code{texinfo-format-region}
+Format the current region for Info.
address@hidden texinfo-format-region
+
address@hidden C-c C-e C-b
address@hidden @code{texinfo-format-buffer}
+Format the current buffer for Info.
address@hidden texinfo-format-buffer
address@hidden table
+
+The @code{texinfo-format-region} and @code{texinfo-format-buffer}
+commands provide you with some error checking, and other functions can
+provide you with further help in finding formatting errors. These
+procedures are described in an appendix; see @ref{Catching Mistakes}.
+However, the @code{makeinfo} program is often faster and
+provides better error checking (@pxref{makeinfo in Emacs})address@hidden
+
address@hidden Batch Formatting
address@hidden node-name, next, previous, up
address@hidden Batch Formatting
address@hidden Batch formatting for Info
address@hidden Info batch formatting
+
+You can format Texinfo files for Info using @code{batch-texinfo-format}
+and Emacs Batch mode. You can run Emacs in Batch mode from any shell,
+including a shell inside of Emacs. (@xref{Command Switches, , Command
+Line Switches and Arguments, emacs, The GNU Emacs Manual}.)@refill
+
+Here is a shell command to format all the files that end in
address@hidden in the current directory:
+
address@hidden
+emacs -batch -funcall batch-texinfo-format *.texinfo
address@hidden example
+
address@hidden
+Emacs processes all the files listed on the command line, even if an
+error occurs while attempting to format some of address@hidden
+
+Run @code{batch-texinfo-format} only with Emacs in Batch mode as shown;
+it is not interactive. It kills the Batch mode Emacs on address@hidden
+
address@hidden is convenient if you lack @code{makeinfo}
+and want to format several Texinfo files at once. When you use Batch
+mode, you create a new Emacs process. This frees your current Emacs, so
+you can continue working in it. (When you run
address@hidden or @code{texinfo-format-buffer}, you cannot
+use that Emacs for anything else until the command finishes.)@refill
+
address@hidden Tag and Split Files
address@hidden node-name, next, previous, up
address@hidden Tag Files and Split Files
address@hidden Making a tag table automatically
address@hidden Tag table, making automatically
+
+If a Texinfo file has more than 30,000 bytes,
address@hidden automatically creates a tag table
+for its Info file; @code{makeinfo} always creates a tag table. With
+a @dfn{tag table}, Info can jump to new nodes more quickly than it can
address@hidden
+
address@hidden Indirect subfiles
+In addition, if the Texinfo file contains more than about 70,000
+bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the
+large Info file into shorter @dfn{indirect} subfiles of about 50,000
+bytes each. Big files are split into smaller files so that Emacs does
+not need to make a large buffer to hold the whole of a large Info
+file; instead, Emacs allocates just enough memory for the small, split-off
+file that is needed at the time. This way, Emacs avoids wasting
+memory when you run Info. (Before splitting was implemented, Info
+files were always kept short and @dfn{include files} were designed as
+a way to create a single, large printed manual out of the smaller Info
+files. @xref{Include Files}, for more information. Include files are
+still used for very large documents, such as @cite{The Emacs Lisp
+Reference Manual}, in which each chapter is a separate file.)@refill
+
+When a file is split, Info itself makes use of a shortened version of
+the original file that contains just the tag table and references to
+the files that were split off. The split-off files are called
address@hidden address@hidden
+
+The split-off files have names that are created by appending @address@hidden,
address@hidden@samp{-2}}, @address@hidden and so on to the file name specified
by the
address@hidden@@setfilename} command. The shortened version of the original
file
+continues to have the name specified by @code{@@address@hidden
+
+At one stage in writing this document, for example, the Info file was saved
+as the file @file{test-texinfo} and that file looked like this:@refill
+
address@hidden
address@hidden
+Info file: test-texinfo, -*-Text-*-
+produced by texinfo-format-buffer
+from file: new-texinfo-manual.texinfo
+
+^_
+Indirect:
+test-texinfo-1: 102
+test-texinfo-2: 50422
address@hidden group
address@hidden
+test-texinfo-3: 101300
+^_^L
+Tag table:
+(Indirect)
+Node: overview^?104
+Node: info file^?1271
address@hidden group
address@hidden
+Node: printed manual^?4853
+Node: conventions^?6855
address@hidden
address@hidden group
address@hidden example
+
address@hidden
+(But @file{test-texinfo} had far more nodes than are shown here.) Each of
+the split-off, indirect files, @file{test-texinfo-1},
address@hidden, and @file{test-texinfo-3}, is listed in this file
+after the line that says @samp{Indirect:}. The tag table is listed after
+the line that says @samp{Tag table:}. @refill
+
+In the list of indirect files, the number following the file name
+records the cumulative number of bytes in the preceding indirect files,
+not counting the file list itself, the tag table, or the permissions
+text in each file. In the tag table, the number following the node name
+records the location of the beginning of the node, in bytes from the
+beginning of the (unsplit) output.
+
+If you are using @code{texinfo-format-buffer} to create Info files,
+you may want to run the @code{Info-validate} command. (The
address@hidden command does such a good job on its own, you do not
+need @code{Info-validate}.) However, you cannot run the @kbd{M-x
+Info-validate} node-checking command on indirect files. For
+information on how to prevent files from being split and how to
+validate the structure of the nodes, see @ref{Using
address@hidden
+
+
address@hidden makeinfo html
address@hidden Generating HTML
address@hidden HTML
+
+Besides generating output in the Info format, you can use the
address@hidden option to generate output in HTML format, for installation
+on a web site (for example). By default, the HTML output is split at
+node level.
+
+When splitting, the HTML output files are written into a subdirectory.
+The subdirectory is named according to the name from
address@hidden@@setfilename} with any extension removed; for example, HTML
+output for @code{@@setfilename emacs.info} would be written into a
+subdirectory named @samp{emacs}. If that directory cannot be created
+for any reason, then @samp{.html} is appended to the directory name, as
+in @samp{emacs.html} (this is necessary because sometimes the info file
+is named without an extension, e.g., @samp{texinfo}). If the
address@hidden@var{name}.html} directory can't be created either,
address@hidden gives up. In any case, the top-level output file within
+the directory is always named @samp{index.html}.
+
+Monolithic output (@code{--no-split}) is named according to
address@hidden@@setfilename} or @code{--outfile}. Cross-document node
+references are not supported in monolithic HTML.
+
+Texinfo input marked up with the @code{@@ifhtml} command will produce
+output only with the @samp{--html} option supplied. Input marked up
+with the @code{@@html} is passed literally to the output (suppressing
+the normal escaping of input @samp{<}, @samp{>} and @samp{&} characters
+which have special significance in HTML).
+
+The @samp{--footnote-style} option is currently ignored for HTML output;
+footnotes are linked to the end of the output file.
+
+The HTML generated is mostly standard (i.e., HTML 2.0, RFC-1866). The
+exception is that HTML 3.2 tables are generated from the
address@hidden@@multitable} command, but tagged to degrade as well as possible
+in browsers without table support. The HTML 4 @samp{lang} attribute on
+the @samp{<html>} attribute is also used. Please report output from an
+error-free run of @code{makeinfo} which has browser portability problems
+as a bug.
+
+Navigation bars are inserted at the start of nodes, similarly to Info
+output. The @samp{--no-headers} option will suppress this if used with
address@hidden Header @code{<link>} elements in split output can
+support info-like navigation with browsers like Lynx and @w{Emacs W3}
+which implement this @w{HTML 1.0} feature. @samp{@@xref} commands to
+other documents are generated assuming the other document is available
+in split HTML form, and installed in the same HTML documentation tree,
+at @file{../<info-document>/}.
+
+
address@hidden Installing an Info File
address@hidden Installing an Info File
address@hidden Installing an Info file
address@hidden Info file installation
address@hidden @file{dir} directory for Info installation
+
+Info files are usually kept in the @file{info} directory. You can read
+Info files using the standalone Info program or the Info reader built
+into Emacs. (@inforef{Top, info, info}, for an introduction to Info.)
+
address@hidden
+* 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 install-info:: @code{install-info} options.
address@hidden menu
+
+
address@hidden Directory File
address@hidden The Directory File @file{dir}
+
+For Info to work, the @file{info} directory must contain a file that
+serves as a top level directory for the Info system. By convention,
+this file is called @file{dir}. (You can find the location of this file
+within Emacs by typing @kbd{C-h i} to enter Info and then typing
address@hidden C-f} to see the pathname to the @file{info} directory.)
+
+The @file{dir} file is itself an Info file. It contains the top level
+menu for all the Info files in the system. The menu looks like
+this:@refill
+
address@hidden
address@hidden
+* Menu:
+* Info: (info). Documentation browsing system.
+* Emacs: (emacs). The extensible, self-documenting
+ text editor.
+* Texinfo: (texinfo). With one source file, make
+ either a printed manual using
+ @@address@hidden@} or an Info file.
address@hidden
address@hidden group
address@hidden example
+
+Each of these menu entries points to the `Top' node of the Info file
+that is named in parentheses. (The menu entry does not need to
+specify the `Top' node, since Info goes to the `Top' node if no node
+name is mentioned. @xref{Other Info Files, , Nodes in Other Info
+Files}.)@refill
+
+Thus, the @samp{Info} entry points to the `Top' node of the
address@hidden file and the @samp{Emacs} entry points to the `Top' node
+of the @file{emacs} address@hidden
+
+In each of the Info files, the `Up' pointer of the `Top' node refers
+back to the @code{dir} file. For example, the line for the `Top'
+node of the Emacs manual looks like this in Info:@refill
+
address@hidden
+File: emacs Node: Top, Up: (DIR), Next: Distrib
address@hidden example
+
address@hidden
+In this case, the @file{dir} file name is written in upper case
+letters---it can be written in either upper or lower case. This is not
+true in general, it is a special case for @file{dir}.
+
+
address@hidden New Info File
address@hidden Listing a New Info File
address@hidden Adding a new Info file
address@hidden Listing a new Info file
address@hidden New Info file, listing it in @file{dir} file
address@hidden Info file, listing a new
address@hidden @file{dir} file listing
+
+To add a new Info file to your system, you must write a menu entry to
+add to the menu in the @file{dir} file in the @file{info} directory.
+For example, if you were adding documentation for GDB, you would write
+the following new entry:@refill
+
address@hidden
+* GDB: (gdb). The source-level C debugger.
address@hidden example
+
address@hidden
+The first part of the menu entry is the menu entry name, followed by a
+colon. The second part is the name of the Info file, in parentheses,
+followed by a period. The third part is the description.
+
+The name of an Info file often has a @file{.info} extension. Thus, the
+Info file for GDB might be called either @file{gdb} or @file{gdb.info}.
+The Info reader programs automatically try the file name both with and
+without @address@hidden MS-DOS/MS-Windows systems, Info will
+try the @file{.inf} extension as well.}; so it is better to avoid
+clutter and not to write @samp{.info} explicitly in the menu entry. For
+example, the GDB menu entry should use just @samp{gdb} for the file
+name, not @samp{gdb.info}.
+
+
address@hidden Other Info Directories
address@hidden Info Files in Other Directories
address@hidden Installing Info in another directory
address@hidden Info installed in another directory
address@hidden Another Info directory
address@hidden @file{dir} files and Info directories
+
+If an Info file is not in the @file{info} directory, there are three
+ways to specify its location:@refill
+
address@hidden
address@hidden
+Write the pathname in the @file{dir} file as the second part of the menu.
+
address@hidden
+If you are using Emacs, list the name of the file in a second @file{dir}
+file, in its directory; and then add the name of that directory to the
address@hidden variable in your personal or site
+initialization file.
+
+This variable tells Emacs where to look for @file{dir} files (the files
+must be named @file{dir}). Emacs merges the files named @file{dir} from
+each of the listed directories. (In Emacs version 18, you can set the
address@hidden variable to the name of only one
+directory.)@refill
+
address@hidden
+Specify the Info directory name in the @code{INFOPATH} environment
+variable in your @file{.profile} or @file{.cshrc} initialization file.
+(Only you and others who set this environment variable will be able to
+find Info files whose location is specified this way.)
address@hidden enumerate
+
+For example, to reach a test file in the @file{/home/bob/info}
+directory, you could add an entry like this to the menu in the
+standard @file{dir} file:@refill
+
address@hidden
+* Test: (/home/bob/info/info-test). Bob's own test file.
address@hidden example
+
address@hidden
+In this case, the absolute file name of the @file{info-test} file is
+written as the second part of the menu address@hidden
+
+Alternatively, you could write the following in your @file{.emacs} file:
+
address@hidden Info-directory-list
address@hidden
address@hidden
+(require 'info)
+(setq Info-directory-list
+ (cons (expand-file-name "/home/bob/info")
+ Info-directory-list))
address@hidden group
address@hidden example
+
+This tells Emacs to merge the system @file{dir} file with the @file{dir}
+file in @file{/home/bob/info}. Thus, Info will list the
address@hidden/home/bob/info/info-test} file as a menu entry in the
address@hidden/home/bob/info/dir} file. Emacs does the merging only when
address@hidden info} is first run, so if you want to set
address@hidden in an Emacs session where you've already run
address@hidden, you must @code{(setq Info-dir-contents nil)} to force Emacs
+to recompose the @file{dir} file.
+
address@hidden INFOPATH
+Finally, you can tell Info where to look by setting the @code{INFOPATH}
+environment variable in your shell startup file, such as @file{.cshrc},
address@hidden or @file{autoexec.bat}. If you use a Bourne-compatible
+shell such as @code{sh} or @code{bash} for your shell command
+interpreter, you set the @code{INFOPATH} environment variable in the
address@hidden initialization file; but if you use @code{csh} or
address@hidden, you set the variable in the @file{.cshrc} initialization
+file. On MS-DOS/MS-Windows systems, you must set @code{INFOPATH} in
+your @file{autoexec.bat} file or in the Registry. Each type of shell
+uses a different syntax.
+
address@hidden @bullet
address@hidden
+In a @file{.cshrc} file, you could set the @code{INFOPATH}
+variable as follows:@refill
+
address@hidden
+setenv INFOPATH .:~/info:/usr/local/emacs/info
address@hidden smallexample
+
address@hidden
+In a @file{.profile} file, you would achieve the same effect by
+writing:@refill
+
address@hidden
+INFOPATH=.:$HOME/info:/usr/local/emacs/info
+export INFOPATH
address@hidden smallexample
+
address@hidden
address@hidden autoexec.bat
+In a @file{autoexec.bat} file, you write this address@hidden the
+use of @samp{;} as the directory separator, and a different syntax for
+using values of other environment variables.}:
+
address@hidden
+set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info
address@hidden smallexample
address@hidden itemize
+
address@hidden
+The @samp{.} indicates the current directory as usual. Emacs uses the
address@hidden environment variable to initialize the value of Emacs's
+own @code{Info-directory-list} variable. The stand-alone Info reader
+merges any files named @file{dir} in any directory listed in the
address@hidden variable into a single menu presented to you in the node
+called @samp{(dir)Top}.
+
address@hidden colon, last in @env{INFOPATH}
+However you set @env{INFOPATH}, if its last character is a
address@hidden MS-DOS/MS-Windows systems, use semi-colon instead.}, this
+is replaced by the default (compiled-in) path. This gives you a way to
+augment the default path with new directories without having to list all
+the standard places. For example (using @code{sh} syntax):
+
address@hidden
+INFOPATH=/local/info:
+export INFOPATH
address@hidden example
+
address@hidden
+will search @file{/local/info} first, then the standard directories.
+Leading or doubled colons are not treated specially.
+
address@hidden @file{dir} file, creating your own
+When you create your own @file{dir} file for use with
address@hidden or @env{INFOPATH}, it's easiest to start by
+copying an existing @file{dir} file and replace all the text after the
address@hidden Menu:} with your desired entries. That way, the punctuation and
+special CTRL-_ characters that Info needs will be present.
+
+
address@hidden Installing Dir Entries
address@hidden Installing Info Directory Files
+
+When you install an Info file onto your system, you can use the program
address@hidden to update the Info directory file @file{dir}.
+Normally the makefile for the package runs @code{install-info}, just
+after copying the Info file into its proper installed location.
+
address@hidden dircategory
address@hidden direntry
+In order for the Info file to work with @code{install-info}, you include
+the commands @code{@@dircategory} and
address@hidden@@address@hidden@code{@@end direntry} in the Texinfo source
+file. Use @code{@@direntry} to specify the menu entries to add to the
+Info directory file, and use @code{@@dircategory} to specify which part
+of the Info directory to put it in. Here is how these commands are used
+in this manual:
+
address@hidden
+@@dircategory Texinfo documentation system
+@@direntry
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. @dots{}
address@hidden
+@@end direntry
address@hidden smallexample
+
+Here's what this produces in the Info file:
+
address@hidden
+INFO-DIR-SECTION Texinfo documentation system
+START-INFO-DIR-ENTRY
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. @dots{}
address@hidden
+END-INFO-DIR-ENTRY
address@hidden smallexample
+
address@hidden
+The @code{install-info} program sees these lines in the Info file, and
+that is how it knows what to do.
+
+Always use the @code{@@direntry} and @code{@@dircategory} commands near
+the beginning of the Texinfo input, before the first @code{@@node}
+command. If you use them later on in the input, @code{install-info}
+will not notice them.
+
+If you use @code{@@dircategory} more than once in the Texinfo source,
+each usage specifies the `current' category; any subsequent
address@hidden@@direntry} commands will add to that category.
+
+Here are some recommended @code{@@dircategory} categories:
+
address@hidden
+GNU packages
+GNU programming tools
+GNU programming documentation
+GNU Emacs Lisp
+GNU libraries
+TeX
+Individual utilities
address@hidden display
+
+The idea is to include the `Invoking' node for every program installed
+by a package under `Individual utilities', and an entry for the manual
+as a whole in the appropriate other category.
+
+
address@hidden Invoking install-info
address@hidden Invoking install-info
+
address@hidden install-info
+
address@hidden inserts menu entries from an Info file into the
+top-level @file{dir} file in the Info system (see the previous sections
+for an explanation of how the @file{dir} file works). It's most often
+run as part of software installation, or when constructing a @file{dir} file
+for all manuals on a system. Synopsis:
+
address@hidden
+install-info address@hidden@dots{} address@hidden address@hidden
address@hidden example
+
+If @var{info-file} or @var{dir-file} are not specified, the options
+(described below) that define them must be. There are no compile-time
+defaults, and standard input is never used. @code{install-info} can
+read only one Info file and write only one @file{dir} file per invocation.
+
address@hidden @file{dir}, created by @code{install-info}
+If @var{dir-file} (however specified) does not exist,
address@hidden creates it if possible (with no entries).
+
address@hidden Compressed files, reading
address@hidden Dir files, compressed
+If any input file is compressed with @code{gzip} (@pxref{Invoking
+gzip,,,gzip, Gzip}), @code{install-info} automatically uncompresses it
+for reading. And if @var{dir-file} is compressed, @code{install-info}
+also automatically leaves it compressed after writing any changes.
+If @var{dir-file} itself does not exist, @code{install-info} tries to
+open @address@hidden
+
+Options:
+
address@hidden @code
address@hidden --delete
address@hidden --delete
+Delete the entries in @var{info-file} from @var{dir-file}. The file
+name in the entry in @var{dir-file} must be @var{info-file} (except for
+an optional @samp{.info} in either one). Don't insert any new entries.
+
address@hidden address@hidden
address@hidden -d @var{name}
address@hidden address@hidden
address@hidden -d @var{name}
+Specify file name of the Info directory file. This is equivalent to
+using the @var{dir-file} argument.
+
address@hidden address@hidden
address@hidden -e @var{text}
address@hidden address@hidden
address@hidden -e @var{text}
+Insert @var{text} as an Info directory entry; @var{text} should have the
+form of an Info menu item line plus zero or more extra lines starting
+with whitespace. If you specify more than one entry, they are all
+added. If you don't specify any entries, they are determined from
+information in the Info file itself.
+
address@hidden --help
address@hidden -h
address@hidden --help
address@hidden -h
+Display a usage message listing basic usage and all available options,
+then exit successfully.
+
address@hidden address@hidden
address@hidden -i @var{file}
address@hidden address@hidden
address@hidden -i @var{file}
+Specify Info file to install in the directory.
+Equivalent to using the @var{info-file} argument.
+
address@hidden address@hidden
address@hidden -D @var{dir}
address@hidden address@hidden
address@hidden -D @var{dir}
+Specify the directory where @file{dir} resides.
+Equivalent to @address@hidden/dir}.
+
address@hidden address@hidden
address@hidden address@hidden
+Same as @address@hidden An Info directory entry is actually
+a menu item.
+
address@hidden --quiet
address@hidden --quiet
+Suppress warnings.
+
address@hidden --remove
address@hidden -r
address@hidden --remove
address@hidden -r
+Same as @samp{--delete}.
+
address@hidden address@hidden
address@hidden -s @var{sec}
address@hidden address@hidden
address@hidden -s @var{sec}
+Put this file's entries in section @var{sec} of the directory. If you
+specify more than one section, all the entries are added in each of the
+sections. If you don't specify any sections, they are determined from
+information in the Info file itself.
+
address@hidden --version
address@hidden -V
address@hidden --version
address@hidden -V
address@hidden version number, finding
+Display version information and exit successfully.
+
address@hidden table
+
+
address@hidden Command List
address@hidden @@-Command List
address@hidden Alphabetical @@-command list
address@hidden List of @@-commands
address@hidden @@-command list
address@hidden Reference to @@-commands
+
+Here is an alphabetical list of the @@-commands in Texinfo. Square
+brackets, @address@hidden address@hidden, indicate optional arguments; an
ellipsis,
address@hidden@dots{}}, indicates repeated text.
+
address@hidden 1
address@hidden @code
address@hidden @@@var{whitespace}
+An @code{@@} followed by a space, tab, or newline produces a normal,
+stretchable, interword space. @xref{Multiple Spaces}.
+
address@hidden @@!
+Generate an exclamation point that really does end a sentence (usually
+after an end-of-sentence capital letter). @xref{Ending a Sentence}.
+
address@hidden @@"
address@hidden @@'
+Generate an umlaut or acute accent, respectively, over the next
+character, as in @"o and @'o. @xref{Inserting Accents}.
+
address@hidden @@*
+Force a line break. Do not end a paragraph that uses @code{@@*} with
+an @code{@@refill} command. @xref{Line Breaks}.
+
address@hidden @@,@address@hidden@}
+Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting
+Accents}.
+
address@hidden @@-
+Insert a discretionary hyphenation point. @xref{- and hyphenation}.
+
address@hidden @@.
+Produce a period that really does end a sentence (usually after an
+end-of-sentence capital letter). @xref{Ending a Sentence}.
+
address@hidden @@:
+Indicate to @TeX{} that an immediately preceding period, question
+mark, exclamation mark, or colon does not end a sentence. Prevent
address@hidden from inserting extra whitespace as it does at the end of a
+sentence. The command has no effect on the Info file output.
address@hidden Ending a Sentence}.
+
address@hidden @@=
+Generate a macron (bar) accent over the next character, as in @=o.
address@hidden Accents}.
+
address@hidden @@?
+Generate a question mark that really does end a sentence (usually after
+an end-of-sentence capital letter). @xref{Ending a Sentence}.
+
address@hidden @@@@
+Stands for an at sign, @samp{@@}.
address@hidden Atsigns, , Inserting @@ and braces}.
+
address@hidden @@\
+Stands for a backslash (@samp{\}) inside @code{@@math}.
address@hidden,,@code{math}}.
+
address@hidden @@^
address@hidden @@`
+Generate a circumflex (hat) or grave accent, respectively, over the next
+character, as in @^o and @`e.
address@hidden Accents}.
+
address@hidden @@@{
+Stands for a left brace, @address@hidden
address@hidden Atsigns, , Inserting @@ and braces}.
+
address@hidden @@@}
+Stands for a right-hand brace, @address@hidden@*
address@hidden Atsigns, , Inserting @@ and braces}.
+
address@hidden @@~
+Generate a tilde accent over the next character, as in @~N.
address@hidden Accents}.
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Generate the uppercase and lowercase Scandinavian A-ring letters,
+respectively: @AA{}, @aa{}. @xref{Inserting Accents}.
+
address@hidden @@address@hidden@address@hidden
+Tag @var{abbrev} as an acronym, that is, an abbreviation written in all
+capital letters, such as `NASA'. @xref{acronym,, @code{acronym}}.
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Generate the uppercase and lowercase AE ligatures, respectively:
address@hidden, @ae{}. @xref{Inserting Accents}.
+
address@hidden @@afivepaper
+Change page dimensions for the A5 paper size. @xref{A4 Paper}.
+
address@hidden @@afourlatex
address@hidden @@afourpaper
address@hidden @@afourwide
+Change page dimensions for the A4 paper size. @xref{A4 Paper}.
+
address@hidden @@alias @address@hidden
+Make the command @samp{@@@var{new}} an alias for the existing command
address@hidden@@@var{existing}}. @xref{alias}.
+
address@hidden @@address@hidden@address@hidden
+Define @var{name} as the current location for use as a cross-reference
+target. @xref{anchor,, @code{@@anchor}}.
+
address@hidden @@appendix @var{title}
+Begin an appendix. The title appears in the table
+of contents of a printed manual. In Info, the title is
+underlined with asterisks. @xref{unnumbered & appendix, , The
address@hidden@@unnumbered} and @code{@@appendix} address@hidden
+
address@hidden @@appendixsec @var{title}
address@hidden @@appendixsection @var{title}
+Begin an appendix section within an appendix. The section title appears
+in the table of contents of a printed manual. In Info, the title is
+underlined with equal signs. @code{@@appendixsection} is a longer
+spelling of the @code{@@appendixsec} command. @xref{unnumberedsec
+appendixsec heading, , Section address@hidden
+
address@hidden @@appendixsubsec @var{title}
+Begin an appendix subsection within an appendix. The title appears
+in the table of contents of a printed manual. In Info, the title is
+underlined with hyphens. @xref{unnumberedsubsec appendixsubsec
+subheading, , Subsection address@hidden
+
address@hidden @@appendixsubsubsec @var{title}
+Begin an appendix subsubsection within an appendix subsection. The
+title appears in the table of contents of a printed manual. In Info,
+the title is underlined with periods. @xref{subsubsection,, The
+`subsub' address@hidden
+
address@hidden @@asis
+Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to
+print the table's first column without highlighting (``as is'').
address@hidden Tables, , Making a Two-column address@hidden
+
address@hidden @@author @var{author}
+Typeset @var{author} flushleft and underline it. @xref{title
+subtitle author, , The @code{@@title} and @code{@@author}
address@hidden
+
address@hidden @@address@hidden@address@hidden
+Print @var{text} in @b{bold} font. No effect in Info. @address@hidden
+
+
address@hidden @@address@hidden@}
+Generate a large round dot, or the closest possible
+thing to one. @xref{bullet, , @code{@@address@hidden
+
address@hidden @@bye
+Stop formatting a file. The formatters do not see the contents of a
+file following an @code{@@bye} command. @xref{Ending a address@hidden
+
address@hidden @@c @var{comment}
+Begin a comment in Texinfo. The rest of the line does not appear in
+either the Info file or the printed manual. A synonym for
address@hidden@@comment}. @xref{Comments, , address@hidden
+
address@hidden @@cartouche
+Highlight an example or quotation by drawing a box with rounded
+corners around it. Pair with @code{@@end cartouche}. No effect in
+Info. @xref{cartouche, , Drawing Cartouches Around Examples}.)@refill
+
address@hidden @@center @var{line-of-text}
+Center the line of text following the command.
address@hidden center sp, , @code{@@address@hidden
+
address@hidden @@centerchap @var{line-of-text}
+Like @code{@@chapter}, but centers the chapter title. @xref{chapter,,
address@hidden@@chapter}}.
+
address@hidden @@chapheading @var{title}
+Print a chapter-like heading in the text, but not in the table of
+contents of a printed manual. In Info, the title is underlined with
+asterisks. @xref{majorheading & chapheading, , @code{@@majorheading}
+and @code{@@address@hidden
+
address@hidden @@chapter @var{title}
+Begin a chapter. The chapter title appears in the table of
+contents of a printed manual. In Info, the title is underlined with
+asterisks. @xref{chapter, , @code{@@address@hidden
+
address@hidden @@cindex @var{entry}
+Add @var{entry} to the index of concepts. @xref{Index Entries, ,
+Defining the Entries of an address@hidden
+
address@hidden @@address@hidden@address@hidden
+Highlight the name of a book or other reference that lacks a
+companion Info file. @xref{cite, , @code{@@address@hidden
+
address@hidden @@clear @var{flag}
+Unset @var{flag}, preventing the Texinfo formatting commands from
+formatting text between subsequent pairs of @code{@@ifset @var{flag}}
+and @code{@@end ifset} commands, and preventing
address@hidden@@address@hidden@address@hidden from expanding to the value to
which
address@hidden is set.
address@hidden clear value, , @code{@@set} @code{@@clear} @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Highlight text that is an expression, a syntactically complete token
+of a program, or a program name. @xref{code, , @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate a command name, such as @command{ls}.
address@hidden,, @code{@@command}}.
+
address@hidden @@comment @var{comment}
+Begin a comment in Texinfo. The rest of the line does not appear in
+either the Info file or the printed manual. A synonym for @code{@@c}.
address@hidden
+
address@hidden @@contents
+Print a complete table of contents. Has no effect in Info, which uses
+menus instead. @xref{Contents, , Generating a Table of
address@hidden
+
address@hidden @@address@hidden@}
+Generate a copyright symbol. @xref{copyright symbol, ,
address@hidden@@address@hidden
+
+
address@hidden @@defcodeindex @var{index-name}
+Define a new index and its indexing command. Print entries in an
address@hidden@@code} font. @xref{New Indices, , Defining New
address@hidden
+
address@hidden @@defcv @var{category} @var{class} @var{name}
address@hidden @@defcvx @var{category} @var{class} @var{name}
+Format a description for a variable associated with a class in
+object-oriented programming. Takes three arguments: the category of
+thing being defined, the class to which it belongs, and its name.
address@hidden Commands}, and @ref{deffnx,, Def Cmds in Detail}.
+
address@hidden @@deffn @var{category} @var{name} @address@hidden
address@hidden @@deffnx @var{category} @var{name} @address@hidden
+Format a description for a function, interactive command, or similar
+entity that may take arguments. @code{@@deffn} takes as arguments the
+category of entity being described, the name of this particular
+entity, and its arguments, if any. @xref{Definition address@hidden
+
address@hidden @@defindex @var{index-name}
+Define a new index and its indexing command. Print entries in a roman
+font. @xref{New Indices, , Defining New address@hidden
+
address@hidden @@definfoenclose @var{newcmd}, @var{before}, @var{after},
+Create new @@-command @var{newcmd} for Info that marks text by enclosing
+it in strings that precede and follow the text. @xref{definfoenclose}.
+
address@hidden @@defivar @var{class} @var{instance-variable-name}
address@hidden @@defivarx @var{class} @var{instance-variable-name}
+This command formats a description for an instance variable in
+object-oriented programming. The command is equivalent to @samp{@@defcv
address@hidden address@hidden @dots{}}. @xref{Definition Commands}, and
address@hidden,, Def Cmds in Detail}.
+
address@hidden @@defmac @var{macroname} @address@hidden
address@hidden @@defmacx @var{macroname} @address@hidden
+Format a description for a macro. The command is equivalent to
address@hidden@@deffn Macro @dots{}}. @xref{Definition Commands}, and
address@hidden,, Def Cmds in Detail}.
+
address@hidden @@defmethod @var{class} @var{method-name} @address@hidden
address@hidden @@defmethodx @var{class} @var{method-name} @address@hidden
+Format a description for a method in object-oriented programming. The
+command is equivalent to @samp{@@defop Method @dots{}}. Takes as
+arguments the name of the class of the method, the name of the
+method, and its arguments, if any. @xref{Definition Commands}, and
address@hidden,, Def Cmds in Detail}.
+
address@hidden @@defop @var{category} @var{class} @var{name} @address@hidden
address@hidden @@defopx @var{category} @var{class} @var{name} @address@hidden
+Format a description for an operation in object-oriented programming.
address@hidden@@defop} takes as arguments the overall name of the category of
+operation, the name of the class of the operation, the name of the
+operation, and its arguments, if any. @xref{Definition
+Commands}, and @ref{Abstract Objects}.
+
address@hidden @@defopt @var{option-name}
address@hidden @@defoptx @var{option-name}
+Format a description for a user option. The command is equivalent to
address@hidden@@defvr @{User address@hidden @dots{}}. @xref{Definition
Commands}, and
address@hidden,, Def Cmds in Detail}.
+
address@hidden @@defspec @var{special-form-name} @address@hidden
address@hidden @@defspecx @var{special-form-name} @address@hidden
+Format a description for a special form. The command is equivalent to
address@hidden@@deffn @{Special address@hidden @dots{}}. @xref{Definition
Commands},
+and @ref{deffnx,, Def Cmds in Detail}.
+
address@hidden @@deftp @var{category} @var{name-of-type} @address@hidden
address@hidden @@deftpx @var{category} @var{name-of-type} @address@hidden
+Format a description for a data type. @code{@@deftp} takes as arguments
+the category, the name of the type (which is a word like @samp{int} or
address@hidden), and then the names of attributes of objects of that type.
address@hidden Commands}, and @ref{Data Types}.
+
address@hidden @@deftypefn @var{classification} @var{data-type} @var{name}
@address@hidden
address@hidden @@deftypefnx @var{classification} @var{data-type} @var{name}
@address@hidden
+Format a description for a function or similar entity that may take
+arguments and that is typed. @code{@@deftypefn} takes as arguments the
+classification of entity being described, the type, the name of the
+entity, and its arguments, if any. @xref{Definition Commands}, and
address@hidden,, Def Cmds in Detail}.
+
address@hidden @@deftypefun @var{data-type} @var{function-name} @address@hidden
address@hidden @@deftypefunx @var{data-type} @var{function-name} @address@hidden
+Format a description for a function in a typed language.
+The command is equivalent to @samp{@@deftypefn Function @dots{}}.
address@hidden Commands}, and @ref{deffnx,, Def Cmds in Detail}.
+
address@hidden @@deftypeivar @var{class} @var{data-type} @var{variable-name}
address@hidden @@deftypeivarx @var{class} @var{data-type} @var{variable-name}
+Format a description for a typed instance variable in object-oriented
+programming. @xref{Definition Commands}, and @ref{Abstract Objects}.
+
address@hidden @@deftypemethod @var{class} @var{data-type} @var{method-name}
@address@hidden
address@hidden @@deftypemethodx @var{class} @var{data-type} @var{method-name}
@address@hidden
+Format a description for a typed method in object-oriented programming.
address@hidden Commands}, and @ref{deffnx,, Def Cmds in Detail}.
+
address@hidden @@deftypeop @var{category} @var{class} @var{data-type}
@var{name} @address@hidden
address@hidden @@deftypeopx @var{category} @var{class} @var{data-type}
@var{name} @address@hidden
+Format a description for a typed operation in object-oriented programming.
address@hidden Commands}, and @ref{Abstract Objects}.
+
address@hidden @@deftypevar @var{data-type} @var{variable-name}
address@hidden @@deftypevarx @var{data-type} @var{variable-name}
+Format a description for a variable in a typed language. The command is
+equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition
+Commands}, and @ref{deffnx,, Def Cmds in Detail}.
+
address@hidden @@deftypevr @var{classification} @var{data-type} @var{name}
address@hidden @@deftypevrx @var{classification} @var{data-type} @var{name}
+Format a description for something like a variable in a typed
+language---an entity that records a value. Takes as arguments the
+classification of entity being described, the type, and the name of the
+entity. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in
+Detail}.
+
address@hidden @@defun @var{function-name} @address@hidden
address@hidden @@defunx @var{function-name} @address@hidden
+Format a description for functions. The command is equivalent to
address@hidden@@deffn Function @dots{}}. @xref{Definition Commands}, and
address@hidden,, Def Cmds in Detail}.
+
address@hidden @@defvar @var{variable-name}
address@hidden @@defvarx @var{variable-name}
+Format a description for variables. The command is equivalent to
address@hidden@@defvr Variable @dots{}}. @xref{Definition Commands}, and
address@hidden,, Def Cmds in Detail}.
+
address@hidden @@defvr @var{category} @var{name}
address@hidden @@defvrx @var{category} @var{name}
+Format a description for any kind of variable. @code{@@defvr} takes
+as arguments the category of the entity and the name of the entity.
address@hidden Commands},
+and @ref{deffnx,, Def Cmds in Detail}.
+
address@hidden @@detailmenu
+Avoid @code{makeinfo} confusion stemming from the detailed node listing
+in a master menu. @xref{Master Menu Parts}.
+
address@hidden @@address@hidden@address@hidden
+Highlight the introductory or defining use of a term.
address@hidden, , @code{@@address@hidden
+
address@hidden @@dircategory @var{dirpart}
+Specify a part of the Info directory menu where this file's entry should
+go. @xref{Installing Dir Entries}.
+
address@hidden @@direntry
+Begin the Info directory menu entry for this file. Pair with
address@hidden@@end direntry}. @xref{Installing Dir Entries}.
+
address@hidden @@display
+Begin a kind of example. Like @code{@@example} (indent text, do not
+fill), but do not select a new font. Pair with @code{@@end display}.
address@hidden, , @code{@@display}}.
+
address@hidden @@address@hidden@address@hidden
+Format a unit of measure, as in address@hidden Causes @TeX{} to insert a
+thin space before @var{dimension}. No effect in Info.
address@hidden, , @code{@@dmn}}.
+
address@hidden @@documentdescription
+Set the document description text, included in the HTML output. Pair
+with @code{@@end documentdescription}. @xref{documentdescription,,
address@hidden@@documentdescription}}.
+
address@hidden @@documentencoding @var{enc}
+Declare the input encoding to be @var{enc}.
address@hidden,, @code{@@documentencoding}}.
+
address@hidden @@documentlanguage @var{CC}
+Declare the document language as the two-character ISO-639 abbreviation
address@hidden @xref{documentlanguage,, @code{@@documentlanguage}}.
+
address@hidden @@address@hidden@address@hidden
+Generate a dot accent over the character @var{c}, as in @dotaccent{o}.
address@hidden Accents}.
+
address@hidden @@address@hidden@}
+Insert an ellipsis: @address@hidden
address@hidden, , @code{@@address@hidden
+
address@hidden @@address@hidden@var{address}[, @address@hidden
+Indicate an electronic mail address.
address@hidden, , @code{@@email}}.
+
address@hidden @@address@hidden@address@hidden
+Highlight @var{text}; text is displayed in @emph{italics} in printed
+output, and surrounded by asterisks in Info. @xref{Emphasis, ,
+Emphasizing Text}.
+
address@hidden @@end @var{environment}
+Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting
+Commands,,@@-commands}.
+
address@hidden @@address@hidden@address@hidden
+Indicate an environment variable name, such as @env{PATH}.
address@hidden,, @code{@@env}}.
+
address@hidden @@address@hidden@}
+Generate an end-of-sentence of ellipsis, like this @enddots{}
address@hidden,,@code{@@address@hidden@}}}.
+
address@hidden @@enumerate address@hidden
+Begin a numbered list, using @code{@@item} for each entry.
+Optionally, start list with @var{number-or-letter}. Pair with
address@hidden@@end enumerate}. @xref{enumerate, ,
address@hidden@@address@hidden
+
address@hidden @@address@hidden@}
+Indicate to the reader the exact equivalence of two forms with a
+glyph: @address@hidden @address@hidden
+
address@hidden @@address@hidden@}
+Indicate to the reader with a glyph that the following text is
+an error message: @address@hidden @xref{Error address@hidden
+
address@hidden @@evenfooting address@hidden @@| address@hidden @@|
address@hidden
address@hidden @@evenheading address@hidden @@| address@hidden @@|
address@hidden
+Specify page footings resp.@: headings for even-numbered (left-hand)
+pages. @xref{Custom Headings, ,
+How to Make Your Own address@hidden
+
address@hidden @@everyfooting address@hidden @@| address@hidden @@|
address@hidden
address@hidden @@everyheading address@hidden @@| address@hidden @@|
address@hidden
+Specify page footings resp.@: headings for every page. Not relevant to
+Info. @xref{Custom Headings, , How to Make Your Own address@hidden
+
address@hidden @@example
+Begin an example. Indent text, do not fill, and select fixed-width font.
+Pair with @code{@@end example}. @xref{example, ,
address@hidden@@address@hidden
+
address@hidden @@exampleindent @var{indent}
+Indent example-like environments by @var{indent} number of spaces
+(perhaps 0). @xref{exampleindent,, Paragraph Indenting}.
+
address@hidden @@address@hidden@}
+Produce an upside-down exclamation point. @xref{Inserting Accents}.
+
address@hidden @@exdent @var{line-of-text}
+Remove any indentation a line might have. @xref{exdent, ,
+Undoing the Indentation of a address@hidden
+
address@hidden @@address@hidden@}
+Indicate the result of a macro expansion to the reader with a special
+glyph: @address@hidden
address@hidden, , @expansion{} Indicating an address@hidden
+
address@hidden @@address@hidden@address@hidden
+Highlight the name of a file, buffer, node, or directory. @xref{file, ,
address@hidden@@address@hidden
+
address@hidden @@finalout
+Prevent @TeX{} from printing large black warning rectangles beside
+over-wide lines. @xref{Overfull address@hidden
+
address@hidden @@findex @var{entry}
+Add @var{entry} to the index of functions. @xref{Index Entries, ,
+Defining the Entries of an address@hidden
+
address@hidden @@flushleft
address@hidden @@flushright
+Left justify every line but leave the right end ragged.
+Leave font as is. Pair with @code{@@end flushleft}.
address@hidden@@flushright} analogous.
address@hidden & flushright, , @code{@@flushleft} and
address@hidden@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Enter a footnote. Footnote text is printed at the bottom of the page
+by @TeX{}; Info may format in either `End' node or `Separate' node style.
address@hidden@refill
+
address@hidden @@footnotestyle @var{style}
+Specify an Info file's footnote style, either @samp{end} for the end
+node style or @samp{separate} for the separate node style.
address@hidden@refill
+
address@hidden @@format
+Begin a kind of example. Like @code{@@display}, but do not narrow the
+margins. Pair with @code{@@end format}. @xref{example,,
address@hidden@@example}}.
+
address@hidden @@ftable @var{formatting-command}
+Begin a two-column table, using @code{@@item} for each entry.
+Automatically enter each of the items in the first column into the
+index of functions. Pair with @code{@@end ftable}. The same as
address@hidden@@table}, except for indexing. @xref{ftable vtable, ,
address@hidden@@ftable} and @code{@@address@hidden
+
address@hidden @@group
+Hold text together that must appear on one printed page. Pair with
address@hidden@@end group}. Not relevant to Info. @xref{group, ,
address@hidden@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}.
+
address@hidden @@heading @var{title}
+Print an unnumbered section-like heading in the text, but not in the
+table of contents of a printed manual. In Info, the title is
+underlined with equal signs. @xref{unnumberedsec appendixsec heading,
+, Section address@hidden
+
address@hidden @@headings @var{on-off-single-double}
+Turn page headings on or off, and/or specify single-sided or double-sided
+page headings for printing. @xref{headings on off, , The
address@hidden@@headings} Command}.
+
address@hidden @@html
+Enter HTML completely. Pair with @code{@@end html}. @xref{Raw
+Formatter Commands}.
+
address@hidden @@address@hidden@var{hy-phen-a-ted address@hidden
+Explicitly define hyphenation points. @xref{- and hyphenation,,
address@hidden@@-} and @code{@@hyphenation}}.
+
address@hidden @@address@hidden@address@hidden
+Print @var{text} in @i{italic} font. No effect in Info. @xref{Fonts}.
+
address@hidden @@ifclear @var{flag}
+If @var{flag} is cleared, the Texinfo formatting commands format text
+between @code{@@ifclear @var{flag}} and the following @code{@@end
+ifclear} command.
address@hidden clear value, , @code{@@set} @code{@@clear} @code{@@address@hidden
+
address@hidden @@ifhtml
address@hidden @@ifinfo
+Begin a stretch of text that will be ignored by @TeX{} when it typesets
+the printed manual. @code{@@ifhtml} text appears only in the HTML
+output. @code{@@ifinfo} output appears in both Info and (for historical
+compatibility) plain text output . Pair with @code{@@end ifhtml}
+resp.@: @code{@@end ifinfo}. @xref{Conditionals}.
+
address@hidden @@ifnothtml
address@hidden @@ifnotinfo
address@hidden @@ifnotplaintext
address@hidden @@ifnottex
+Begin a stretch of text that will be ignored in one output format but
+not the others. The text appears in the formats not specified:
address@hidden@@ifnothtml} text is omitted from html output, etc. The exception
+is @code{@@ifnotinfo} text, which is omitted from plain text output as
+well as Info output. Pair with @code{@@end ifnothtml} resp.@:
address@hidden@@end ifnotinfo} resp.@: @code{@@end ifnotplaintext} resp.@:
address@hidden@@end ifnottex}. @xref{Conditionals}.
+
address@hidden @@ifplaintext
+Begin a stretch of text that appears only in the plain text output.
+Pair with @code{@@end ifplaintext}. @xref{Conditionals}.
+
address@hidden @@ifset @var{flag}
+If @var{flag} is set, the Texinfo formatting commands format text
+between @code{@@ifset @var{flag}} and the following @code{@@end ifset}
+command.
address@hidden clear value, , @code{@@set} @code{@@clear} @code{@@address@hidden
+
address@hidden @@iftex
+Begin a stretch of text that will not appear in the Info file, but
+will be processed only by @TeX{}. Pair with @code{@@end iftex}.
address@hidden, , Conditionally Visible address@hidden
+
address@hidden @@ignore
+Begin a stretch of text that will not appear in either the Info file
+or the printed output. Pair with @code{@@end ignore}.
address@hidden, , Comments and Ignored address@hidden
+
address@hidden @@address@hidden@var{filename}, address@hidden, address@hidden,
address@hidden, address@hidden@}
+Include graphics image in external @var{filename} scaled to the given
address@hidden and/or @var{height}, using @var{alt} text and looking for
address@hidden@address@hidden in HTML. @xref{Images}.
+
address@hidden @@include @var{filename}
+Incorporate the contents of the file @var{filename} into the Info file
+or printed document. @xref{Include address@hidden
+
address@hidden @@address@hidden@var{node-name}, address@hidden, @address@hidden
+Make a cross reference to an Info file for which there is no printed
+manual. @xref{inforef, , Cross references using
address@hidden@@address@hidden
+
address@hidden \input @var{macro-definitions-file}
+Use the specified macro definitions file. This command is used only
+in the first line of a Texinfo file to cause @TeX{} to make use of the
address@hidden macro definitions file. The backslash in @code{\input}
+is used instead of an @code{@@} because @TeX{} does not
+recognize @code{@@} until after it has read the definitions file.
address@hidden File Header}.
+
address@hidden @@item
+Indicate the beginning of a marked paragraph for @code{@@itemize} and
address@hidden@@enumerate}; indicate the beginning of the text of a first column
+entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}.
address@hidden and address@hidden
+
address@hidden @@itemize @var{mark-generating-character-or-command}
+Produce a sequence of indented paragraphs, with a mark inside the left
+margin at the beginning of each paragraph. Pair with @code{@@end
+itemize}. @xref{itemize, , @code{@@address@hidden
+
address@hidden @@itemx
+Like @code{@@item} but do not generate extra vertical space above the
+item text. @xref{itemx, , @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate text that is characters of input to be typed by
+users. @xref{kbd, , @code{@@address@hidden
+
address@hidden @@kbdinputstyle @var{style}
+Specify when @code{@@kbd} should use a font distinct from @code{@@code}.
address@hidden, , @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate a name for a key on a keyboard.
address@hidden, , @code{@@address@hidden
+
address@hidden @@kindex @var{entry}
+Add @var{entry} to the index of keys.
address@hidden Entries, , Defining the Entries of an address@hidden
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Generate the uppercase and lowercase Polish suppressed-L letters,
+respectively: @L{}, @l{}.
+
address@hidden Possibly this can be tossed now that we have macros. --karl,
16sep96.
address@hidden Yes, let's toss it, it's pretty weird. --karl, 15jun97.
address@hidden @item @@global@@address@hidden@var{existing-command}
address@hidden Equate a new highlighting command with an existing one. Only for
address@hidden @TeX{}. Write definition inside of @code{@@iftex} @dots{}
@code{@@end
address@hidden iftex}. @xref{Customized address@hidden
+
address@hidden @@lisp
+Begin an example of Lisp code. Indent text, do not fill, and select
+fixed-width font. Pair with @code{@@end lisp}. @xref{lisp, , @code{@@lisp}}.
+
address@hidden @@lowersections
+Change subsequent chapters to sections, sections to subsections, and so
+on. @xref{Raise/lower sections, , @code{@@raisesections} and
address@hidden@@address@hidden
+
address@hidden @@macro @var{macroname} @address@hidden@}
+Define a new Texinfo command @code{@@@address@hidden@address@hidden
+Only supported by @code{makeinfo} and @code{texi2dvi}. @xref{Defining
+Macros}.
+
address@hidden @@majorheading @var{title}
+Print a chapter-like heading in the text, but not in the table of
+contents of a printed manual. Generate more vertical whitespace before
+the heading than the @code{@@chapheading} command. In Info, the chapter
+heading line is underlined with asterisks. @xref{majorheading &
+chapheading, , @code{@@majorheading} and @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Format a mathematical expression.
address@hidden, , @code{@@math}: Inserting Mathematical Expressions}.
+
address@hidden @@menu
+Mark the beginning of a menu of nodes in Info. No effect in a printed
+manual. Pair with @code{@@end menu}. @address@hidden
+
address@hidden @@address@hidden@}
+Generate a minus sign, address@hidden'. @xref{minus, , @code{@@address@hidden
+
address@hidden @@multitable @var{column-width-spec}
+Begin a multi-column table. Pair with @code{@@end multitable}.
address@hidden Column Widths}.
+
address@hidden @@need @var{n}
+Start a new page in a printed manual if fewer than @var{n} mils
+(thousandths of an inch) remain on the current page. @xref{need, ,
address@hidden@@address@hidden
+
address@hidden @@node @var{name}, @var{next}, @var{previous}, @var{up}
+Define the beginning of a new node in Info, and serve as a locator for
+references for @TeX{}. @xref{node, , @code{@@address@hidden
+
address@hidden @@noindent
+Prevent text from being indented as if it were a new paragraph.
address@hidden, , @code{@@address@hidden
+
address@hidden @@novalidate
+Suppress validation of node references, omit creation of auxiliary files
+with @TeX{}. Use before @code{@@setfilename}. @xref{Pointer Validation}.
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Generate the uppercase and lowercase O-with-slash letters, respectively:
address@hidden, @o{}.
+
address@hidden @@oddfooting address@hidden @@| address@hidden @@|
address@hidden
address@hidden @@oddheading address@hidden @@| address@hidden @@| address@hidden
+Specify page footings resp.@: headings for odd-numbered (right-hand)
+pages. @xref{Custom Headings, ,
+How to Make Your Own address@hidden
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Generate the uppercase and lowercase OE ligatures, respectively:
address@hidden, @oe{}. @xref{Inserting Accents}.
+
address@hidden @@address@hidden@address@hidden
+Indicate a command-line option, such as @option{-l} or @option{--help}.
address@hidden,, @code{@@option}}.
+
address@hidden @@page
+Start a new page in a printed manual. No effect in Info.
address@hidden, , @code{@@address@hidden
+
address@hidden @@pagesizes address@hidden, @var{height}]
+Change page dimensions. @xref{pagesizes}.
+
address@hidden @@paragraphindent @var{indent}
+Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve
+source file indentation if @var{indent} is @code{asis}.
address@hidden,, Paragraph Indenting}.
+
address@hidden @@pindex @var{entry}
+Add @var{entry} to the index of programs. @xref{Index Entries, , Defining
+the Entries of an address@hidden
+
address@hidden @@address@hidden@}
+Indicate the position of point in a buffer to the reader with a
+glyph: @address@hidden @xref{Point Glyph, , Indicating
+Point in a address@hidden
+
address@hidden @@address@hidden@}
+Generate the pounds sterling currency sign.
address@hidden,,@code{@@address@hidden@}}}.
+
address@hidden @@address@hidden@}
+Indicate printed output to the reader with a glyph:
address@hidden@print{}}. @xref{Print address@hidden
+
address@hidden @@printindex @var{index-name}
+Print an alphabetized two-column index in a printed manual or generate
+an alphabetized menu of index entries for Info. @xref{Printing
+Indices & address@hidden
+
address@hidden @@address@hidden@var{node-name}, address@hidden, address@hidden,
address@hidden, address@hidden@}
+Make a reference that starts with a lower case `see' in a printed
+manual. Use within parentheses only. Do not follow command with a
+punctuation mark---the Info formatting commands automatically insert
+terminating punctuation as needed. Only the first argument is mandatory.
address@hidden, , @code{@@address@hidden
+
address@hidden @@address@hidden@}
+Generate an upside-down question mark. @xref{Inserting Accents}.
+
address@hidden @@quotation
+Narrow the margins to indicate text that is quoted from another real
+or imaginary work. Write command on a line of its own. Pair with
address@hidden@@end quotation}. @xref{quotation, ,
address@hidden@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Print @var{text} in @r{roman} font. No effect in Info.
address@hidden@refill
+
address@hidden @@raisesections
+Change subsequent sections to chapters, subsections to sections, and so
+on. @xref{Raise/lower sections, , @code{@@raisesections} and
address@hidden@@address@hidden
+
address@hidden @@address@hidden@var{node-name}, address@hidden, address@hidden,
address@hidden, address@hidden@}
+Make a reference. In a printed manual, the reference does not start
+with a `See'. Follow command with a punctuation mark. Only the first
+argument is mandatory. @xref{ref, , @code{@@address@hidden
+
address@hidden @@refill
+In Info, refill and indent the paragraph after all the other processing
+has been done. No effect on @TeX{}, which always refills. This command
+is no longer needed, since all formatters now automatically refill.
address@hidden address@hidden
+
address@hidden @@address@hidden@}
+Indicate the result of an expression to the reader with a special
+glyph: @address@hidden @xref{result, , @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Generate a ring accent over the next character, as in @ringaccent{o}.
address@hidden Accents}.
+
address@hidden @@address@hidden@address@hidden
+Highlight @var{text} that is a literal example of a sequence of
+characters. Used for single characters, for statements, and often for
+entire shell commands. @xref{samp, , @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Set @var{text} in a printed output in @sc{the small caps font} and
+set text in the Info file in uppercase letters.
address@hidden@refill
+
address@hidden @@section @var{title}
+Begin a section within a chapter. In a printed manual, the section
+title is numbered and appears in the table of contents. In Info, the
+title is underlined with equal signs. @xref{section, ,
address@hidden@@address@hidden
+
address@hidden @@set @var{flag} address@hidden
+Make @var{flag} active, causing the Texinfo formatting commands to
+format text between subsequent pairs of @code{@@ifset @var{flag}} and
address@hidden@@end ifset} commands. Optionally, set value of @var{flag} to
address@hidden
address@hidden clear value, , @code{@@set} @code{@@clear} @code{@@value}}.
+
address@hidden @@setchapternewpage @var{on-off-odd}
+Specify whether chapters start on new pages, and if so, whether on
+odd-numbered (right-hand) new pages. @xref{setchapternewpage, ,
address@hidden@@setchapternewpage}}.
+
address@hidden @@setcontentsaftertitlepage
+Put the table of contents after the @samp{@@end titlepage} even if the
address@hidden@@contents} command is not there. @xref{Contents}.
+
address@hidden @@setfilename @var{info-file-name}
+Provide a name to be used by the Info file. This command is essential
+for @TeX{} formatting as well, even though it produces no output.
address@hidden, , @code{@@setfilename}}.
+
address@hidden @@setshortcontentsaftertitlepage
+Place the short table of contents after the @samp{@@end titlepage}
+command even if the @code{@@shortcontents} command is not there.
address@hidden
+
address@hidden @@settitle @var{title}
+Provide a title for page headers in a printed manual, and the default
+document description for HTML @samp{<head>}.
address@hidden, , @code{@@address@hidden
+
address@hidden @@shortcontents
+Print a short table of contents. Not relevant to Info, which uses
+menus rather than tables of contents. A synonym for
address@hidden@@summarycontents}. @xref{Contents, , Generating a Table of
address@hidden
+
address@hidden @@shorttitlepage @var{title}
+Generate a minimal title page. @xref{titlepage,,@code{@@titlepage}}.
+
address@hidden @@smallbook
+Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format
+rather than the regular 8.5 by 11 inch format. @xref{smallbook, ,
+Printing Small Books}. Also, see @ref{small}.
+
address@hidden @@smalldisplay
+Begin a kind of example. Like @code{@@smallexample} (narrow margins, no
+filling), but do not select the fixed-width font. Pair with @code{@@end
+smalldisplay}. @xref{small}.
+
address@hidden @@smallexample
+Indent text to indicate an example. Do not fill, select fixed-width
+font, narrow the margins. In printed manuals, print text in a smaller
+font than with @code{@@example}. Pair with @code{@@end smallexample}.
address@hidden
+
address@hidden @@smallformat
+Begin a kind of example. Like @code{@@smalldisplay}, but do not narrow
+the margins. Pair with @code{@@end smallformat}. @xref{small}.
+
address@hidden @@smalllisp
+Begin an example of Lisp code. Same as @code{@@smallexample}. Pair
+with @code{@@end smalllisp}. @xref{small}.
+
address@hidden @@sp @var{n}
+Skip @var{n} blank lines. @xref{sp, , @code{@@address@hidden
+
address@hidden @@address@hidden@}
+Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}.
+
address@hidden @@strong @address@hidden@}
+Emphasize @var{text} by typesetting it in a @strong{bold} font for the
+printed manual and by surrounding it with asterisks for Info.
address@hidden & strong, , Emphasizing address@hidden
+
address@hidden @@subheading @var{title}
+Print an unnumbered subsection-like heading in the text, but not in
+the table of contents of a printed manual. In Info, the title is
+underlined with hyphens. @xref{unnumberedsubsec appendixsubsec
+subheading, , @code{@@unnumberedsubsec} @code{@@appendixsubsec}
address@hidden@@address@hidden
+
address@hidden @@subsection @var{title}
+Begin a subsection within a section. In a printed manual, the
+subsection title is numbered and appears in the table of contents. In
+Info, the title is underlined with hyphens. @xref{subsection, ,
address@hidden@@address@hidden
+
address@hidden @@subsubheading @var{title}
+Print an unnumbered subsubsection-like heading in the text, but not in
+the table of contents of a printed manual. In Info, the title is
+underlined with periods. @xref{subsubsection, , The `subsub'
address@hidden
+
address@hidden @@subsubsection @var{title}
+Begin a subsubsection within a subsection. In a printed manual,
+the subsubsection title is numbered and appears in the table of
+contents. In Info, the title is underlined with periods.
address@hidden, , The `subsub' address@hidden
+
address@hidden @@subtitle @var{title}
+In a printed manual, set a subtitle in a normal sized font flush to
+the right-hand side of the page. Not relevant to Info, which does not
+have title pages. @xref{title subtitle author, , @code{@@title}
address@hidden@@subtitle} and @code{@@author} address@hidden
+
address@hidden @@summarycontents
+Print a short table of contents. Not relevant to Info, which uses
+menus rather than tables of contents. A synonym for
address@hidden@@shortcontents}. @xref{Contents, , Generating a Table of
address@hidden
+
address@hidden @@syncodeindex @var{from-index} @var{into-index}
+Merge the index named in the first argument into the index named in
+the second argument, printing the entries from the first index in
address@hidden@@code} font. @xref{Combining address@hidden
+
address@hidden @@synindex @var{from-index} @var{into-index}
+Merge the index named in the first argument into the index named in
+the second argument. Do not change the font of @var{from-index}
+entries. @xref{Combining address@hidden
+
address@hidden @@address@hidden@address@hidden
+Print @var{text} in a @t{fixed-width}, typewriter-like font.
+No effect in Info. @address@hidden
+
address@hidden @@tab
+Separate columns in a multitable. @xref{Multitable Rows}.
+
address@hidden @@table @var{formatting-command}
+Begin a two-column table, using @code{@@item} for each entry. Write
+each first column entry on the same line as @code{@@item}. First
+column entries are printed in the font resulting from
address@hidden Pair with @code{@@end table}.
address@hidden Tables, , Making a Two-column Table}.
+Also see @ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}},
+and @ref{itemx, , @code{@@address@hidden
+
address@hidden @@address@hidden@}
+Insert the logo @TeX{}. @xref{TeX and copyright, , Inserting @TeX{}
+and @address@hidden
+
address@hidden @@tex
+Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Raw
+Formatter Commands}.
+
address@hidden @@thischapter
address@hidden @@thischaptername
address@hidden @@thisfile
address@hidden @@thispage
address@hidden @@thistitle
+Only allowed in a heading or footing. Stands for the number and name of
+the current chapter (in the format `Chapter 1: Title'), the chapter name
+only, the filename, the current page number, and the title of the
+document, respectively. @xref{Custom Headings, , How to Make Your Own
address@hidden
+
address@hidden @@address@hidden@address@hidden
+Generate a tie-after accent over the next two characters @var{cc}, as in
address@hidden'. @xref{Inserting Accents}.
+
address@hidden @@tindex @var{entry}
+Add @var{entry} to the index of data types. @xref{Index Entries, ,
+Defining the Entries of an address@hidden
+
address@hidden @@title @var{title}
+In a printed manual, set a title flush to the left-hand side of the
+page in a larger than normal font and underline it with a black rule.
+Not relevant to Info, which does not have title pages. @xref{title
+subtitle author, , The @code{@@title} @code{@@subtitle} and
address@hidden@@author} address@hidden
+
address@hidden @@address@hidden@address@hidden
+In a printed manual, print @var{text} in a larger than normal font.
+Not relevant to Info, which does not have title pages.
address@hidden center sp, , The @code{@@titlefont} @code{@@center}
+and @code{@@sp} address@hidden
+
address@hidden @@titlepage
+Indicate to Texinfo the beginning of the title page. Write command on
+a line of its own. Pair with @code{@@end titlepage}. Nothing between
address@hidden@@titlepage} and @code{@@end titlepage} appears in Info.
address@hidden, , @code{@@address@hidden
+
address@hidden @@address@hidden@}
+Insert the current date, in `1 Jan 1900' style. @xref{Custom
+Headings, , How to Make Your Own address@hidden
+
address@hidden @@top @var{title}
+In a Texinfo file to be formatted with @code{makeinfo}, identify the
+topmost @code{@@node} in the file, which must be written on the line
+immediately preceding the @code{@@top} command. Used for
address@hidden's node pointer insertion feature. The title is
+underlined with asterisks. Both the @code{@@node} line and the @code{@@top}
+line normally should be enclosed by @code{@@ifnottex} and @code{@@end
+ifnottex}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
+command is merely a synonym for @code{@@unnumbered}. @xref{makeinfo
+Pointer Creation, , Creating Pointers with @code{makeinfo}}.
+
address@hidden @@address@hidden@address@hidden
address@hidden @@address@hidden@address@hidden
address@hidden @@address@hidden@address@hidden
+Generate a breve, underbar, or underdot accent, respectively, over or
+under the character @var{c}, as in @u{o}, @ubaraccent{o},
address@hidden @xref{Inserting Accents}.
+
address@hidden @@unnumbered @var{title}
+In a printed manual, begin a chapter that appears without chapter
+numbers of any kind. The title appears in the table of contents of a
+printed manual. In Info, the title is underlined with asterisks.
address@hidden & appendix, , @code{@@unnumbered} and
address@hidden@@address@hidden
+
address@hidden @@unnumberedsec @var{title}
+In a printed manual, begin a section that appears without section
+numbers of any kind. The title appears in the table of contents of a
+printed manual. In Info, the title is underlined with equal signs.
address@hidden appendixsec heading, , Section address@hidden
+
address@hidden @@unnumberedsubsec @var{title}
+In a printed manual, begin an unnumbered subsection within a
+chapter. The title appears in the table of contents of a printed
+manual. In Info, the title is underlined with hyphens.
address@hidden appendixsubsec subheading, ,
address@hidden@@unnumberedsubsec} @code{@@appendixsubsec}
address@hidden@@address@hidden
+
address@hidden @@unnumberedsubsubsec @var{title}
+In a printed manual, begin an unnumbered subsubsection within a
+chapter. The title appears in the table of contents of a printed
+manual. In Info, the title is underlined with periods.
address@hidden, , The `subsub' address@hidden
+
address@hidden @@address@hidden@var{url}[, @var{displayed-text}][,
@address@hidden
+Define a cross reference to an external uniform resource locator for the
+World Wide Web. @xref{uref, , @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate text that is a uniform resource locator for the World Wide
+Web. @xref{url, , @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Generate check accent over the character @var{c}, as in @v{o}.
address@hidden Accents}.
+
address@hidden @@address@hidden@address@hidden
+Replace @var{flag} with the value to which it is set by @code{@@set
address@hidden
address@hidden clear value, , @code{@@set} @code{@@clear} @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Highlight a metasyntactic variable, which is something that stands for
+another piece of text. @xref{var, , Indicating Metasyntactic
address@hidden
+
address@hidden @@address@hidden@var{delim} @var{literal} @address@hidden
+Output @var{literal}, delimited by the single character @var{delim},
+exactly as is (in the fixed-width font), including any whitespace or
+Texinfo special characters. @xref{verb,,@code{verb}}.
+
address@hidden @@verbatim
+Output the text of the environment exactly as is (in the fixed-width
+font). Pair with @code{@@end verbatim}. @xref{verbatim,,@code{verbatim}}.
+
address@hidden @@verbatiminclude @var{filename}
+Output the contents of @var{filename} exactly as is (in the fixed-width font).
address@hidden,,@code{verbatiminclude}}.
+
address@hidden @@vindex @var{entry}
+Add @var{entry} to the index of variables. @xref{Index Entries, ,
+Defining the Entries of an address@hidden
+
address@hidden @@vskip @var{amount}
+In a printed manual, insert whitespace so as to push text on the
+remainder of the page towards the bottom of the page. Used in
+formatting the copyright page with the argument @samp{0pt plus
+1filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used
+only in contexts ignored for Info. @xref{Copyright}.
+
address@hidden @@vtable @var{formatting-command}
+Begin a two-column table, using @code{@@item} for each entry.
+Automatically enter each of the items in the first column into the
+index of variables. Pair with @code{@@end vtable}. The same as
address@hidden@@table}, except for indexing. @xref{ftable vtable, ,
address@hidden@@ftable} and @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Prevent @var{text} from being split across two lines. Do not end a
+paragraph that uses @code{@@w} with an @code{@@refill} command.
address@hidden, , @code{@@address@hidden
+
address@hidden @@address@hidden@var{node-name}, address@hidden, address@hidden,
address@hidden, address@hidden@}
+Make a reference that starts with `See' in a printed manual. Follow
+command with a punctuation mark. Only the first argument is
+mandatory. @xref{xref, , @code{@@address@hidden
address@hidden table
+
+
address@hidden Tips
address@hidden Tips and Hints
+
+Here are some tips for writing Texinfo documentation:@refill
+
address@hidden Tips
address@hidden Usage tips
address@hidden Hints
address@hidden @bullet
address@hidden
+Write in the present tense, not in the past or the future.
+
address@hidden
+Write actively! For example, write ``We recommend that @dots{}'' rather
+than ``It is recommended that @dots{}''.
+
address@hidden
+Use 70 or 72 as your fill column. Longer lines are hard to read.
+
address@hidden
+Include a copyright notice and copying permissions.
address@hidden itemize
+
address@hidden Index, Index, Index!
+
+Write many index entries, in different ways.
+Readers like indices; they are helpful and convenient.
+
+Although it is easiest to write index entries as you write the body of
+the text, some people prefer to write entries afterwards. In either
+case, write an entry before the paragraph to which it applies. This
+way, an index entry points to the first page of a paragraph that is
+split across pages.
+
+Here are more hints we have found valuable:
+
address@hidden @bullet
address@hidden
+Write each index entry differently, so each entry refers to a different
+place in the document.
+
address@hidden
+Write index entries only where a topic is discussed significantly. For
+example, it is not useful to index ``debugging information'' in a
+chapter on reporting bugs. Someone who wants to know about debugging
+information will certainly not find it in that chapter.
+
address@hidden
+Consistently capitalize the first word of every concept index entry,
+or else consistently use lower case. Terse entries often call for
+lower case; longer entries for capitalization. Whichever case
+convention you use, please use one or the other consistently! Mixing
+the two styles looks bad.
+
address@hidden
+Always capitalize or use upper case for those words in an index for
+which this is proper, such as names of countries or acronyms. Always
+use the appropriate case for case-sensitive names, such as those in C or
+Lisp.
+
address@hidden
+Write the indexing commands that refer to a whole section immediately
+after the section command, and write the indexing commands that refer to
+a paragraph before that paragraph.
+
+In the example that follows, a blank line comes after the index
+entry for ``Leaping'':
+
address@hidden
address@hidden
+@@section The Dog and the Fox
+@@cindex Jumping, in general
+@@cindex Leaping
+
+@@cindex Dog, lazy, jumped over
+@@cindex Lazy dog jumped over
+@@cindex Fox, jumps over dog
+@@cindex Quick fox jumps over dog
+The quick brown fox jumps over the lazy dog.
address@hidden group
address@hidden example
+
address@hidden
+(Note that the example shows entries for the same concept that are
+written in different address@hidden dog}, and @samp{Dog, lazy}---so
+readers can look up the concept in different ways.)
address@hidden itemize
+
address@hidden Blank Lines
+
address@hidden @bullet
address@hidden
+Insert a blank line between a sectioning command and the first following
+sentence or paragraph, or between the indexing commands associated with
+the sectioning command and the first following sentence or paragraph, as
+shown in the tip on indexing. Otherwise, a formatter may fold title and
+paragraph together.
+
address@hidden
+Always insert a blank line before an @code{@@table} command and after an
address@hidden@@end table} command; but never insert a blank line after an
address@hidden@@table} command or before an @code{@@end table} command.
+
address@hidden 1000
+For example,
+
address@hidden
address@hidden
+Types of fox:
+
+@@table @@samp
+@@item Quick
+Jump over lazy dogs.
address@hidden group
+
address@hidden
+@@item Brown
+Also jump over lazy dogs.
+@@end table
+
address@hidden group
address@hidden
+@@noindent
+On the other hand, @dots{}
address@hidden group
address@hidden example
+
+Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end
+itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the
+same way.
address@hidden itemize
+
address@hidden Complete Phrases
+
+Complete phrases are easier to read than @dots{}
+
address@hidden @bullet
address@hidden
+Write entries in an itemized list as complete sentences; or at least, as
+complete phrases. Incomplete expressions @dots{} awkward @dots{} like
+this.
+
address@hidden
+Write the prefatory sentence or phrase for a multi-item list or table as
+a complete expression. Do not write ``You can set:''; instead, write
+``You can set these variables:''. The former expression sounds cut off.
address@hidden itemize
+
address@hidden Editions, Dates and Versions
+
+Include edition numbers, version numbers, and dates in the
address@hidden@@copying} text (for people reading the Texinfo file, and for the
+legal copyright in the output files). Then use @code{@@insertcopying}
+in the @code{@@titlepage} section (for people reading the printed
+output) and the Top node (for people reading the online output).
+
+It is easiest to do this using @code{@@set} and @code{@@value}.
address@hidden Example, , @code{@@value} Example}, and @ref{GNU Sample Texts}.
+
+
address@hidden Definition Commands
+
+Definition commands are @code{@@deffn}, @code{@@defun},
address@hidden@@defmac}, and the like, and enable you to write descriptions in
+a uniform address@hidden
+
address@hidden @bullet
address@hidden
+Write just one definition command for each entity you define with a
+definition command. The automatic indexing feature creates an index
+entry that leads the reader to the definition.
+
address@hidden
+Use @code{@@table} @dots{} @code{@@end table} in an appendix that
+contains a summary of functions, not @code{@@deffn} or other definition
+commands.
address@hidden itemize
+
address@hidden Capitalization
+
address@hidden @bullet
address@hidden
+Capitalize ``Texinfo''; it is a name. Do not write the @samp{x} or
address@hidden in upper case.
+
address@hidden
+Capitalize ``Info''; it is a name.
+
address@hidden
+Write @TeX{} using the @code{@@address@hidden@}} command. Note the uppercase
address@hidden and @samp{X}. This command causes the formatters to
+typeset the name according to the wishes of Donald Knuth, who wrote
address@hidden
address@hidden itemize
+
address@hidden Spaces
+
+Do not use spaces to format a Texinfo file, except inside of
address@hidden@@example} @dots{} @code{@@end example} and similar commands.
+
address@hidden 700
+For example, @TeX{} fills the following:
+
address@hidden
address@hidden
+ @@address@hidden address@hidden
+ @@address@hidden address@hidden
+ Perform the next logical operation
+ on the version-controlled file
+ corresponding to the current buffer.
address@hidden group
address@hidden example
+
address@hidden 950
address@hidden
+so it looks like this:
+
address@hidden
+`C-x v' `M-x vc-next-action' Perform the next logical operation on the
+version-controlled file corresponding to the current buffer.
address@hidden quotation
+
address@hidden
+In this case, the text should be formatted with
address@hidden@@table}, @code{@@item}, and @code{@@itemx}, to create a table.
+
address@hidden @@code, @@samp, @@var, and @samp{---}
+
address@hidden @bullet
address@hidden
+Use @code{@@code} around Lisp symbols, including command names.
+For example,
+
address@hidden
+The main function is @@address@hidden@}, @dots{}
address@hidden example
+
address@hidden
+Avoid putting letters such as @samp{s} immediately after an
address@hidden@@code}. Such letters look bad.
+
address@hidden
+Use @code{@@var} around meta-variables. Do not write angle brackets
+around them.
+
address@hidden
+Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{}
+typesets these as a long dash and the Info formatters reduce three
+hyphens to two.
address@hidden itemize
+
address@hidden Periods Outside of Quotes
+
+Place periods and other punctuation marks @emph{outside} of quotations,
+unless the punctuation is part of the quotation. This practice goes
+against publishing conventions in the United States, but enables the
+reader to distinguish between the contents of the quotation and the
+whole passage.
+
+For example, you should write the following sentence with the period
+outside the end quotation marks:
+
address@hidden
+Evidently, @samp{au} is an abbreviation for ``author''.
address@hidden example
+
address@hidden
+since @samp{au} does @emph{not} serve as an abbreviation for
address@hidden (with a period following the word).
+
address@hidden Introducing New Terms
+
address@hidden @bullet
address@hidden
+Introduce new terms so that a reader who does not know them can
+understand them from context; or write a definition for the term.
+
+For example, in the following, the terms ``check in'', ``register'' and
+``delta'' are all appearing for the first time; the example sentence should be
+rewritten so they are understandable.
+
address@hidden
+The major function assists you in checking in a file to your
+version control system and registering successive sets of changes to
+it as deltas.
address@hidden quotation
+
address@hidden
+Use the @code{@@dfn} command around a word being introduced, to indicate
+that the reader should not expect to know the meaning already, and
+should expect to learn the meaning from this passage.
address@hidden itemize
+
address@hidden @@pxref
+
address@hidden !!! maybe include this in the tips on pxref
+Absolutely never use @code{@@pxref} except in the special context for
+which it is designed: inside parentheses, with the closing parenthesis
+following immediately after the closing brace. One formatter
+automatically inserts closing punctuation and the other does not. This
+means that the output looks right both in printed output and in an Info
+file, but only when the command is used inside parentheses.
+
address@hidden Invoking from a Shell
+
+You can invoke programs such as Emacs, GCC, and @code{gawk} from a
+shell. The documentation for each program should contain a section that
+describes this. Unfortunately, if the node names and titles for these
+sections are all different, they are difficult for users to find.
+
+So, there is a convention to name such sections with a phrase beginning
+with the word `Invoking', as in `Invoking Emacs'; this way, users can
+find the section easily.
+
+
address@hidden ANSI C Syntax
+
+When you use @code{@@example} to describe a C function's calling
+conventions, use the ANSI C syntax, like this:@refill
+
address@hidden
+void dld_init (char *@@address@hidden@});
address@hidden example
+
address@hidden
+And in the subsequent discussion, refer to the argument values by
+writing the same argument names, again highlighted with
address@hidden@@address@hidden
+
address@hidden 800
+Avoid the obsolete style that looks like this:@refill
+
address@hidden
+#include <dld.h>
+
+dld_init (path)
+char *path;
address@hidden example
+
+Also, it is best to avoid writing @code{#include} above the
+declaration just to indicate that the function is declared in a
+header file. The practice may give the misimpression that the
address@hidden belongs near the declaration of the function. Either
+state explicitly which header file holds the declaration or, better
+yet, name the header file used for a group of functions at the
+beginning of the section that describes the address@hidden
+
address@hidden Bad Examples
+
+Here are several examples of bad writing to avoid:
+
+In this example, say, `` @dots{} you must @code{@@address@hidden
address@hidden the new version.'' That flows better.
+
address@hidden
+When you are done editing the file, you must perform a
address@hidden@@address@hidden address@hidden
address@hidden quotation
+
+In the following example, say, address@hidden makes a unified interface such
as VC
+mode possible.''
+
address@hidden
+SCCS, RCS and other version-control systems all perform similar
+functions in broadly similar ways (it is this resemblance which makes
+a unified control mode like this possible).
address@hidden quotation
+
+And in this example, you should specify what `it' refers to:
+
address@hidden
+If you are working with other people, it assists in coordinating
+everyone's changes so they do not step on each other.
address@hidden quotation
+
address@hidden And Finally @dots{}
+
address@hidden @bullet
address@hidden
+Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last
+sound in the name `Bach'. But pronounce Texinfo as in `speck':
+``teckinfo''.
+
address@hidden
+Write notes for yourself at the very end of a Texinfo file after the
address@hidden@@bye}. None of the formatters process text after the
address@hidden@@bye}; it is as if the text were within @code{@@ignore} @dots{}
address@hidden@@end ignore}.
address@hidden itemize
+
+
address@hidden Sample Texinfo Files
address@hidden Sample Texinfo Files
address@hidden Sample Texinfo files
+
+The first example is from the first chapter (@pxref{Short Sample}),
+given here in its entirety, without commentary. The second sample
+includes the full texts to be used in GNU manuals.
+
address@hidden
+* Short Sample Texinfo File::
+* GNU Sample Texts::
address@hidden menu
+
+
address@hidden Short Sample Texinfo File
address@hidden Short Sample
address@hidden Sample Texinfo file, no comments
+
+Here is a complete, short sample Texinfo file, without any commentary.
+You can see this file, with comments, in the first chapter. @xref{Short
+Sample}.
+
+In a nutshell: The @command{makeinfo} program transforms a Texinfo
+source file such as this into an Info file or HTML; and @TeX{} typesets
+it for a printed manual.
+
+
address@hidden 1
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename sample.info
+@@settitle Sample Manual 1.0
+@@c %**end of header
+
+@@copying
+This is a short example of a complete Texinfo file.
+
+Copyright (C) 2002 Free Software Foundation, Inc.
+@@end copying
+
+@@titlepage
+@@title Sample Title
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
+@@end titlepage
+
+@@c Output the table of the contents at the beginning.
+@@contents
+
+@@ifnottex
+@@node Top
+
+@@insertcopying
+@@end ifnottex
+
+@@menu
+* First Chapter:: The first chapter is the
+ only chapter in this sample.
+* Index:: Complete index.
+@@end menu
+
+
+@@node First Chapter
+@@chapter First Chapter
+
+@@cindex chapter, first
+
+This is the first chapter.
+@@cindex index entry, another
+
+Here is a numbered list.
+
+@@enumerate
+@@item
+This is the first item.
+
+@@item
+This is the second item.
+@@end enumerate
+
+
+@@node Index
+@@unnumbered Index
+
+@@printindex cp
+
+@@bye
address@hidden example
+
+
address@hidden GNU Sample Texts
address@hidden GNU Sample Texts
+
address@hidden GNU sample texts
address@hidden Sample texts, GNU
address@hidden Full texts, GNU
+
+Here 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.
+
address@hidden Sample}, for a minimal example of a Texinfo file.
address@hidden a File}, for a full explanation of that minimal
+example.
+
+Here are some notes on the example:
+
address@hidden @bullet
address@hidden
address@hidden $ @c Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $
comment
address@hidden CVS Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $, in
Texinfo
address@hidden RCS Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $, in
Texinfo
+The @samp{Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $} comment is
for CVS (@pxref{Top,, Overview, cvs,
+Concurrent Versions System}) or RCS (see rcsintro(1)) version control
+systems, which expand it into a string such as:
address@hidden
+Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $
address@hidden example
+(This is useful in all sources that use version control, not just manuals.)
+
address@hidden
address@hidden address@hidden, and version info}
+The @file{version.texi} in the @code{@@include} command is maintained
+automatically by Automake (@pxref{Top,, Introduction, automake, GNU
+Automake}). It sets the @samp{VERSION} and @samp{UPDATED} values used
+elsewhere. If your distribution doesn't use Automake, you can mimic
+these or equivalent settings.
+
address@hidden
+The @code{@@syncodeindex} command reflects the recommendation to use only
+one index if at all possible, to make it easier for readers.
+
address@hidden
+The @code{@@dircategory} is for constructing the Info directory.
address@hidden Dir Entries}, which includes a variety of recommended
+category names.
+
address@hidden
+The `Invoking' node is a GNU standard to help users find the basic
+information about command-line usage of a given program. @xref{Manual
+Structure Details,,,standards, GNU Coding Standards}.
+
address@hidden
+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 of doing so. The @file{fdl.texi}
+file is available on the GNU machines (and in the Texinfo and other GNU
+distributions).
+
+The FDL provides for omitting itself under certain conditions, but in
+that case the sample texts given here have to be modified. @xref{GNU
+Free Documentation License}.
+
address@hidden
+If your manual has invariant sections (again, see the license itself for
+details), then don't forget to include them.
address@hidden itemize
+
+Here is the sample document:
+
address@hidden We do the first part of this with @example instead of @verbatim
address@hidden because the literal @setfilename and @include confuse Automake.
Argh.
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@comment Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $
+@@comment %**start of header
+@@setfilename sample.info
+@@include version.texi
+@@settitle GNU Sample @@address@hidden@}
+@@syncodeindex pg cp
+@@comment %**end of header
+@@copying
+This manual is for GNU Sample
+(version @@address@hidden@}, @@address@hidden@}),
+which is an example in the Texinfo documentation.
+
+Copyright @@address@hidden@} 2002 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 @@address@hidden@}, @@address@hidden@}
+@@author A.U. Thor (@@address@hidden@@@@address@hidden)
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
+@@end titlepage
+
+@@contents
+
+@@ifnottex
+@@node Top
+@@top GNU Sample
+
+@@insertcopying
+@@end ifnottex
+
+@@menu
+* Invoking sample::
+* Copying This Manual::
+* Index::
+@@end menu
+
+
+@@node Invoking sample
+@@chapter Invoking sample
+
+@@pindex sample
+@@cindex invoking @@address@hidden@}
+
+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
address@hidden example
+
+
address@hidden Include Files
address@hidden Include Files
address@hidden Include files
+
+When @TeX{} or an Info formatting command sees an @code{@@include}
+command in a Texinfo file, it processes the contents of the file named
+by the command and incorporates them into the DVI or Info file being
+created. Index entries from the included file are incorporated into
+the indices of the output file.
+
+Include files let you keep a single large document as a collection of
+conveniently small parts.
+
address@hidden
+* Using Include Files:: How to use the @code{@@include} command.
+* texinfo-multiple-files-update:: How to create and update nodes and
+ menus when using included files.
+* Include File Requirements:: What @code{texinfo-multiple-files-update}
expects.
+* 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.
address@hidden menu
+
address@hidden Using Include Files, texinfo-multiple-files-update, Include
Files, Include Files
address@hidden How to Use Include Files
address@hidden include
+
+To include another file within a Texinfo file, write the
address@hidden@@include} command at the beginning of a line and follow it on
+the same line by the name of a file to be included. For
+example:@refill
+
address@hidden
+@@include buffers.texi
address@hidden example
+
+An included file should simply be a segment of text that you expect to
+be included as is into the overall or @dfn{outer} Texinfo file; it
+should not contain the standard beginning and end parts of a Texinfo
+file. In particular, you should not start an included file with a
+line saying @samp{\input texinfo}; if you do, that phrase is inserted
+into the output file as is. Likewise, you should not end an included
+file with an @code{@@bye} command; nothing after @code{@@bye} is
address@hidden
+
+In the past, you were required to write an @code{@@setfilename} line at the
+beginning of an included file, but no longer. Now, it does not matter
+whether you write such a line. If an @code{@@setfilename} line exists
+in an included file, it is address@hidden
+
+Conventionally, an included file begins with an @code{@@node} line that
+is followed by an @code{@@chapter} line. Each included file is one
+chapter. This makes it easy to use the regular node and menu creating
+and updating commands to create the node pointers and menus within the
+included file. However, the simple Emacs node and menu creating and
+updating commands do not work with multiple Texinfo files. Thus you
+cannot use these commands to fill in the `Next', `Previous', and `Up'
+pointers of the @code{@@node} line that begins the included file. Also,
+you cannot use the regular commands to create a master menu for the
+whole file. Either you must insert the menus and the `Next',
+`Previous', and `Up' pointers by hand, or you must use the GNU Emacs
+Texinfo mode command, @code{texinfo-multiple-files-update}, that is
+designed for @code{@@include} address@hidden
+
address@hidden texinfo-multiple-files-update, Include File Requirements, Using
Include Files, Include Files
address@hidden @code{texinfo-multiple-files-update}
address@hidden texinfo-multiple-files-update
+
+GNU Emacs Texinfo mode provides the @code{texinfo-multiple-files-update}
+command. This command creates or updates `Next', `Previous', and `Up'
+pointers of included files as well as those in the outer or overall
+Texinfo file, and it creates or updates a main menu in the outer file.
+Depending whether you call it with optional arguments, the command
+updates only the pointers in the first @code{@@node} line of the
+included files or all of them:@refill
+
address@hidden @kbd
address@hidden M-x texinfo-multiple-files-update
+Called without any arguments:@refill
+
address@hidden @minus
address@hidden
+Create or update the `Next', `Previous', and `Up' pointers of the
+first @code{@@node} line in each file included in an outer or overall
+Texinfo address@hidden
+
address@hidden
+Create or update the `Top' level node pointers of the outer or
+overall address@hidden
+
address@hidden
+Create or update a main menu in the outer address@hidden
address@hidden itemize
+
address@hidden C-u M-x texinfo-multiple-files-update
+Called with @kbd{C-u} as a prefix argument:
+
address@hidden @minus{}
address@hidden
+Create or update pointers in the first @code{@@node} line in each
+included file.
+
address@hidden
+Create or update the `Top' level node pointers of the outer file.
+
address@hidden
+Create and insert a master menu in the outer file. The master menu
+is made from all the menus in all the included address@hidden
address@hidden itemize
+
address@hidden C-u 8 M-x texinfo-multiple-files-update
+Called with a numeric prefix argument, such as @kbd{C-u 8}:
+
address@hidden @minus
address@hidden
+Create or update @strong{all} the `Next', `Previous', and `Up' pointers
+of all the included address@hidden
+
address@hidden
+Create or update @strong{all} the menus of all the included
address@hidden
+
address@hidden
+Create or update the `Top' level node pointers of the outer or
+overall address@hidden
+
address@hidden
+And then create a master menu in the outer file. This is similar to
+invoking @code{texinfo-master-menu} with an argument when you are
+working with just one address@hidden
address@hidden itemize
address@hidden table
+
+Note the use of the prefix argument in interactive use: with a regular
+prefix argument, just @address@hidden, the
address@hidden command inserts a master menu;
+with a numeric prefix argument, such as @kbd{C-u 8}, the command
+updates @strong{every} pointer and menu in @strong{all} the files and then
inserts a
+master address@hidden
+
+
address@hidden Include File Requirements
address@hidden Include File Requirements
address@hidden Include file requirements
address@hidden Requirements for include files
+
+If you plan to use the @code{texinfo-multiple-files-update} command,
+the outer Texinfo file that lists included files within it should
+contain nothing but the beginning and end parts of a Texinfo file, and
+a number of @code{@@include} commands listing the included files. It
+should not even include indices, which should be listed in an included
+file of their address@hidden
+
+Moreover, each of the included files must contain exactly one highest
+level node (conventionally, @code{@@chapter} or equivalent),
+and this node must be the first node in the included file.
+Furthermore, each of these highest level nodes in each included file
+must be at the same hierarchical level in the file structure.
+Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an
address@hidden@@unnumbered} node. Thus, normally, each included file contains
+one, and only one, chapter or equivalent-level address@hidden
+
+The outer file should contain only @emph{one} node, the `Top' node. It
+should @emph{not} contain any nodes besides the single `Top' node. The
address@hidden command will not process
address@hidden
+
address@hidden Sample Include File, Include Files Evolution, Include File
Requirements, Include Files
address@hidden Sample File with @code{@@include}
address@hidden Sample @code{@@include} file
address@hidden Include file sample
address@hidden @code{@@include} file sample
+
+Here is an example of a complete outer Texinfo file with @code{@@include} files
+within it before running @code{texinfo-multiple-files-update}, which
+would insert a main or master menu:@refill
+
address@hidden
address@hidden
+\input texinfo @@c -*-texinfo-*-
address@hidden %**start of header
+@@setfilename include-example.info
+@@settitle Include Example
address@hidden %**end of header
address@hidden group
+
address@hidden
+@@setchapternewpage odd
+@@titlepage
+@@sp 12
+@@center @@address@hidden address@hidden
+@@sp 2
+@@center by Whom Ever
address@hidden group
+
address@hidden
+@@page
+@@vskip 0pt plus 1filll
+Copyright @@address@hidden@} 2002 Free Software Foundation, Inc.
+@@end titlepage
address@hidden group
+
address@hidden
+@@ifinfo
+@@node Top, First, , (dir)
+@@top Master Menu
+@@end ifinfo
address@hidden group
+
address@hidden
+@@include foo.texinfo
+@@include bar.texinfo
+@@include concept-index.texinfo
address@hidden group
+
address@hidden
+@@summarycontents
+@@contents
+
+@@bye
address@hidden group
address@hidden example
+
+An included file, such as @file{foo.texinfo}, might look like this:
+
address@hidden
address@hidden
+@@node First, Second, , Top
+@@chapter First Chapter
+
+Contents of first chapter @dots{}
address@hidden group
address@hidden example
+
+The full contents of @file{concept-index.texinfo} might be as simple as this:
+
address@hidden
address@hidden
+@@node Concept Index
+@@unnumbered Concept Index
+
+@@printindex cp
address@hidden group
address@hidden example
+
+The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference
+Manual} is named @file{elisp.texi}. This outer file contains a master
+menu with 417 entries and a list of 41 @code{@@include}
address@hidden
+
+
address@hidden Include Files Evolution
address@hidden Evolution of Include Files
+
+When Info was first created, it was customary to create many small
+Info files on one subject. Each Info file was formatted from its own
+Texinfo source file. This custom meant that Emacs did not need to
+make a large buffer to hold the whole of a large Info file when
+someone wanted information; instead, Emacs allocated just enough
+memory for the small Info file that contained the particular
+information sought. This way, Emacs could avoid wasting address@hidden
+
+References from one file to another were made by referring to the file
+name as well as the node name. (@xref{Other Info Files, , Referring to
+Other Info Files}. Also, see @ref{Four and Five Arguments, ,
address@hidden@@xref} with Four and Five Arguments}.)@refill
+
+Include files were designed primarily as a way to create a single,
+large printed manual out of several smaller Info files. In a printed
+manual, all the references were within the same document, so @TeX{}
+could automatically determine the references' page numbers. The Info
+formatting commands used include files only for creating joint
+indices; each of the individual Texinfo files had to be formatted for
+Info individually. (Each, therefore, required its own
address@hidden@@setfilename} line.)@refill
+
+However, because large Info files are now split automatically, it is
+no longer necessary to keep them address@hidden
+
+Nowadays, multiple Texinfo files are used mostly for large documents,
+such as @cite{The GNU Emacs Lisp Reference Manual}, and for projects
+in which several different people write different sections of a
+document address@hidden
+
+In addition, the Info formatting commands have been extended to work
+with the @code{@@include} command so as to create a single large Info
+file that is split into smaller files if necessary. This means that
+you can write menus and cross references without naming the different
+Texinfo address@hidden
+
+
address@hidden Headings
address@hidden Page Headings
address@hidden Headings
address@hidden Footings
address@hidden Page numbering
address@hidden Page headings
address@hidden Formatting headings and footings
+
+Most printed manuals contain headings along the top of every page
+except the title and copyright pages. Some manuals also contain
+footings. (Headings and footings have no meaning to Info, which is
+not paginated.)@refill
+
address@hidden
+* 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.
address@hidden menu
+
address@hidden Headings Introduced, Heading Format, Headings, Headings
address@hidden Headings Introduced
+
+Texinfo provides standard page heading formats for manuals that are
+printed on one side of each sheet of paper and for manuals that are
+printed on both sides of the paper. Typically, you will use these
+formats, but you can specify your own format if you address@hidden
+
+In addition, you can specify whether chapters should begin on a new
+page, or merely continue the same page as the previous chapter; and if
+chapters begin on new pages, you can specify whether they must be
+odd-numbered address@hidden
+
+By convention, a book is printed on both sides of each sheet of paper.
+When you open a book, the right-hand page is odd-numbered, and
+chapters begin on right-hand pages---a preceding left-hand page is
+left blank if necessary. Reports, however, are often printed on just
+one side of paper, and chapters begin on a fresh page immediately
+following the end of the preceding chapter. In short or informal
+reports, chapters often do not begin on a new page at all, but are
+separated from the preceding text by a small amount of address@hidden
+
+The @code{@@setchapternewpage} command controls whether chapters begin
+on new pages, and whether one of the standard heading formats is used.
+In addition, Texinfo has several heading and footing commands that you
+can use to generate your own heading and footing address@hidden
+
+In Texinfo, headings and footings are single lines at the tops and
+bottoms of pages; you cannot create multiline headings or footings.
+Each header or footer line is divided into three parts: a left part, a
+middle part, and a right part. Any part, or a whole line, may be left
+blank. Text for the left part of a header or footer line is set
+flushleft; text for the middle part is centered; and, text for the
+right part is set address@hidden
+
address@hidden Heading Format, Heading Choice, Headings Introduced, Headings
address@hidden node-name, next, previous, up
address@hidden Standard Heading Formats
+
+Texinfo provides two standard heading formats, one for manuals printed
+on one side of each sheet of paper, and the other for manuals printed
+on both sides of the paper.
+
+By default, nothing is specified for the footing of a Texinfo file,
+so the footing remains address@hidden
+
+The standard format for single-sided printing consists of a header
+line in which the left-hand part contains the name of the chapter, the
+central part is blank, and the right-hand part contains the page
address@hidden
+
address@hidden 950
+A single-sided page looks like this:
+
address@hidden
address@hidden
+ _______________________
+ | |
+ | chapter page number |
+ | |
+ | Start of text ... |
+ | ... |
+ | |
+
address@hidden group
address@hidden example
+
+The standard format for two-sided printing depends on whether the page
+number is even or odd. By convention, even-numbered pages are on the
+left- and odd-numbered pages are on the right. (@TeX{} will adjust the
+widths of the left- and right-hand margins. Usually, widths are
+correct, but during double-sided printing, it is wise to check that
+pages will bind properly---sometimes a printer will produce output in
+which the even-numbered pages have a larger right-hand margin than the
+odd-numbered pages.)@refill
+
+In the standard double-sided format, the left part of the left-hand
+(even-numbered) page contains the page number, the central part is
+blank, and the right part contains the title (specified by the
address@hidden@@settitle} command). The left part of the right-hand
+(odd-numbered) page contains the name of the chapter, the central part
+is blank, and the right part contains the page address@hidden
+
address@hidden 750
+Two pages, side by side as in an open book, look like this:@refill
+
address@hidden
address@hidden
+ _______________________ _______________________
+ | | | |
+ | page number title | | chapter page number |
+ | | | |
+ | Start of text ... | | More text ... |
+ | ... | | ... |
+ | | | |
+
address@hidden group
address@hidden example
+
address@hidden
+The chapter name is preceded by the word ``Chapter'', the chapter number
+and a colon. This makes it easier to keep track of where you are in the
address@hidden
+
address@hidden Heading Choice, Custom Headings, Heading Format, Headings
address@hidden node-name, next, previous, up
address@hidden Specifying the Type of Heading
+
address@hidden does not begin to generate page headings for a standard Texinfo
+file until it reaches the @code{@@end titlepage} command. Thus, the
+title and copyright pages are not numbered. The @code{@@end
+titlepage} command causes @TeX{} to begin to generate page headings
+according to a standard format specified by the
address@hidden@@setchapternewpage} command that precedes the
address@hidden@@titlepage} address@hidden
+
address@hidden 1000
+There are four possibilities:@refill
+
address@hidden @asis
address@hidden No @code{@@setchapternewpage} command
+Cause @TeX{} to specify the single-sided heading format, with chapters
+on new pages. This is the same as @code{@@setchapternewpage address@hidden
+
address@hidden @code{@@setchapternewpage on}
+Specify the single-sided heading format, with chapters on new address@hidden
+
address@hidden @code{@@setchapternewpage off}
+Cause @TeX{} to start a new chapter on the same page as the last page of
+the preceding chapter, after skipping some vertical whitespace. Also
+cause @TeX{} to typeset for single-sided printing. (You can override
+the headers format with the @code{@@headings double} command; see
address@hidden on off, , The @code{@@headings} Command}.)@refill
+
address@hidden @code{@@setchapternewpage odd}
+Specify the double-sided heading format, with chapters on new address@hidden
address@hidden table
+
address@hidden
+Texinfo lacks an @code{@@setchapternewpage even} address@hidden
+
address@hidden Custom Headings, , Heading Choice, Headings
address@hidden node-name, next, previous, up
address@hidden How to Make Your Own Headings
+
+You can use the standard headings provided with Texinfo or specify
+your own. By default, Texinfo has no footers, so if you specify them,
+the available page size for the main text will be slightly reduced.
+
+Texinfo provides six commands for specifying headings and
+footings:
address@hidden @bullet
address@hidden
address@hidden@@everyheading} @code{@@everyfooting} generate page headers and
+footers that are the same for both even- and odd-numbered pages.
address@hidden
address@hidden@@evenheading} and @code{@@evenfooting} command generate headers
+and footers for even-numbered (left-hand) pages.
address@hidden
address@hidden@@oddheading} and @code{@@oddfooting} generate headers and footers
+for odd-numbered (right-hand) pages.
address@hidden itemize
+
+Write custom heading specifications in the Texinfo file immediately
+after the @code{@@end titlepage} command.
+You must cancel the predefined heading commands with the
address@hidden@@headings off} command before defining your own
address@hidden
+
address@hidden 1000
+Here is how to tell @TeX{} to place the chapter name at the left, the
+page number in the center, and the date at the right of every header
+for both even- and odd-numbered pages:@refill
+
address@hidden
address@hidden
+@@headings off
+@@everyheading @@thischapter @@| @@thispage @@| @@address@hidden@}
address@hidden group
address@hidden example
+
address@hidden
+You need to divide the left part from the central part and the central
+part from the right part by inserting @samp{@@|} between parts.
+Otherwise, the specification command will not be able to tell where
+the text for one part ends and the next part address@hidden
+
+Each part can contain text or @@-commands. The text
+is printed as if the part were within an ordinary paragraph in the
+body of the page. The @@-commands replace
+themselves with the page number, date, chapter name, or
address@hidden
+
address@hidden 950
+Here are the six heading and footing commands:@refill
+
address@hidden everyheading
address@hidden everyfooting
address@hidden @code
address@hidden @@everyheading @var{left} @@| @var{center} @@| @var{right}
address@hidden @@everyfooting @var{left} @@| @var{center} @@| @var{right}
+
+The `every' commands specify the format for both even- and odd-numbered
+pages. These commands are for documents that are printed on one side
+of each sheet of paper, or for documents in which you want symmetrical
+headers or address@hidden
+
address@hidden evenheading
address@hidden evenfooting
address@hidden oddheading
address@hidden oddfooting
address@hidden @@evenheading @var{left} @@| @var{center} @@| @var{right}
address@hidden @@oddheading @var{left} @@| @var{center} @@| @var{right}
+
address@hidden @@evenfooting @var{left} @@| @var{center} @@| @var{right}
address@hidden @@oddfooting @var{left} @@| @var{center} @@| @var{right}
+
+The `even' and `odd' commands specify the format for even-numbered
+pages and odd-numbered pages. These commands are for books and
+manuals that are printed on both sides of each sheet of paper.
address@hidden table
+
+Use the @samp{@@address@hidden series of @@-commands to
+provide the names of chapters
+and sections and the page number. You can use the
address@hidden@@address@hidden commands in the left, center, or right portions
+of headers and footers, or anywhere else in a Texinfo file so long as
+they are between @code{@@iftex} and @code{@@end iftex} address@hidden
+
address@hidden 1000
+Here are the @samp{@@address@hidden commands:@refill
+
address@hidden @code
address@hidden thispage
address@hidden @@thispage
+Expands to the current page address@hidden
address@hidden !!! Karl Berry says that `thissection' can fail on page breaks.
+
address@hidden thischaptername
address@hidden @@thischaptername
+Expands to the name of the current address@hidden
+
address@hidden thischapter
address@hidden @@thischapter
+Expands to the number and name of the current
+chapter, in the format `Chapter 1: Title'address@hidden
+
address@hidden thistitle
address@hidden @@thistitle
+Expands to the name of the document, as specified by the
address@hidden@@settitle} address@hidden
+
address@hidden thisfile
address@hidden @@thisfile
+For @code{@@include} files only: expands to the name of the current
address@hidden@@include} file. If the current Texinfo source file is not an
address@hidden@@include} file, this command has no effect. This command does
address@hidden provide the name of the current Texinfo source file unless
+it is an @code{@@include} file. (@xref{Include Files}, for more
+information about @code{@@include} files.)@refill
address@hidden table
+
address@hidden
+You can also use the @code{@@address@hidden@}} command, which expands to the
+current date, in `1 Jan 1900' address@hidden
address@hidden today
+
+Other @@-commands and text are printed in a header or footer just as
+if they were in the body of a page. It is useful to incorporate text,
+particularly when you are writing drafts:@refill
+
address@hidden
address@hidden
+@@headings off
+@@everyheading @@address@hidden@} @@| @@thispage @@| @@thischapter
+@@everyfooting @@| @@| Version: 0.27: @@address@hidden@}
address@hidden group
address@hidden example
+
+Beware of overlong titles: they may overlap another part of the
+header or footer and blot it address@hidden
+
+
address@hidden Catching Mistakes
address@hidden Formatting Mistakes
address@hidden Structure, catching mistakes in
address@hidden Nodes, catching mistakes
address@hidden Catching mistakes
address@hidden Correcting mistakes
address@hidden Mistakes, catching
address@hidden Problems, catching
address@hidden Debugging the Texinfo structure
+
+Besides mistakes in the content of your documentation, there are two
+kinds of mistake you can make with Texinfo: you can make mistakes with
+@@-commands, and you can make mistakes with the structure of the nodes
+and chapters.
+
+Emacs has two tools for catching the @@-command mistakes and two for
+catching structuring address@hidden
+
+For finding problems with @@-commands, you can run @TeX{} or a region
+formatting command on the region that has a problem; indeed, you can
+run these commands on each region as you write address@hidden
+
+For finding problems with the structure of nodes and chapters, you can use
address@hidden C-s} (@code{texinfo-show-structure}) and the related @code{occur}
+command and you can use the @kbd{M-x Info-validate} address@hidden
+
address@hidden
+* 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 texinfo-show-structure:: How to use @code{texinfo-show-structure}.
+* Using occur:: How to list all lines containing a pattern.
+* Running Info-Validate:: How to find badly referenced nodes.
address@hidden menu
+
address@hidden makeinfo Preferred, Debugging with Info, Catching Mistakes,
Catching Mistakes
address@hidden @code{makeinfo} Find Errors
+
+The @code{makeinfo} program does an excellent job of catching errors
+and reporting them---far better than @code{texinfo-format-region} or
address@hidden In addition, the various functions for
+automatically creating and updating node pointers and menus remove
+many opportunities for human address@hidden
+
+If you can, use the updating commands to create and insert pointers
+and menus. These prevent many errors. Then use @code{makeinfo} (or
+its Texinfo mode manifestations, @code{makeinfo-region} and
address@hidden) to format your file and check for other
+errors. This is the best way to work with Texinfo. But if you
+cannot use @code{makeinfo}, or your problem is very puzzling, then you
+may want to use the tools described in this address@hidden
+
address@hidden Debugging with Info, Debugging with TeX, makeinfo Preferred,
Catching Mistakes
address@hidden node-name, next, previous, up
address@hidden Catching Errors with Info Formatting
address@hidden Catching errors with Info formatting
address@hidden Debugging with Info formatting
+
+After you have written part of a Texinfo file, you can use the
address@hidden or the @code{makeinfo-region} command to
+see whether the region formats address@hidden
+
+Most likely, however, you are reading this section because for some
+reason you cannot use the @code{makeinfo-region} command; therefore, the
+rest of this section presumes that you are using
address@hidden@refill
+
+If you have made a mistake with an @@-command,
address@hidden will stop processing at or after the
+error and display an error message. To see where in the buffer the
+error occurred, switch to the @samp{*Info Region*} buffer; the cursor
+will be in a position that is after the location of the error. Also,
+the text will not be formatted after the place where the error
+occurred (or more precisely, where it was detected)address@hidden
+
+For example, if you accidentally end a menu with the command @code{@@end
+menus} with an `s' on the end, instead of with @code{@@end menu}, you
+will see an error message that says:@refill
+
address@hidden
+@@end menus is not handled by texinfo
address@hidden example
+
address@hidden
+The cursor will stop at the point in the buffer where the error
+occurs, or not long after it. The buffer will look like this:@refill
+
address@hidden
address@hidden
+---------- Buffer: *Info Region* ----------
+* Menu:
+
+* Using texinfo-show-structure:: How to use
+ `texinfo-show-structure'
+ to catch mistakes.
+* Running Info-Validate:: How to check for
+ unreferenced nodes.
+@@end menus
address@hidden
+---------- Buffer: *Info Region* ----------
address@hidden group
address@hidden example
+
+The @code{texinfo-format-region} command sometimes provides slightly
+odd error messages. For example, the following cross reference fails to
format:@refill
+
address@hidden
+(@@address@hidden Mistakes, for more info.)
address@hidden example
+
address@hidden
+In this case, @code{texinfo-format-region} detects the missing closing
+brace but displays a message that says @samp{Unbalanced parentheses}
+rather than @samp{Unbalanced braces}. This is because the formatting
+command looks for mismatches between braces as if they were
address@hidden
+
+Sometimes @code{texinfo-format-region} fails to detect mistakes. For
+example, in the following, the closing brace is swapped with the
+closing parenthesis:@refill
+
address@hidden
+(@@address@hidden Mistakes), for more address@hidden
address@hidden example
+
address@hidden
+Formatting produces:
address@hidden
+(*Note for more info.: Catching Mistakes)
address@hidden example
+
+The only way for you to detect this error is to realize that the
+reference should have looked like this:@refill
+
address@hidden
+(*Note Catching Mistakes::, for more info.)
address@hidden example
+
+Incidentally, if you are reading this node in Info and type @kbd{f
address@hidden (@code{Info-follow-reference}), you will generate an error
+message that says:
+
address@hidden
+No such node: "Catching Mistakes) The only way @dots{}
address@hidden example
+
address@hidden
+This is because Info perceives the example of the error as the first
+cross reference in this node and if you type a @key{RET} immediately
+after typing the Info @kbd{f} command, Info will attempt to go to the
+referenced node. If you type @kbd{f catch @key{TAB} @key{RET}}, Info
+will complete the node name of the correctly written example and take
+you to the `Catching Mistakes' node. (If you try this, you can return
+from the `Catching Mistakes' node by typing @kbd{l}
+(@code{Info-last}).)
+
address@hidden !!! section on using Elisp debugger ignored.
+
address@hidden Debugging with TeX, Using texinfo-show-structure, Debugging with
Info, Catching Mistakes
address@hidden node-name, next, previous, up
address@hidden Catching Errors with @TeX{} Formatting
address@hidden Catching errors with @TeX{} formatting
address@hidden Debugging with @TeX{} formatting
+
+You can also catch mistakes when you format a file with @address@hidden
+
+Usually, you will want to do this after you have run
address@hidden (or, better, @code{makeinfo-buffer}) on
+the same file, because @code{texinfo-format-buffer} sometimes displays
+error messages that make more sense than @TeX{}. (@xref{Debugging
+with Info}, for more information.)@refill
+
+For example, @TeX{} was run on a Texinfo file, part of which is shown
+here:@refill
+
address@hidden
+---------- Buffer: texinfo.texi ----------
+name of the Texinfo file as an extension. The
+@@address@hidden@} are `wildcards' that cause the shell to
+substitute all the raw index files. (@@address@hidden
+indices, for more information about sorting
+indices.)@@refill
+---------- Buffer: texinfo.texi ----------
address@hidden example
+
address@hidden
+(The cross reference lacks a closing brace.)
address@hidden produced the following output, after which it stopped:@refill
+
address@hidden
+---------- Buffer: *tex-shell* ----------
+Runaway argument?
address@hidden indices, for more information about sorting
+indices.) @@refill @@ETC.
+! Paragraph ended before @@xref was complete.
+<to be read again>
+ @@par
+l.27
+
+?
+---------- Buffer: *tex-shell* ----------
address@hidden example
+
+In this case, @TeX{} produced an accurate and
+understandable error message:
+
address@hidden
+Paragraph ended before @@xref was complete.
address@hidden example
+
address@hidden
address@hidden@@par} is an internal @TeX{} command of no relevance to Texinfo.
address@hidden means that @TeX{} detected the problem on line 27 of the
+Texinfo file. The @samp{?} is the prompt @TeX{} uses in this
address@hidden
+
+Unfortunately, @TeX{} is not always so helpful, and sometimes you must
+truly be a Sherlock Holmes to discover what went address@hidden
+
+In any case, if you run into a problem like this, you can do one of three
address@hidden
+
address@hidden
address@hidden
+You can tell @TeX{} to continue running and ignore just this error by
+typing @key{RET} at the @samp{?} address@hidden
+
address@hidden
+You can tell @TeX{} to continue running and to ignore all errors as best
+it can by typing @kbd{r @key{RET}} at the @samp{?} address@hidden
+
+This is often the best thing to do. However, beware: the one error
+may produce a cascade of additional error messages as its consequences
+are felt through the rest of the file. To stop @TeX{} when it is
+producing such an avalanche of error messages, type @kbd{C-c} (or
address@hidden C-c}, if you are running a shell inside Emacs).
+
address@hidden
+You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}}
+at the @samp{?} address@hidden
address@hidden enumerate
+
+If you are running @TeX{} inside Emacs, you need to switch to the shell
+buffer and line at which @TeX{} offers the @samp{?} prompt.
+
+Sometimes @TeX{} will format a file without producing error messages even
+though there is a problem. This usually occurs if a command is not ended
+but @TeX{} is able to continue processing anyhow. For example, if you fail
+to end an itemized list with the @code{@@end itemize} command, @TeX{} will
+write a DVI file that you can print out. The only error message that
address@hidden will give you is the somewhat mysterious comment address@hidden
+
address@hidden
+(@@end occurred inside a group at level 1)
address@hidden example
+
address@hidden
+However, if you print the DVI file, you will find that the text
+of the file that follows the itemized list is entirely indented as if
+it were part of the last item in the itemized list. The error message
+is the way @TeX{} says that it expected to find an @code{@@end}
+command somewhere in the file; but that it could not determine where
+it was address@hidden
+
+Another source of notoriously hard-to-find errors is a missing
address@hidden@@end group} command. If you ever are stumped by
+incomprehensible errors, look for a missing @code{@@end group} command
address@hidden
+
+If the Texinfo file lacks header lines,
address@hidden may stop in the
+beginning of its run and display output that looks like the following.
+The @samp{*} indicates that @TeX{} is waiting for address@hidden
+
address@hidden
+This is TeX, Version 3.14159 (Web2c 7.0)
+(test.texinfo [1])
+*
address@hidden example
+
address@hidden
+In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then
+write the header lines in the Texinfo file and run the @TeX{} command
+again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\}
+instead of @samp{@@}; and in this circumstance, you are working
+directly with @TeX{}, not with Texinfo.)@refill
+
address@hidden Using texinfo-show-structure, Using occur, Debugging with TeX,
Catching Mistakes
address@hidden node-name, next, previous, up
address@hidden Using @code{texinfo-show-structure}
address@hidden Showing the structure of a file
address@hidden texinfo-show-structure
+
+It is not always easy to keep track of the nodes, chapters, sections, and
+subsections of a Texinfo file. This is especially true if you are revising
+or adding to a Texinfo file that someone else has address@hidden
+
+In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure}
+command lists all the lines that begin with the @@-commands that
+specify the structure: @code{@@chapter}, @code{@@section},
address@hidden@@appendix}, and so on. With an argument (@address@hidden
+as prefix argument, if interactive),
+the command also shows the @code{@@node} lines. The
address@hidden command is bound to @kbd{C-c C-s} in
+Texinfo mode, by address@hidden
+
+The lines are displayed in a buffer called the @samp{*Occur*} buffer,
+indented by hierarchical level. For example, here is a part of what was
+produced by running @code{texinfo-show-structure} on this manual:@refill
+
address@hidden
address@hidden
+ Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\|
+ unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
+ in buffer texinfo.texi.
+ @dots{}
+ 4177:@@chapter Nodes
+ 4198: @@heading Two Paths
+ 4231: @@section Node and Menu Illustration
+ 4337: @@section The @@address@hidden@@@@address@hidden Command
+ 4393: @@subheading Choosing Node and Pointer Names
+ 4417: @@subsection How to Write an @@address@hidden@@@@address@hidden
Line
+ 4469: @@subsection @@address@hidden@@@@address@hidden Line Tips
+ @dots{}
address@hidden group
address@hidden example
+
+This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin
+with the @code{@@section}, @code{@@subheading}, and @code{@@subsection}
+commands respectively. If you move your cursor into the @samp{*Occur*}
+window, you can position the cursor over one of the lines and use the
address@hidden C-c} command (@code{occur-mode-goto-occurrence}), to jump to
+the corresponding spot in the Texinfo file. @xref{Other Repeating
+Search, , Using Occur, emacs, The GNU Emacs Manual}, for more
+information about @address@hidden
+
+The first line in the @samp{*Occur*} window describes the @dfn{regular
+expression} specified by @var{texinfo-heading-pattern}. This regular
+expression is the pattern that @code{texinfo-show-structure} looks for.
address@hidden, , Using Regular Expressions, emacs, The GNU Emacs Manual},
+for more address@hidden
+
+When you invoke the @code{texinfo-show-structure} command, Emacs will
+display the structure of the whole buffer. If you want to see the
+structure of just a part of the buffer, of one chapter, for example,
+use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the
+region. (@xref{Narrowing, , , emacs, The GNU Emacs Manual}.) This is
+how the example used above was generated. (To see the whole buffer
+again, use @kbd{C-x n w} (@code{widen}).)@refill
+
+If you call @code{texinfo-show-structure} with a prefix argument by
+typing @address@hidden C-c C-s}}, it will list lines beginning with
address@hidden@@node} as well as the lines beginning with the @@-sign commands
+for @code{@@chapter}, @code{@@section}, and the address@hidden
+
+You can remind yourself of the structure of a Texinfo file by looking at
+the list in the @samp{*Occur*} window; and if you have mis-named a node
+or left out a section, you can correct the address@hidden
+
address@hidden Using occur, Running Info-Validate, Using
texinfo-show-structure, Catching Mistakes
address@hidden node-name, next, previous, up
address@hidden Using @code{occur}
address@hidden Occurrences, listing with @code{@@occur}
address@hidden occur
+
+Sometimes the @code{texinfo-show-structure} command produces too much
+information. Perhaps you want to remind yourself of the overall structure
+of a Texinfo file, and are overwhelmed by the detailed list produced by
address@hidden In this case, you can use the @code{occur}
+command directly. To do this, address@hidden
+
address@hidden
address@hidden occur}
address@hidden example
+
address@hidden
+and then, when prompted, type a @dfn{regexp}, a regular expression for
+the pattern you want to match. (@xref{Regexps, , Regular Expressions,
+emacs, The GNU Emacs Manual}.) The @code{occur} command works from
+the current location of the cursor in the buffer to the end of the
+buffer. If you want to run @code{occur} on the whole buffer, place
+the cursor at the beginning of the address@hidden
+
+For example, to see all the lines that contain the word
address@hidden@@chapter} in them, just type @samp{@@chapter}. This will
+produce a list of the chapters. It will also list all the sentences
+with @samp{@@chapter} in the middle of the address@hidden
+
+If you want to see only those lines that start with the word
address@hidden@@chapter}, type @samp{^@@chapter} when prompted by
address@hidden If you want to see all the lines that end with a word
+or phrase, end the last word with a @samp{$}; for example,
address@hidden mistakes$}. This can be helpful when you want to see
+all the nodes that are part of the same chapter or section and
+therefore have the same `Up' address@hidden
+
address@hidden Repeating Search, , Using Occur, emacs , The GNU Emacs Manual},
+for more address@hidden
+
address@hidden Running Info-Validate, , Using occur, Catching Mistakes
address@hidden node-name, next, previous, up
address@hidden Finding Badly Referenced Nodes
address@hidden Info-validate
address@hidden Nodes, checking for badly referenced
address@hidden Checking for badly referenced nodes
address@hidden Looking for badly referenced nodes
address@hidden Finding badly referenced nodes
address@hidden Badly referenced nodes
+
+You can use the @code{Info-validate} command to check whether any of
+the `Next', `Previous', `Up' or other node pointers fail to point to a
+node. This command checks that every node pointer points to an
+existing node. The @code{Info-validate} command works only on Info
+files, not on Texinfo address@hidden
+
+The @code{makeinfo} program validates pointers automatically, so you
+do not need to use the @code{Info-validate} command if you are using
address@hidden You only may need to use @code{Info-validate} if you
+are unable to run @code{makeinfo} and instead must create an Info file
+using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or
+if you write an Info file from address@hidden
+
address@hidden
+* Using 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.
address@hidden menu
+
address@hidden Using Info-validate, Unsplit, Running Info-Validate, Running
Info-Validate
address@hidden Running @code{Info-validate}
address@hidden Running @code{Info-validate}
address@hidden Info validating a large file
address@hidden Validating a large file
+
+To use @code{Info-validate}, visit the Info file you wish to check and
+type:@refill
+
address@hidden
+M-x Info-validate
address@hidden example
+
address@hidden
+Note that the @code{Info-validate} command requires an upper case
+`I'. You may also need to create a tag table before running
address@hidden @xref{Tagifying}.
+
+If your file is valid, you will receive a message that says ``File appears
+valid''. However, if you have a pointer that does not point to a node,
+error messages will be displayed in a buffer called @samp{*problems in
+info address@hidden
+
+For example, @code{Info-validate} was run on a test file that contained
+only the first node of this manual. One of the messages said:@refill
+
address@hidden
+In node "Overview", invalid Next: Texinfo Mode
address@hidden example
+
address@hidden
+This meant that the node called @samp{Overview} had a `Next' pointer that
+did not point to anything (which was true in this case, since the test file
+had only one node in it)address@hidden
+
+Now suppose we add a node named @samp{Texinfo Mode} to our test case
+but we do not specify a `Previous' for this node. Then we will get
+the following error message:@refill
+
address@hidden
+In node "Texinfo Mode", should have Previous: Overview
address@hidden example
+
address@hidden
+This is because every `Next' pointer should be matched by a
+`Previous' (in the node where the `Next' points) which points address@hidden
+
address@hidden also checks that all menu entries and cross references
+point to actual address@hidden
+
address@hidden requires a tag table and does not work with files
+that have been split. (The @code{texinfo-format-buffer} command
+automatically splits large files.) In order to use @code{Info-validate}
+on a large file, you must run @code{texinfo-format-buffer} with an
+argument so that it does not split the Info file; and you must create a
+tag table for the unsplit file.
+
address@hidden Unsplit, Tagifying, Using Info-validate, Running Info-Validate
address@hidden node-name, next, previous, up
address@hidden Creating an Unsplit File
address@hidden Creating an unsplit file
address@hidden Unsplit file creation
+
+You can run @code{Info-validate} only on a single Info file that has a
+tag table. The command will not work on the indirect subfiles that
+are generated when a master file is split. If you have a large file
+(longer than 70,000 bytes or so), you need to run the
address@hidden or @code{makeinfo-buffer} command in such
+a way that it does not create indirect subfiles. You will also need
+to create a tag table for the Info file. After you have done this,
+you can run @code{Info-validate} and look for badly referenced
address@hidden
+
+The first step is to create an unsplit Info file. To prevent
address@hidden from splitting a Texinfo file into
+smaller Info files, give a prefix to the @kbd{M-x
+texinfo-format-buffer} command:@refill
+
address@hidden
+C-u M-x texinfo-format-buffer
address@hidden example
+
address@hidden
+or else
+
address@hidden
+C-u C-c C-e C-b
address@hidden example
+
address@hidden
+When you do this, Texinfo will not split the file and will not create
+a tag table for it. @refill
address@hidden Making a tag table manually
address@hidden Tag table, making manually
+
address@hidden Tagifying, Splitting, Unsplit, Running Info-Validate
address@hidden Tagifying a File
+
+After creating an unsplit Info file, you must create a tag table for
+it. Visit the Info file you wish to tagify and type:@refill
+
address@hidden
+M-x Info-tagify
address@hidden example
+
address@hidden
+(Note the upper case @samp{I} in @code{Info-tagify}.) This creates an
+Info file with a tag table that you can address@hidden
+
+The third step is to validate the Info file:@refill
+
address@hidden
+M-x Info-validate
address@hidden example
+
address@hidden
+(Note the upper case @samp{I} in @code{Info-validate}.)
+In brief, the steps are:@refill
+
address@hidden
address@hidden
+C-u M-x texinfo-format-buffer
+M-x Info-tagify
+M-x Info-validate
address@hidden group
address@hidden example
+
+After you have validated the node structure, you can rerun
address@hidden in the normal way so it will construct a
+tag table and split the file automatically, or you can make the tag
+table and split the file address@hidden
+
address@hidden Splitting, , Tagifying, Running Info-Validate
address@hidden node-name, next, previous, up
address@hidden Splitting a File Manually
address@hidden Splitting an Info file manually
address@hidden Info file, splitting manually
+
+You should split a large file or else let the
address@hidden or @code{makeinfo-buffer} command do it
+for you automatically. (Generally you will let one of the formatting
+commands do this job for you. @xref{Creating an Info File}.)@refill
+
+The split-off files are called the indirect address@hidden
+
+Info files are split to save memory. With smaller files, Emacs does not
+have make such a large buffer to hold the address@hidden
+
+If an Info file has more than 30 nodes, you should also make a tag
+table for it. @xref{Using Info-validate}, for information
+about creating a tag table. (Again, tag tables are usually created
+automatically by the formatting command; you only need to create a tag
+table yourself if you are doing the job manually. Most likely, you
+will do this for a large, unsplit file on which you have run
address@hidden)@refill
+
address@hidden Info-split is autoloaded in `loaddefs.el' in Emacs 18.51
+
+Visit the Info file you wish to tagify and split and type the two
+commands:@refill
+
address@hidden
+M-x Info-tagify
+M-x Info-split
address@hidden example
+
address@hidden
+(Note that the @samp{I} in @samp{Info} is upper case.)@refill
+
+When you use the @code{Info-split} command, the buffer is modified into a
+(small) Info file which lists the indirect subfiles. This file should be
+saved in place of the original visited file. The indirect subfiles are
+written in the same directory the original file is in, with names generated
+by appending @samp{-} and a number to the original file address@hidden
+
+The primary file still functions as an Info file, but it contains just
+the tag table and a directory of address@hidden
+
+
address@hidden Refilling Paragraphs
address@hidden Refilling Paragraphs
address@hidden Refilling paragraphs
address@hidden Filling paragraphs
address@hidden Paragraphs, filling
address@hidden refill
+
+The @code{@@refill} command refills and, optionally, indents the first
+line of a address@hidden the command should have been
+called the @code{@@refillandindent} command, but @code{@@refill} is
+shorter and the name was chosen before indenting was possible.} The
address@hidden@@refill} command is no longer important, but we describe it here
+because you once needed it. You will see it in many old Texinfo
address@hidden
+
+Without refilling, paragraphs containing long @@-constructs may look
+bad after formatting because the formatter removes @@-commands and
+shortens some lines more than others. In the past, neither the
address@hidden command nor the
address@hidden command refilled paragraphs
+automatically. The @code{@@refill} command had to be written at the
+end of every paragraph to cause these formatters to fill them. (Both
address@hidden and @code{makeinfo} have always refilled paragraphs
+automatically.) Now, all the Info formatters automatically fill and
+indent those paragraphs that need to be filled and address@hidden
+
+The @code{@@refill} command causes @code{texinfo-format-region} and
address@hidden to refill a paragraph in the Info file
address@hidden all the other processing has been done. For this reason,
+you can not use @code{@@refill} with a paragraph containing either
address@hidden@@*} or @code{@@address@hidden @dots{} @}} since the refilling
action will
+override those two address@hidden
+
+The @code{texinfo-format-region} and @code{texinfo-format-buffer}
+commands now automatically append @code{@@refill} to the end of each
+paragraph that should be filled. They do not append @code{@@refill} to
+the ends of paragraphs that contain @code{@@*} or
@address@hidden@@address@hidden @address@hidden
+and therefore do not refill or indent address@hidden
+
+
address@hidden Command Syntax
address@hidden @@-Command Syntax
address@hidden @@-command syntax
address@hidden Syntax, of @@-commands
address@hidden Command syntax
+
+The character @samp{@@} is used to start special Texinfo commands.
+(It has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo
+has four types of @@-command:@refill
+
address@hidden @asis
address@hidden 1. Non-alphabetic commands.
+These commands consist of an @@ followed by a punctuation mark or other
+character that is not part of the alphabet. Non-alphabetic commands are
+almost always part of the text within a paragraph, and never take any
+argument. The two characters (@@ and the other one) are complete in
+themselves; none is followed by braces. The non-alphabetic commands
+are: @code{@@.}, @code{@@:}, @code{@@*}, @code{@@@kbd{SPACE}},
address@hidden@@@kbd{TAB}}, @code{@@@kbd{NL}}, @code{@@@@}, @code{@@@{}, and
address@hidden@@@address@hidden
+
address@hidden 2. Alphabetic commands that do not require arguments.
+These commands start with @@ followed by a word followed by left- and
+right-hand braces. These commands insert special symbols in the
+document; they do not require arguments. For example,
address@hidden@@address@hidden@}} @result{} @address@hidden,
@code{@@address@hidden@}}
address@hidden @address@hidden, @code{@@address@hidden@}} @result{}
address@hidden',
+and @code{@@address@hidden@}} @result{} @address@hidden@refill
+
address@hidden 3. Alphabetic commands that require arguments within braces.
+These commands start with @@ followed by a letter or a word, followed by an
+argument within braces. For example, the command @code{@@dfn} indicates
+the introductory or defining use of a term; it is used as follows: @samp{In
+Texinfo, @@@@-commands are @@address@hidden@} address@hidden
+
address@hidden 4. Alphabetic commands that occupy an entire line.
+These commands occupy an entire line. The line starts with @@,
+followed by the name of the command (a word); for example, @code{@@center}
+or @code{@@cindex}. If no argument is needed, the word is followed by
+the end of the line. If there is an argument, it is separated from
+the command name by a space. Braces are not address@hidden
address@hidden table
+
address@hidden Braces and argument syntax
+Thus, the alphabetic commands fall into classes that have
+different argument syntaxes. You cannot tell to which class a command
+belongs by the appearance of its name, but you can tell by the
+command's meaning: if the command stands for a glyph, it is in
+class 2 and does not require an argument; if it makes sense to use the
+command together with other text as part of a paragraph, the command
+is in class 3 and must be followed by an argument in braces;
+otherwise, it is in class 4 and uses the rest of the line as its
address@hidden
+
+The purpose of having a different syntax for commands of classes 3 and
+4 is to make Texinfo files easier to read, and also to help the GNU
+Emacs paragraph and filling commands work properly. There is only one
+exception to this rule: the command @code{@@refill}, which is always
+used at the end of a paragraph immediately following the final period
+or other punctuation character. @code{@@refill} takes no argument and
+does @emph{not} require braces. @code{@@refill} never confuses the
+Emacs paragraph commands because it cannot appear at the beginning of
+a address@hidden
+
+
address@hidden Obtaining TeX
address@hidden How to Obtain @TeX{}
address@hidden Obtaining @TeX{}
address@hidden @TeX{}, how to obtain
+
address@hidden !!! Here is information about obtaining TeX. Update it whenever.
address@hidden !!! Also consider updating TeX.README on ftp.gnu.org.
address@hidden Updated by RJC on 1 March 1995, conversation with MacKay.
address@hidden Updated by address@hidden on 29 July 1996.
address@hidden Updated by address@hidden on 25 April 1997.
address@hidden Updated by address@hidden on 27 February 1998.
address@hidden is freely redistributable. You can obtain @TeX{} for Unix
+systems via anonymous ftp or on physical media. The core material
+consists of the Web2c @TeX{} distribution (@uref{http://tug.org/web2c}).
+
+Instructions for retrieval by anonymous ftp and information on other
+available distributions:
address@hidden
address@hidden://tug.org/tex/unixtex.ftp}
address@hidden://tug.org/unixtex.ftp}
address@hidden example
+
+The Free Software Foundation provides a core distribution on its Source
+Code CD-ROM suitable for printing Texinfo manuals. To order it, contact:
+
address@hidden
address@hidden
+Free Software Foundation, Inc.
+59 Temple Place Suite 330
+Boston, MA @ @ 02111-1307
+USA
+Telephone: @w{+1-617-542-5942}
+Fax: (including Japan) @w{+1-617-542-2652}
+Free Dial Fax (in Japan):
address@hidden } @w{ } @w{ } 0031-13-2473 (KDD)
address@hidden } @w{ } @w{ } 0066-3382-0158 (IDC)
+Electronic mail: @code{gnu@@gnu.org}
address@hidden group
address@hidden display
+
+Many other @TeX{} distributions are available; see
address@hidden://tug.org/}.
+
+
address@hidden These are no longer ``new'', and the explanations
address@hidden are all given elsewhere anyway, I think. --karl, 25apr97.
address@hidden So ignore the entire appendix.
+
+
address@hidden Copying This Manual
address@hidden Copying This Manual
+
address@hidden
+* GNU Free Documentation License:: License for copying this manual.
address@hidden menu
+
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
+
address@hidden FDL, GNU Free Documentation License
address@hidden Version 1.1, March 2000
+
address@hidden
+Copyright @copyright{} 2000 Free Software Foundation, Inc.
+59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
address@hidden display
+
address@hidden 0
address@hidden
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+written document @dfn{free} in the sense of freedom: to assure everyone
+the effective freedom to copy and redistribute it, with or without
+modifying it, either commercially or noncommercially. Secondarily,
+this License preserves for the author and publisher a way to get
+credit for their work, while not being considered responsible for
+modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
address@hidden
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work that contains a
+notice placed by the copyright holder saying it can be distributed
+under the terms of this License. The ``Document'', below, refers to any
+such manual or work. Any member of the public is a licensee, and is
+addressed as ``you''.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (For example, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, whose contents can be viewed and edited directly and
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is
+not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
address@hidden without markup, Texinfo input format, address@hidden input
format,
address@hidden or @acronym{XML} using a publicly available
address@hidden, and standard-conforming simple @acronym{HTML} designed
+for human modification. Opaque formats include PostScript,
address@hidden, proprietary formats that can be read and edited only by
+proprietary word processors, @acronym{SGML} or @acronym{XML} for which
+the @acronym{DTD} and/or processing tools are not generally available,
+and the machine-generated @acronym{HTML} produced by some word
+processors for output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
address@hidden
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
address@hidden
+COPYING IN QUANTITY
+
+If you publish printed copies of the Document numbering more than 100,
+and the Document's license notice requires Cover Texts, you must enclose
+the copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols. If you use the latter
+option, you must take reasonably prudent steps, when you begin
+distribution of Opaque copies in quantity, to ensure that this
+Transparent copy will remain thus accessible at the stated location
+until at least one year after the last time you distribute an Opaque
+copy (directly or through your agents or retailers) of that edition to
+the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
address@hidden
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
address@hidden A
address@hidden
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
address@hidden
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has less than five).
+
address@hidden
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
address@hidden
+Preserve all the copyright notices of the Document.
+
address@hidden
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
address@hidden
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
address@hidden
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
address@hidden
+Include an unaltered copy of this License.
+
address@hidden
+Preserve the section entitled ``History'', and its title, and add to
+it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
address@hidden
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
address@hidden
+In any section entitled ``Acknowledgments'' or ``Dedications'',
+preserve the section's title, and preserve in the section all the
+substance and tone of each of the contributor acknowledgments
+and/or dedications given therein.
+
address@hidden
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
address@hidden
+Delete any section entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
address@hidden
+Do not retitle any existing section as ``Endorsements''
+or to conflict in title with any Invariant Section.
address@hidden enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
address@hidden
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections entitled ``History''
+in the various original documents, forming one section entitled
+``History''; likewise combine any sections entitled ``Acknowledgments'',
+and any sections entitled ``Dedications''. You must delete all sections
+entitled ``Endorsements.''
+
address@hidden
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
address@hidden
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, does not as a whole count as a Modified Version
+of the Document, provided no compilation copyright is claimed for the
+compilation. Such a compilation is called an ``aggregate'', and this
+License does not apply to the other self-contained works thus compiled
+with the Document, on account of their being thus compiled, if they
+are not themselves derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one quarter
+of the entire aggregate, the Document's Cover Texts may be placed on
+covers that surround only the Document within the aggregate.
+Otherwise they must appear on covers around the whole aggregate.
+
address@hidden
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License provided that you also include the
+original English version of this License. In case of a disagreement
+between the translation and the original English version of this
+License, the original English version will prevail.
+
address@hidden
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
address@hidden
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
address@hidden://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
address@hidden enumerate
+
address@hidden
address@hidden ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
address@hidden
address@hidden
+ Copyright (C) @var{year} @var{your name}.
+ 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 the Invariant Sections being @var{list their titles}, with the
+ Front-Cover Texts being @var{list}, and with the Back-Cover Texts being
@var{list}.
+ A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
address@hidden group
address@hidden smallexample
+
+If you have no Invariant Sections, write ``with no Invariant Sections''
+instead of saying which ones are invariant. If you have no
+Front-Cover Texts, write ``no Front-Cover Texts'' instead of
+``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
address@hidden Local Variables:
address@hidden ispell-local-pdict: "ispell-dict"
address@hidden End:
+
+
+
address@hidden Command and Variable Index
address@hidden Command and Variable Index
+
+This is an alphabetical list of all the @@-commands, assorted Emacs Lisp
+functions, and several variables. To make the list easier to use, the
+commands are listed without their preceding @samp{@@address@hidden
+
address@hidden fn
+
+
address@hidden Concept Index
address@hidden Concept Index
+
address@hidden cp
+
+
address@hidden
Index: res_all/texi_cvs/cvs.texi.first
===================================================================
RCS file: res_all/texi_cvs/cvs.texi.first
diff -N res_all/texi_cvs/cvs.texi.first
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ res_all/texi_cvs/cvs.texi.first 2 Aug 2009 13:11:02 -0000 1.1
@@ -0,0 +1,14377 @@
+\input texinfo @c -*-texinfo-*-
address@hidden Documentation for CVS.
address@hidden cvs.info
address@hidden copyleftnotice
address@hidden
+Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
+ 2001, 2002, 2003 Free Software Foundation, Inc.
+
address@hidden @columnfractions .12 .88
address@hidden Portions
address@hidden @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003 Derek
R. Price,
address@hidden @tab Copyright @copyright{} 2002, 2003 Ximbiot
<http://ximbiot.com>,
address@hidden @tab Copyright @copyright{} 1992, 1993, 1999 Signum Support AB,
address@hidden @tab and Copyright @copyright{} others.
address@hidden multitable
+
address@hidden
+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).
+
address@hidden ignore
+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 also 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 Free Software Foundation.
address@hidden macro
+
address@hidden This file is part of the CVS distribution.
+
address@hidden CVS is free software; you can redistribute it and/or modify
address@hidden it under the terms of the GNU General Public License as
published by
address@hidden the Free Software Foundation; either version 2, or (at your
option)
address@hidden any later version.
+
address@hidden CVS is distributed in the hope that it will be useful,
address@hidden but WITHOUT ANY WARRANTY; without even the implied warranty of
address@hidden MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
address@hidden GNU General Public License for more details.
+
address@hidden See ../README for A4 vs. US letter size.
address@hidden When we provided A4 postscript, and people tried to
address@hidden print it on US letter, the usual complaint was that the
address@hidden page numbers would get cut off.
address@hidden If one prints US letter on A4, reportedly there is
address@hidden some extra space at the top and/or bottom, and the side
address@hidden margins are a bit narrow, but no text is lost.
address@hidden
address@hidden See
address@hidden http://www.ft.uni-erlangen.de/~mskuhn/iso-paper.html
address@hidden for more on paper sizes. Insuring that margins are
address@hidden big enough to print on either A4 or US letter does
address@hidden indeed seem to be the usual approach (RFC2346).
+
address@hidden This document seems to get overfull hboxes with some
address@hidden frequency (probably because the tendency is to
address@hidden sanity-check it with "make info" and run TeX less
address@hidden often). The big ugly boxes just seem to add insult
address@hidden to injury, and I'm not aware of them helping to fix
address@hidden the overfull hboxes at all.
address@hidden
+
address@hidden UPDATED 28 March 2002
address@hidden UPDATED-MONTH March 2002
address@hidden EDITION 4.2
address@hidden VERSION 4.2
address@hidden CVS---Concurrent Versions System v4.2
address@hidden odd
+
address@hidden -- TODO list:
address@hidden -- Fix all lines that match "address@hidden -- "
address@hidden -- Also places marked with FIXME should be manual
address@hidden problems (as opposed to FIXCVS for CVS problems).
+
address@hidden @splitrcskeyword{} is used to avoid keyword expansion. It is
replaced by
address@hidden @asis when generating info and dvi, and by <i></i> in the
generated html,
address@hidden such that keywords are not expanded in the generated html.
+
address@hidden splitrcskeyword {arg}
+ \arg\
address@hidden macro
+
+
+
+
address@hidden GNU Packages
address@hidden
+* CVS: (cvs). Concurrent Versions System
address@hidden direntry
address@hidden Individual utilities
address@hidden
+* cvs: (cvs)CVS commands. Concurrent Versions System
address@hidden direntry
+
address@hidden The titlepage section does not appear in the Info file.
+
address@hidden ================================================================
address@hidden The real text starts here
address@hidden ================================================================
+
address@hidden
---------------------------------------------------------------------
address@hidden Top
address@hidden
+
+This info manual describes how to use and administer
address@hidden version 4.2.
+
+
address@hidden This menu is pretty long. Not sure how easily that
address@hidden can be fixed (no brilliant ideas right away)...
address@hidden
+* Overview:: An introduction to CVS
+* Repository:: Where all your sources are stored
+* Starting a new project:: Starting a project with CVS
+* Revisions:: Numeric and symbolic names for revisions
+* Branching and merging:: Diverging/rejoining branches of development
+* Recursive behavior:: CVS descends directories
+* Adding and removing:: Adding/removing/renaming files/directories
+* History browsing:: Viewing the history of files in various ways
+
+CVS and the Real World.
+-----------------------
+* Binary files:: CVS can handle binary files
+* Multiple developers:: How CVS helps a group of developers
+* Revision management:: Policy questions for revision management
+* Keyword substitution:: CVS can include the revision inside the file
+* Tracking sources:: Tracking third-party sources
+* Builds:: Issues related to CVS and builds
+* Special Files:: Devices, links and other non-regular files
+
+References.
+-----------
+* CVS commands:: CVS commands share some things
+* Invoking CVS:: Quick reference to CVS commands
+* Administrative files:: Reference manual for the Administrative files
+* Environment variables:: All environment variables which affect CVS
+* Compatibility:: Upgrading CVS versions
+* Troubleshooting:: Some tips when nothing works
+* Credits:: Some of the contributors to this manual
+* BUGS:: Dealing with bugs in CVS or this manual
+* Index:: Index
address@hidden menu
+
address@hidden
---------------------------------------------------------------------
address@hidden Overview
address@hidden Overview
address@hidden Overview
+
+This chapter is for people who have never used
address@hidden, and perhaps have never used version control
+software before.
+
+If you are already familiar with @sc{cvs} and are just
+trying to learn a particular feature or remember a
+certain command, you can probably skip everything here.
+
address@hidden
+* What is CVS?:: What you can do with @sc{cvs}
+* What is CVS not?:: Problems @sc{cvs} doesn't try to solve
+* A sample session:: A tour of basic @sc{cvs} usage
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden What is CVS?
address@hidden What is CVS?
address@hidden What is CVS?
address@hidden Introduction to CVS
address@hidden CVS, introduction to
+
address@hidden is a version control system. Using it, you can
+record the history of your source files.
+
address@hidden -- ///
address@hidden -- ///Those who cannot remember the past are condemned to repeat
it.
address@hidden -- /// -- George Santayana
address@hidden -- //////
+
address@hidden -- Insert history quote here!
+For example, bugs sometimes creep in when
+software is modified, and you might not detect the bug
+until a long time after you make the modification.
+With @sc{cvs}, you can easily retrieve old versions to see
+exactly which change caused the bug. This can
+sometimes be a big help.
+
+You could of course save every version of every file
+you have ever created. This would
+however waste an enormous amount of disk space. @sc{cvs}
+stores all the versions of a file in a single file in a
+clever way that only stores the differences between
+versions.
+
address@hidden also helps you if you are part of a group of people working
+on the same project. It is all too easy to overwrite
+each others' changes unless you are extremely careful.
+Some editors, like @sc{gnu} Emacs, try to make sure that
+the same file is never modified by two people at the
+same time. Unfortunately, if someone is using another
+editor, that safeguard will not work. @sc{cvs} solves this problem
+by insulating the different developers from each other. Every
+developer works in his own directory, and @sc{cvs} merges
+the work when each developer is done.
+
address@hidden History of CVS
address@hidden CVS, history of
address@hidden Credits (CVS program)
address@hidden Contributors (CVS program)
address@hidden started out as a bunch of shell scripts written by
+Dick Grune, posted to the newsgroup
address@hidden in the volume 6
+release of July, 1986. While no actual code from
+these shell scripts is present in the current version
+of @sc{cvs} much of the @sc{cvs} conflict resolution algorithms
+come from them.
+
+In April, 1989, Brian Berliner designed and coded @sc{cvs}.
+Jeff Polk later helped Brian with the design of the @sc{cvs}
+module and vendor branch support.
+
address@hidden Source, getting CVS source
+You can get @sc{cvs} in a variety of ways, including
+free download from the internet. For more information
+on downloading @sc{cvs} and other @sc{cvs} topics, see:
+
address@hidden
+http://www.cvshome.org/
+http://www.loria.fr/~molli/cvs-index.html
address@hidden example
+
address@hidden Mailing list
address@hidden List, mailing list
address@hidden Newsgroups
+There is a mailing list, known as @address@hidden,
+devoted to @sc{cvs}. To subscribe or
+unsubscribe
+write to
address@hidden@code{info-cvs-request@@gnu.org}}.
+If you prefer a usenet group, the right
+group is @code{comp.software.config-mgmt} which is for
address@hidden discussions (along with other configuration
+management systems). In the future, it might be
+possible to create a
address@hidden, but probably only
+if there is sufficient @sc{cvs} traffic on
address@hidden
address@hidden Other random data is that past attempts to create a
address@hidden gnu.* group have failed (the relevant authorities
address@hidden say they'll do it, but don't), and that tale was very
address@hidden skeptical of comp.software.config-mgmt.cvs when the
address@hidden subject came up around 1995 or so (for one
address@hidden thing, because creating it would be a "reorg" which
address@hidden would need to take a more comprehensive look at the
address@hidden whole comp.software.config-mgmt.* hierarchy).
+
+You can also subscribe to the @code{bug-cvs} mailing list,
+described in more detail in @ref{BUGS}. To subscribe
+send mail to @code{bug-cvs-request@@gnu.org}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden What is CVS not?
address@hidden What is CVS not?
address@hidden What is CVS not?
+
address@hidden can do a lot of things for you, but it does
+not try to be everything for everyone.
+
address@hidden @asis
address@hidden @sc{cvs} is not a build system.
+
+Though the structure of your repository and modules
+file interact with your build system
+(e.g. @file{Makefile}s), they are essentially
+independent.
+
address@hidden does not dictate how you build anything. It
+merely stores files for retrieval in a tree structure
+you devise.
+
address@hidden does not dictate how to use disk space in the
+checked out working directories. If you write your
address@hidden or scripts in every directory so they
+have to know the relative positions of everything else,
+you wind up requiring the entire repository to be
+checked out.
+
+If you modularize your work, and construct a build
+system that will share files (via links, mounts,
address@hidden in @file{Makefile}s, etc.), you can
+arrange your disk usage however you like.
+
+But you have to remember that @emph{any} such system is
+a lot of work to construct and maintain. @sc{cvs} does
+not address the issues involved.
+
+Of course, you should place the tools created to
+support such a build system (scripts, @file{Makefile}s,
+etc) under @sc{cvs}.
+
+Figuring out what files need to be rebuilt when
+something changes is, again, something to be handled
+outside the scope of @sc{cvs}. One traditional
+approach is to use @code{make} for building, and use
+some automated tool for generating the dependencies which
address@hidden uses.
+
+See @ref{Builds}, for more information on doing builds
+in conjunction with @sc{cvs}.
+
address@hidden @sc{cvs} is not a substitute for management.
+
+Your managers and project leaders are expected to talk
+to you frequently enough to make certain you are aware
+of schedules, merge points, branch names and release
+dates. If they don't, @sc{cvs} can't help.
+
address@hidden is an instrument for making sources dance to
+your tune. But you are the piper and the composer. No
+instrument plays itself or writes its own music.
+
address@hidden @sc{cvs} is not a substitute for developer communication.
+
+When faced with conflicts within a single file, most
+developers manage to resolve them without too much
+effort. But a more general definition of ``conflict''
+includes problems too difficult to solve without
+communication between developers.
+
address@hidden cannot determine when simultaneous changes
+within a single file, or across a whole collection of
+files, will logically conflict with one another. Its
+concept of a @dfn{conflict} is purely textual, arising
+when two changes to the same base file are near enough
+to spook the merge (i.e. @code{diff3}) command.
+
address@hidden does not claim to help at all in figuring out
+non-textual or distributed conflicts in program logic.
+
+For example: Say you change the arguments to function
address@hidden defined in file @file{A}. At the same time,
+someone edits file @file{B}, adding new calls to
+function @code{X} using the old arguments. You are
+outside the realm of @sc{cvs}'s competence.
+
+Acquire the habit of reading specs and talking to your
+peers.
+
+
address@hidden @sc{cvs} does not have change control
+
+Change control refers to a number of things. First of
+all it can mean @dfn{bug-tracking}, that is being able
+to keep a database of reported bugs and the status of
+each one (is it fixed? in what release? has the bug
+submitter agreed that it is fixed?). For interfacing
address@hidden to an external bug-tracking system, see the
address@hidden and @file{verifymsg} files
+(@pxref{Administrative files}).
+
+Another aspect of change control is keeping track of
+the fact that changes to several files were in fact
+changed together as one logical change. If you check
+in several files in a single @code{cvs commit}
+operation, @sc{cvs} then forgets that those files were
+checked in together, and the fact that they have the
+same log message is the only thing tying them
+together. Keeping a @sc{gnu} style @file{ChangeLog}
+can help somewhat.
address@hidden FIXME: should have an xref to a section which talks
address@hidden more about keeping ChangeLog's with CVS, but that
address@hidden section hasn't been written yet.
+
+Another aspect of change control, in some systems, is
+the ability to keep track of the status of each
+change. Some changes have been written by a developer,
+others have been reviewed by a second developer, and so
+on. Generally, the way to do this with @sc{cvs} is to
+generate a diff (using @code{cvs diff} or @code{diff})
+and email it to someone who can then apply it using the
address@hidden utility. This is very flexible, but
+depends on mechanisms outside @sc{cvs} to make sure
+nothing falls through the cracks.
+
address@hidden @sc{cvs} is not an automated testing program
+
+It should be possible to enforce mandatory use of a
+testsuite using the @code{commitinfo} file. I haven't
+heard a lot about projects trying to do that or whether
+there are subtle gotchas, however.
+
address@hidden @sc{cvs} does not have a builtin process model
+
+Some systems provide ways to ensure that changes or
+releases go through various steps, with various
+approvals as needed. Generally, one can accomplish
+this with @sc{cvs} but it might be a little more work.
+In some cases you'll want to use the @file{commitinfo},
address@hidden, @file{rcsinfo}, or @file{verifymsg}
+files, to require that certain steps be performed
+before cvs will allow a checkin. Also consider whether
+features such as branches and tags can be used to
+perform tasks such as doing work in a development tree
+and then merging certain changes over to a stable tree
+only once they have been proven.
address@hidden table
+
address@hidden
---------------------------------------------------------------------
address@hidden A sample session
address@hidden A sample session
address@hidden Example of a work-session
address@hidden Getting started
address@hidden Work-session, example of
address@hidden tc, Trivial Compiler (example)
address@hidden Trivial Compiler (example)
+
address@hidden I think an example is a pretty good way to start. But
address@hidden somewhere in here, maybe after the sample session,
address@hidden we need something which is kind of
address@hidden a "roadmap" which is more directed at sketching out
address@hidden the functionality of CVS and pointing people to
address@hidden various other parts of the manual. As it stands now
address@hidden people who read in order get dumped right into all
address@hidden manner of hair regarding remote repositories,
address@hidden creating a repository, etc.
address@hidden
address@hidden The following was in the old Basic concepts node. I don't
address@hidden know how good a job it does at introducing modules,
address@hidden or whether they need to be introduced so soon, but
address@hidden something of this sort might go into some
address@hidden introductory material somewhere.
+
+As a way of introducing @sc{cvs}, we'll go through a
+typical work-session using @sc{cvs}. The first thing
+to understand is that @sc{cvs} stores all files in a
+centralized @dfn{repository} (@pxref{Repository}); this
+section assumes that a repository is set up.
address@hidden I'm not sure that the sentence concerning the
address@hidden repository quite tells the user what they need to
address@hidden know at this point. Might need to expand on "centralized"
address@hidden slightly (maybe not here, maybe further down in the example?)
+
+Suppose you are working on a simple compiler. The source
+consists of a handful of C files and a @file{Makefile}.
+The compiler is called @samp{tc} (Trivial Compiler),
+and the repository is set up so that there is a module
+called @samp{tc}.
+
address@hidden
+* Getting the source:: Creating a workspace
+* Committing your changes:: Making your work available to others
+* Cleaning up:: Cleaning up
+* Viewing differences:: Viewing differences
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Getting the source
address@hidden Getting the source
address@hidden Getting the source
address@hidden Checking out source
address@hidden Fetching source
address@hidden Source, getting from CVS
address@hidden Checkout, example
+
+The first thing you must do is to get your own working copy of the
+source for @samp{tc}. For this, you use the @code{checkout} command:
+
address@hidden
+$ cvs checkout tc
address@hidden example
+
address@hidden
+This will create a new directory called @file{tc} and populate it with
+the source files.
+
address@hidden
+$ cd tc
+$ ls
+CVS Makefile backend.c driver.c frontend.c parser.c
address@hidden example
+
+The @file{CVS} directory is used internally by
address@hidden Normally, you should not modify or remove
+any of the files in it.
+
+You start your favorite editor, hack away at @file{backend.c}, and a couple
+of hours later you have added an optimization pass to the compiler.
+A note to @sc{rcs} and @sc{sccs} users: There is no need to lock the files that
+you want to edit. @xref{Multiple developers}, for an explanation.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Committing your changes
address@hidden Committing your changes
address@hidden Committing changes to files
address@hidden Log message entry
+
+When you have checked that the compiler is still compilable you decide
+to make a new version of @file{backend.c}. This will
+store your new @file{backend.c} in the repository and
+make it available to anyone else who is using that same
+repository.
+
address@hidden
+$ cvs commit backend.c
address@hidden example
+
address@hidden
address@hidden starts an editor, to allow you to enter a log
+message. You type in ``Added an optimization pass.'',
+save the temporary file, and exit the editor.
+
address@hidden CVSEDITOR, environment variable
address@hidden EDITOR, environment variable
+The environment variable @code{$CVSEDITOR} determines
+which editor is started. If @code{$CVSEDITOR} is not
+set, then if the environment variable @code{$EDITOR} is
+set, it will be used. If both @code{$CVSEDITOR} and
address@hidden are not set then there is a default
+which will vary with your operating system, for example
address@hidden for unix or @code{notepad} for Windows
+NT/95.
+
address@hidden VISUAL, environment variable
+In addition, @sc{cvs} checks the @code{$VISUAL} environment
+variable. Opinions vary on whether this behavior is desirable and
+whether future releases of @sc{cvs} should check @code{$VISUAL} or
+ignore it. You will be OK either way if you make sure that
address@hidden is either unset or set to the same thing as
address@hidden
+
address@hidden This probably should go into some new node
address@hidden containing detailed info on the editor, rather than
address@hidden the intro. In fact, perhaps some of the stuff with
address@hidden CVSEDITOR and -m and so on should too.
+When @sc{cvs} starts the editor, it includes a list of
+files which are modified. For the @sc{cvs} client,
+this list is based on comparing the modification time
+of the file against the modification time that the file
+had when it was last gotten or updated. Therefore, if
+a file's modification time has changed but its contents
+have not, it will show up as modified. The simplest
+way to handle this is simply not to worry about it---if
+you proceed with the commit @sc{cvs} will detect that
+the contents are not modified and treat it as an
+unmodified file. The next @code{update} will clue
address@hidden in to the fact that the file is unmodified,
+and it will reset its stored timestamp so that the file
+will not show up in future editor sessions.
address@hidden FIXCVS: Might be nice if "commit" and other commands
address@hidden would reset that timestamp too, but currently commit
address@hidden doesn't.
address@hidden FIXME: Need to talk more about the process of
address@hidden prompting for the log message. Like show an example
address@hidden of what it pops up in the editor, for example. Also
address@hidden a discussion of how to get the "a)bort, c)ontinue,
address@hidden e)dit" prompt and what to do with it. Might also
address@hidden work in the suggestion that if you want a diff, you
address@hidden should make it before running commit (someone
address@hidden suggested that the diff pop up in the editor. I'm
address@hidden not sure that is better than telling people to run
address@hidden "cvs diff" first if that is what they want, but if
address@hidden we want to tell people that, the manual possibly
address@hidden should say it).
+
+If you want to avoid
+starting an editor you can specify the log message on
+the command line using the @samp{-m} flag instead, like
+this:
+
address@hidden
+$ cvs commit -m "Added an optimization pass" backend.c
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Cleaning up
address@hidden Cleaning up
address@hidden Cleaning up
address@hidden Working copy, removing
address@hidden Removing your working copy
address@hidden Releasing your working copy
+
+Before you turn to other tasks you decide to remove your working copy of
+tc. One acceptable way to do that is of course
+
address@hidden
+$ cd ..
+$ rm -r tc
address@hidden example
+
address@hidden
+but a better way is to use the @code{release} command (@pxref{release}):
+
address@hidden
+$ cd ..
+$ cvs release -d tc
+M driver.c
+? tc
+You have [1] altered files in this repository.
+Are you sure you want to release (and delete) directory `tc': n
+** `release' aborted by user choice.
address@hidden example
+
+The @code{release} command checks that all your modifications have been
+committed. If history logging is enabled it also makes a note in the
+history file. @xref{history file}.
+
+When you use the @samp{-d} flag with @code{release}, it
+also removes your working copy.
+
+In the example above, the @code{release} command wrote a couple of lines
+of output. @samp{? tc} means that the file @file{tc} is unknown to @sc{cvs}.
+That is nothing to worry about: @file{tc} is the executable compiler,
+and it should not be stored in the repository. @xref{cvsignore},
+for information about how to make that warning go away.
address@hidden output}, for a complete explanation of
+all possible output from @code{release}.
+
address@hidden driver.c} is more serious. It means that the
+file @file{driver.c} has been modified since it was
+checked out.
+
+The @code{release} command always finishes by telling
+you how many modified files you have in your working
+copy of the sources, and then asks you for confirmation
+before deleting any files or making any note in the
+history file.
+
+You decide to play it safe and answer @kbd{n @key{RET}}
+when @code{release} asks for confirmation.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Viewing differences
address@hidden Viewing differences
address@hidden Viewing differences
address@hidden Diff
+
+You do not remember modifying @file{driver.c}, so you want to see what
+has happened to that file.
+
address@hidden
+$ cd tc
+$ cvs diff driver.c
address@hidden example
+
+This command runs @code{diff} to compare the version of @file{driver.c}
+that you checked out with your working copy. When you see the output
+you remember that you added a command line option that enabled the
+optimization pass. You check it in, and release the module.
address@hidden FIXME: we haven't yet defined the term "check in".
+
address@hidden
+$ cvs commit -m "Added an optimization pass" driver.c
+Checking in driver.c;
+/usr/local/cvsroot/tc/driver.c,v <-- driver.c
+new revision: 1.2; previous revision: 1.1
+done
+$ cd ..
+$ cvs release -d tc
+? tc
+You have [0] altered files in this repository.
+Are you sure you want to release (and delete) directory `tc': y
address@hidden example
+
address@hidden
---------------------------------------------------------------------
address@hidden Repository
address@hidden The Repository
address@hidden Repository (intro)
address@hidden Repository, example
address@hidden Layout of repository
address@hidden Typical repository
address@hidden /usr/local/cvsroot, as example repository
address@hidden cvsroot
+
+The @sc{cvs} @dfn{repository} stores a complete copy of
+all the files and directories which are under version
+control.
+
+Normally, you never access any of the files in the
+repository directly. Instead, you use @sc{cvs}
+commands to get your own copy of the files into a
address@hidden directory}, and then
+work on that copy. When you've finished a set of
+changes, you check (or @dfn{commit}) them back into the
+repository. The repository then contains the changes
+which you have made, as well as recording exactly what
+you changed, when you changed it, and other such
+information. Note that the repository is not a
+subdirectory of the working directory, or vice versa;
+they should be in separate locations.
address@hidden Need some example, e.g. repository
address@hidden /usr/local/cvsroot; working directory
address@hidden /home/joe/sources. But this node is too long
address@hidden as it is; need a little reorganization...
+
address@hidden :local:, setting up
address@hidden can access a repository by a variety of
+means. It might be on the local computer, or it might
+be on a computer across the room or across the world.
+To distinguish various ways to access a repository, the
+repository name can start with an @dfn{access method}.
+For example, the access method @code{:local:} means to
+access a repository directory, so the repository
address@hidden:local:/usr/local/cvsroot} means that the
+repository is in @file{/usr/local/cvsroot} on the
+computer running @sc{cvs}. For information on other
+access methods, see @ref{Remote repositories}.
+
address@hidden Can se say this more concisely? Like by passing
address@hidden more of the buck to the Remote repositories node?
+If the access method is omitted, then if the repository
+starts with @samp{/}, then @code{:local:} is
+assumed. If it does not start with @samp{/} then either
address@hidden:ext:} or @code{:server:} is assumed. For
+example, if you have a local repository in
address@hidden/usr/local/cvsroot}, you can use
address@hidden/usr/local/cvsroot} instead of
address@hidden:local:/usr/local/cvsroot}. But if (under
+Windows NT, for example) your local repository is
address@hidden:\src\cvsroot}, then you must specify the access
+method, as in @code{:local:c:/src/cvsroot}.
+
address@hidden This might appear to go in Repository storage, but
address@hidden actually it is describing something which is quite
address@hidden user-visible, when you do a "cvs co CVSROOT". This
address@hidden isn't necessary the perfect place for that, though.
+The repository is split in two parts. @file{$CVSROOT/CVSROOT} contains
+administrative files for @sc{cvs}. The other directories contain the actual
+user-defined modules.
+
address@hidden
+* Specifying a repository:: Telling CVS where your repository is
+* Repository storage:: The structure of the repository
+* Working directory storage:: The structure of working directories
+* Intro administrative files:: Defining modules
+* Multiple repositories:: Multiple repositories
+* Creating a repository:: Creating a repository
+* Backing up:: Backing up a repository
+* Moving a repository:: Moving a repository
+* Remote repositories:: Accessing repositories on remote machines
+* Read-only access:: Granting read-only access to the repository
+* Server temporary directory:: The server creates temporary directories
address@hidden menu
+
address@hidden Specifying a repository
address@hidden Telling CVS where your repository is
+
+There are several ways to tell @sc{cvs}
+where to find the repository. You can name the
+repository on the command line explicitly, with the
address@hidden (for "directory") option:
+
address@hidden
+cvs -d /usr/local/cvsroot checkout yoyodyne/tc
address@hidden example
+
address@hidden .profile, setting CVSROOT in
address@hidden .cshrc, setting CVSROOT in
address@hidden .tcshrc, setting CVSROOT in
address@hidden .bashrc, setting CVSROOT in
address@hidden CVSROOT, environment variable
+ Or you can set the @code{$CVSROOT} environment
+variable to an absolute path to the root of the
+repository, @file{/usr/local/cvsroot} in this example.
+To set @code{$CVSROOT}, @code{csh} and @code{tcsh}
+users should have this line in their @file{.cshrc} or
address@hidden files:
+
address@hidden
+setenv CVSROOT /usr/local/cvsroot
address@hidden example
+
address@hidden
address@hidden and @code{bash} users should instead have these lines in their
address@hidden or @file{.bashrc}:
+
address@hidden
+CVSROOT=/usr/local/cvsroot
+export CVSROOT
address@hidden example
+
address@hidden Root file, in CVS directory
address@hidden CVS/Root file
+ A repository specified with @code{-d} will
+override the @code{$CVSROOT} environment variable.
+Once you've checked a working copy out from the
+repository, it will remember where its repository is
+(the information is recorded in the
address@hidden/Root} file in the working copy).
+
+The @code{-d} option and the @file{CVS/Root} file both
+override the @code{$CVSROOT} environment variable. If
address@hidden option differs from @file{CVS/Root}, the
+former is used. Of course, for proper operation they
+should be two ways of referring to the same repository.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Repository storage
address@hidden How data is stored in the repository
address@hidden Repository, how data is stored
+
+For most purposes it isn't important @emph{how}
address@hidden stores information in the repository. In
+fact, the format has changed in the past, and is likely
+to change in the future. Since in almost all cases one
+accesses the repository via @sc{cvs} commands, such
+changes need not be disruptive.
+
+However, in some cases it may be necessary to
+understand how @sc{cvs} stores data in the repository,
+for example you might need to track down @sc{cvs} locks
+(@pxref{Concurrency}) or you might need to deal with
+the file permissions appropriate for the repository.
+
address@hidden
+* Repository files:: What files are stored in the repository
+* File permissions:: File permissions
+* Windows permissions:: Issues specific to Windows
+* Attic:: Some files are stored in the Attic
+* CVS in repository:: Additional information in CVS directory
+* Locks:: CVS locks control concurrent accesses
+* CVSROOT storage:: A few things about CVSROOT are different
address@hidden menu
+
address@hidden Repository files
address@hidden Where files are stored within the repository
+
address@hidden @cindex Filenames, legal
address@hidden @cindex Legal filenames
address@hidden Somewhere we need to say something about legitimate
address@hidden characters in filenames in working directory and
address@hidden repository. Not "/" (not even on non-unix). And
address@hidden here is a specific set of issues:
address@hidden Files starting with a - are handled inconsistently. They can not
address@hidden be added to a repository with an add command, because it they
are
address@hidden interpreted as a switch. They can appear in a repository if
they are
address@hidden part of a tree that is imported. They can not be removed from
the tree
address@hidden once they are there.
address@hidden Note that "--" *is* supported (as a
address@hidden consequence of using GNU getopt). Should document
address@hidden this somewhere ("Common options"?). The other usual technique,
address@hidden "./-foo", isn't as effective, at least for "cvs add"
address@hidden which doesn't support pathnames containing "/".
+
+The overall structure of the repository is a directory
+tree corresponding to the directories in the working
+directory. For example, supposing the repository is in
+
address@hidden
+/usr/local/cvsroot
address@hidden example
+
address@hidden
+here is a possible directory tree (showing only the
+directories):
+
address@hidden
address@hidden/usr}
+ |
+ address@hidden
+ | |
+ | address@hidden
+ | | |
+ | | address@hidden
+ | (administrative files)
+ |
+ address@hidden
+ | |
+ | address@hidden
+ | | (source code to @sc{gnu} diff)
+ | |
+ | address@hidden
+ | | (source code to @sc{rcs})
+ | |
+ | address@hidden
+ | (source code to @sc{cvs})
+ |
+ address@hidden
+ |
+ address@hidden
+ | |
+ | address@hidden
+ | |
+ | address@hidden
+ |
+ +--(other Yoyodyne software)
address@hidden example
+
+With the directories are @dfn{history files} for each file
+under version control. The name of the history file is
+the name of the corresponding file with @samp{,v}
+appended to the end. Here is what the repository for
+the @file{yoyodyne/tc} directory might look like:
address@hidden FIXME: Should also mention CVS (CVSREP)
address@hidden FIXME? Should we introduce Attic with an xref to
address@hidden Attic? Not sure whether that is a good idea or not.
address@hidden
+ @code{$CVSROOT}
+ |
+ address@hidden
+ | |
+ | address@hidden
+ | | |
+ address@hidden,v}
+ address@hidden,v}
+ address@hidden,v}
+ address@hidden,v}
+ address@hidden,v}
+ address@hidden
+ | |
+ | address@hidden,v}
+ |
+ address@hidden
+ |
+ address@hidden,v}
+ address@hidden,v}
address@hidden example
+
address@hidden History files
address@hidden RCS history files
address@hidden The first sentence, about what history files
address@hidden contain, is kind of redundant with our intro to what the
address@hidden repository does in node Repository....
+The history files contain, among other things, enough
+information to recreate any revision of the file, a log
+of all commit messages and the user-name of the person
+who committed the revision. The history files are
+known as @dfn{RCS files}, because the first program to
+store files in that format was a version control system
+known as @sc{rcs}. For a full
+description of the file format, see the @code{man} page
address@hidden(5)}, distributed with @sc{rcs}, or the
+file @file{doc/RCSFILES} in the @sc{cvs} source
+distribution. This
+file format has become very common---many systems other
+than @sc{cvs} or @sc{rcs} can at least import history
+files in this format.
address@hidden FIXME: Think about including documentation for this
address@hidden rather than citing it? In the long run, getting
address@hidden this to be a standard (not sure if we can cope with
address@hidden a standards process as formal as IEEE/ANSI/ISO/etc,
address@hidden though...) is the way to go, so maybe citing is
address@hidden better.
+
+The @sc{rcs} files used in @sc{cvs} differ in a few
+ways from the standard format. The biggest difference
+is magic branches; for more information see @ref{Magic
+branch numbers}. Also in @sc{cvs} the valid tag names
+are a subset of what @sc{rcs} accepts; for @sc{cvs}'s
+rules see @ref{Tags}.
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden File permissions
address@hidden File permissions
address@hidden -- Move this to @node Creating a repository or similar
address@hidden Security, file permissions in repository
address@hidden File permissions, general
address@hidden Permissions, general
address@hidden FIXME: we need to somehow reflect "permissions in
address@hidden repository" versus "permissions in working
address@hidden directory" in the index entries.
address@hidden Group
address@hidden Read-only files, in repository
+All @samp{,v} files are created read-only, and you
+should not change the permission of those files. The
+directories inside the repository should be writable by
+the persons that have permission to modify the files in
+each directory. This normally means that you must
+create a UNIX group (see group(5)) consisting of the
+persons that are to edit the files in a project, and
+set up the repository so that it is that group that
+owns the directory.
+(On some systems, you also need to set the set-group-ID-on-execution bit
+on the repository directories (see chmod(1)) so that newly-created files
+and directories get the group-ID of the parent directory rather than
+that of the current process.)
+
address@hidden See also comment in commitinfo node regarding cases
address@hidden which are really awkward with unix groups.
+
+This means that you can only control access to files on
+a per-directory basis.
+
+Note that users must also have write access to check
+out files, because @sc{cvs} needs to create lock files
+(@pxref{Concurrency}). You can use LockDir in CVSROOT/config
+to put the lock files somewhere other than in the repository
+if you want to allow read-only access to some directories
+(@pxref{config}).
+
address@hidden CVS seems to use CVSUMASK in picking permissions for
address@hidden val-tags, but maybe we should say more about this.
address@hidden Like val-tags gets created by someone who doesn't
address@hidden have CVSUMASK set right?
+Also note that users must have write access to the
address@hidden/val-tags} file. @sc{cvs} uses it to keep
+track of what tags are valid tag names (it is sometimes
+updated when tags are used, as well as when they are
+created).
+
+Each @sc{rcs} file will be owned by the user who last
+checked it in. This has little significance; what
+really matters is who owns the directories.
+
address@hidden CVSUMASK, environment variable
address@hidden Umask, for repository files
address@hidden tries to set up reasonable file permissions
+for new directories that are added inside the tree, but
+you must fix the permissions manually when a new
+directory should have different permissions than its
+parent directory. If you set the @code{CVSUMASK}
+environment variable that will control the file
+permissions which @sc{cvs} uses in creating directories
+and/or files in the repository. @code{CVSUMASK} does
+not affect the file permissions in the working
+directory; such files have the permissions which are
+typical for newly created files, except that sometimes
address@hidden creates them read-only (see the sections on
+watches, @ref{Setting a watch}; -r, @ref{Global
+options}; or @code{CVSREAD}, @ref{Environment variables}).
address@hidden FIXME: Need more discussion of which
address@hidden group should own the file in the repository.
address@hidden Include a somewhat detailed example of the usual
address@hidden case where CVSUMASK is 007, the developers are all
address@hidden in a group, and that group owns stuff in the
address@hidden repository. Need to talk about group ownership of
address@hidden newly-created directories/files (on some unices,
address@hidden such as SunOS4, setting the setgid bit on the
address@hidden directories will make files inherit the directory's
address@hidden group. On other unices, your mileage may vary. I
address@hidden can't remember what POSIX says about this, if
address@hidden anything).
+
+Note that using the client/server @sc{cvs}
+(@pxref{Remote repositories}), there is no good way to
+set @code{CVSUMASK}; the setting on the client machine
+has no effect. If you are connecting with @code{rsh}, you
+can set @code{CVSUMASK} in @file{.bashrc} or @file{.cshrc}, as
+described in the documentation for your operating
+system. This behavior might change in future versions
+of @sc{cvs}; do not rely on the setting of
address@hidden on the client having no effect.
address@hidden FIXME: need to explain what a umask is or cite
address@hidden someplace which does.
address@hidden
address@hidden There is also a larger (largely separate) issue
address@hidden about the meaning of CVSUMASK in a non-unix context.
address@hidden For example, whether there is
address@hidden an equivalent which fits better into other
address@hidden protection schemes like POSIX.6, VMS, &c.
address@hidden
address@hidden FIXME: Need one place which discusses this
address@hidden read-only files thing. Why would one use -r or
address@hidden CVSREAD? Why would one use watches? How do they
address@hidden interact?
address@hidden
address@hidden FIXME: We need to state
address@hidden whether using CVSUMASK removes the need for manually
address@hidden fixing permissions (in fact, if we are going to mention
address@hidden manually fixing permission, we better document a lot
address@hidden better just what we mean by "fix").
+
+Using pserver, you will generally need stricter
+permissions on the @sc{cvsroot} directory and
+directories above it in the tree; see @ref{Password
+authentication security}.
+
address@hidden Setuid
address@hidden Setgid
address@hidden Security, setuid
address@hidden Installed images (VMS)
+Some operating systems have features which allow a
+particular program to run with the ability to perform
+operations which the caller of the program could not.
+For example, the set user ID (setuid) or set group ID
+(setgid) features of unix or the installed image
+feature of VMS. @sc{cvs} was not written to use such
+features and therefore attempting to install @sc{cvs} in
+this fashion will provide protection against only
+accidental lapses; anyone who is trying to circumvent
+the measure will be able to do so, and depending on how
+you have set it up may gain access to more than just
address@hidden You may wish to instead consider pserver. It
+shares some of the same attributes, in terms of
+possibly providing a false sense of security or opening
+security holes wider than the ones you are trying to
+fix, so read the documentation on pserver security
+carefully if you are considering this option
+(@ref{Password authentication security}).
+
address@hidden Windows permissions
address@hidden File Permission issues specific to Windows
address@hidden Windows, and permissions
address@hidden File permissions, Windows-specific
address@hidden Permissions, Windows-specific
+
+Some file permission issues are specific to Windows
+operating systems (Windows 95, Windows NT, and
+presumably future operating systems in this family.
+Some of the following might apply to OS/2 but I'm not
+sure).
+
+If you are using local @sc{cvs} and the repository is on a
+networked file system which is served by the Samba SMB
+server, some people have reported problems with
+permissions. Enabling WRITE=YES in the samba
+configuration is said to fix/workaround it.
+Disclaimer: I haven't investigated enough to know the
+implications of enabling that option, nor do I know
+whether there is something which @sc{cvs} could be doing
+differently in order to avoid the problem. If you find
+something out, please let us know as described in
address@hidden
+
address@hidden Attic
address@hidden The attic
address@hidden Attic
+
+You will notice that sometimes @sc{cvs} stores an
address@hidden file in the @code{Attic}. For example, if the
address@hidden is @file{/usr/local/cvsroot} and we are
+talking about the file @file{backend.c} in the
+directory @file{yoyodyne/tc}, then the file normally
+would be in
+
address@hidden
+/usr/local/cvsroot/yoyodyne/tc/backend.c,v
address@hidden example
+
address@hidden
+but if it goes in the attic, it would be in
+
address@hidden
+/usr/local/cvsroot/yoyodyne/tc/Attic/backend.c,v
address@hidden example
+
address@hidden
address@hidden Dead state
+instead. It should not matter from a user point of
+view whether a file is in the attic; @sc{cvs} keeps
+track of this and looks in the attic when it needs to.
+But in case you want to know, the rule is that the RCS
+file is stored in the attic if and only if the head
+revision on the trunk has state @code{dead}. A
address@hidden state means that file has been removed, or
+never added, for that revision. For example, if you
+add a file on a branch, it will have a trunk revision
+in @code{dead} state, and a branch revision in a
address@hidden state.
address@hidden Probably should have some more concrete examples
address@hidden here, or somewhere (not sure exactly how we should
address@hidden arrange the discussion of the dead state, versus
address@hidden discussion of the attic).
+
address@hidden CVS in repository
address@hidden The CVS directory in the repository
address@hidden CVS directory, in repository
+
+The @file{CVS} directory in each repository directory
+contains information such as file attributes (in a file
+called @file{CVS/fileattr}. In the
+future additional files may be added to this directory,
+so implementations should silently ignore additional
+files.
+
+This behavior is implemented only by @sc{cvs} 1.7 and
+later; for details see @ref{Watches Compatibility}.
+
+The format of the fileattr file is a series of entries
+of the following form (where @address@hidden and @address@hidden
+means the text between the braces can be repeated zero
+or more times):
+
address@hidden @var{filename} <tab> @var{attrname} = @var{attrval}
+ @{; @var{attrname} = @address@hidden <linefeed>
+
address@hidden is @samp{F} for a file, in which case the entry specifies the
+attributes for that file.
+
address@hidden is @samp{D},
+and @var{filename} empty, to specify default attributes
+to be used for newly added files.
+
+Other @var{ent-type} are reserved for future expansion. @sc{cvs} 1.9 and older
+will delete them any time it writes file attributes.
address@hidden 1.10 and later will preserve them.
+
+Note that the order of the lines is not significant;
+a program writing the fileattr file may
+rearrange them at its convenience.
+
+There is currently no way of quoting tabs or linefeeds in the
+filename, @samp{=} in @var{attrname},
address@hidden;} in @var{attrval}, etc. Note: some implementations also
+don't handle a NUL character in any of the fields, but
+implementations are encouraged to allow it.
+
+By convention, @var{attrname} starting with @samp{_} is for an attribute given
+special meaning by @sc{cvs}; other @var{attrname}s are for user-defined
attributes
+(or will be, once implementations start supporting user-defined attributes).
+
+Builtin attributes:
+
address@hidden @code
address@hidden _watched
+Present means the file is watched and should be checked out
+read-only.
+
address@hidden _watchers
+Users with watches for this file. Value is
address@hidden > @var{type} @{ , @var{watcher} > @var{type} @}
+where @var{watcher} is a username, and @var{type}
+is zero or more of edit,unedit,commit separated by
address@hidden (that is, nothing if none; there is no "none" or "all" keyword).
+
address@hidden _editors
+Users editing this file. Value is
address@hidden > @var{val} @{ , @var{editor} > @var{val} @}
+where @var{editor} is a username, and @var{val} is
address@hidden@address@hidden, where
address@hidden is when the @code{cvs edit} command (or
+equivalent) happened,
+and @var{hostname} and @var{pathname} are for the working directory.
address@hidden table
+
+Example:
+
address@hidden FIXME: sanity.sh should contain a similar test case
address@hidden so we can compare this example from something from
address@hidden Real Life(TM). See cvsclient.texi (under Notify) for more
address@hidden discussion of the date format of _editors.
address@hidden
+Ffile1 _watched=;_watchers=joe>edit,mary>commit
+Ffile2 _watched=;_editors=sue>8 Jan 1975+workstn1+/home/sue/cvs
+D _watched=
address@hidden example
+
address@hidden
+means that the file @file{file1} should be checked out
+read-only. Furthermore, joe is watching for edits and
+mary is watching for commits. The file @file{file2}
+should be checked out read-only; sue started editing it
+on 8 Jan 1975 in the directory @file{/home/sue/cvs} on
+the machine @code{workstn1}. Future files which are
+added should be checked out read-only. To represent
+this example here, we have shown a space after
address@hidden, @samp{Ffile1}, and @samp{Ffile2}, but in fact
+there must be a single tab character there and no spaces.
+
address@hidden Locks
address@hidden CVS locks in the repository
+
address@hidden #cvs.rfl, technical details
address@hidden #cvs.wfl, technical details
address@hidden #cvs.lock, technical details
address@hidden Locks, cvs, technical details
+For an introduction to @sc{cvs} locks focusing on
+user-visible behavior, see @ref{Concurrency}. The
+following section is aimed at people who are writing
+tools which want to access a @sc{cvs} repository without
+interfering with other tools accessing the same
+repository. If you find yourself confused by concepts
+described here, like @dfn{read lock}, @dfn{write lock},
+and @dfn{deadlock}, you might consult the literature on
+operating systems or databases.
+
address@hidden #cvs.tfl
+Any file in the repository with a name starting
+with @file{#cvs.rfl.} is a read lock. Any file in
+the repository with a name starting with
address@hidden is a write lock. Old versions of @sc{cvs}
+(before @sc{cvs} 1.5) also created files with names starting
+with @file{#cvs.tfl}, but they are not discussed here.
+The directory @file{#cvs.lock} serves as a master
+lock. That is, one must obtain this lock first before
+creating any of the other locks.
+
+To obtain a readlock, first create the @file{#cvs.lock}
+directory. This operation must be atomic (which should
+be true for creating a directory under most operating
+systems). If it fails because the directory already
+existed, wait for a while and try again. After
+obtaining the @file{#cvs.lock} lock, create a file
+whose name is @file{#cvs.rfl.} followed by information
+of your choice (for example, hostname and process
+identification number). Then remove the
address@hidden directory to release the master lock.
+Then proceed with reading the repository. When you are
+done, remove the @file{#cvs.rfl} file to release the
+read lock.
+
+To obtain a writelock, first create the
address@hidden directory, as with a readlock. Then
+check that there are no files whose names start with
address@hidden If there are, remove
address@hidden, wait for a while, and try again. If
+there are no readers, then create a file whose name is
address@hidden followed by information of your choice
+(for example, hostname and process identification
+number). Hang on to the @file{#cvs.lock} lock. Proceed
+with writing the repository. When you are done, first
+remove the @file{#cvs.wfl} file and then the
address@hidden directory. Note that unlike the
address@hidden file, the @file{#cvs.wfl} file is just
+informational; it has no effect on the locking operation
+beyond what is provided by holding on to the
address@hidden lock itself.
+
+Note that each lock (writelock or readlock) only locks
+a single directory in the repository, including
address@hidden and @file{CVS} but not including
+subdirectories which represent other directories under
+version control. To lock an entire tree, you need to
+lock each directory (note that if you fail to obtain
+any lock you need, you must release the whole tree
+before waiting and trying again, to avoid deadlocks).
+
+Note also that @sc{cvs} expects writelocks to control
+access to individual @file{foo,v} files. @sc{rcs} has
+a scheme where the @file{,foo,} file serves as a lock,
+but @sc{cvs} does not implement it and so taking out a
address@hidden writelock is recommended. See the comments at
+rcs_internal_lockfile in the @sc{cvs} source code for
+further discussion/rationale.
+
address@hidden CVSROOT storage
address@hidden How files are stored in the CVSROOT directory
address@hidden CVSROOT, storage of files
+
+The @file{$CVSROOT/CVSROOT} directory contains the
+various administrative files. In some ways this
+directory is just like any other directory in the
+repository; it contains @sc{rcs} files whose names end
+in @samp{,v}, and many of the @sc{cvs} commands operate
+on it the same way. However, there are a few
+differences.
+
+For each administrative file, in addition to the
address@hidden file, there is also a checked out copy of the
+file. For example, there is an @sc{rcs} file
address@hidden,v} and a file @file{loginfo} which
+contains the latest revision contained in
address@hidden,v}. When you check in an administrative
+file, @sc{cvs} should print
+
address@hidden
+cvs commit: Rebuilding administrative file database
address@hidden example
+
address@hidden
+and update the checked out copy in
address@hidden/CVSROOT}. If it does not, there is
+something wrong (@pxref{BUGS}). To add your own files
+to the files to be updated in this fashion, you can add
+them to the @file{checkoutlist} administrative file
+(@pxref{checkoutlist}).
+
address@hidden modules.db
address@hidden modules.pag
address@hidden modules.dir
+By default, the @file{modules} file behaves as
+described above. If the modules file is very large,
+storing it as a flat text file may make looking up
+modules slow (I'm not sure whether this is as much of a
+concern now as when @sc{cvs} first evolved this
+feature; I haven't seen benchmarks). Therefore, by
+making appropriate edits to the @sc{cvs} source code
+one can store the modules file in a database which
+implements the @code{ndbm} interface, such as Berkeley
+db or GDBM. If this option is in use, then the modules
+database will be stored in the files @file{modules.db},
address@hidden, and/or @file{modules.dir}.
address@hidden I think fileattr also will use the database stuff.
address@hidden Anything else?
+
+For information on the meaning of the various
+administrative files, see @ref{Administrative files}.
+
address@hidden Working directory storage
address@hidden How data is stored in the working directory
+
address@hidden FIXME: Somewhere we should discuss timestamps (test
address@hidden case "stamps" in sanity.sh). But not here. Maybe
address@hidden in some kind of "working directory" chapter which
address@hidden would encompass the "Builds" one? But I'm not sure
address@hidden whether that is a good organization (is it based on
address@hidden what the user wants to do?).
+
address@hidden CVS directory, in working directory
+While we are discussing @sc{cvs} internals which may
+become visible from time to time, we might as well talk
+about what @sc{cvs} puts in the @file{CVS} directories
+in the working directories. As with the repository,
address@hidden handles this information and one can usually
+access it via @sc{cvs} commands. But in some cases it
+may be useful to look at it, and other programs, such
+as the @code{jCVS} graphical user interface or the
address@hidden package for emacs, may need to look at it.
+Such programs should follow the recommendations in this
+section if they hope to be able to work with other
+programs which use those files, including future
+versions of the programs just mentioned and the
+command-line @sc{cvs} client.
+
+The @file{CVS} directory contains several files.
+Programs which are reading this directory should
+silently ignore files which are in the directory but
+which are not documented here, to allow for future
+expansion.
+
+The files are stored according to the text file
+convention for the system in question. This means that
+working directories are not portable between systems
+with differing conventions for storing text files.
+This is intentional, on the theory that the files being
+managed by @sc{cvs} probably will not be portable between
+such systems either.
+
address@hidden @file
address@hidden Root
+This file contains the current @sc{cvs} root, as
+described in @ref{Specifying a repository}.
+
address@hidden Repository file, in CVS directory
address@hidden CVS/Repository file
address@hidden Repository
+This file contains the directory within the repository
+which the current directory corresponds with. It can
+be either an absolute pathname or a relative pathname;
address@hidden has had the ability to read either format
+since at least version 1.3 or so. The relative
+pathname is relative to the root, and is the more
+sensible approach, but the absolute pathname is quite
+common and implementations should accept either. For
+example, after the command
+
address@hidden
+cvs -d :local:/usr/local/cvsroot checkout yoyodyne/tc
address@hidden example
+
address@hidden
address@hidden will contain
+
address@hidden
+:local:/usr/local/cvsroot
address@hidden example
+
address@hidden
+and @file{Repository} will contain either
+
address@hidden
+/usr/local/cvsroot/yoyodyne/tc
address@hidden example
+
address@hidden
+or
+
address@hidden
+yoyodyne/tc
address@hidden example
+
+If the particular working directory does not correspond
+to a directory in the repository, then @file{Repository}
+should contain @file{CVSROOT/Emptydir}.
address@hidden Emptydir, in CVSROOT directory
address@hidden CVSROOT/Emptydir directory
+
address@hidden Entries file, in CVS directory
address@hidden CVS/Entries file
address@hidden Entries
+This file lists the files and directories in the
+working directory.
+The first character of each line indicates what sort of
+line it is. If the character is unrecognized, programs
+reading the file should silently skip that line, to
+allow for future expansion.
+
+If the first character is @samp{/}, then the format is:
+
address@hidden
+/@var{name}/@var{revision}/@address@hidden/@var{options}/@var{tagdate}
address@hidden example
+
address@hidden
+where @samp{[} and @samp{]} are not part of the entry,
+but instead indicate that the @samp{+} and conflict
+marker are optional. @var{name} is the name of the
+file within the directory. @var{revision} is the
+revision that the file in the working derives from, or
address@hidden for an added file, or @samp{-} followed by a
+revision for a removed file. @var{timestamp} is the
+timestamp of the file at the time that @sc{cvs} created
+it; if the timestamp differs with the actual
+modification time of the file it means the file has
+been modified. It is stored in
+the format used by the ISO C asctime() function (for
+example, @samp{Sun Apr 7 01:29:26 1996}). One may
+write a string which is not in that format, for
+example, @samp{Result of merge}, to indicate that the
+file should always be considered to be modified. This
+is not a special case; to see whether a file is
+modified a program should take the timestamp of the file
+and simply do a string compare with @var{timestamp}.
+If there was a conflict, @var{conflict} can be set to
+the modification time of the file after the file has been
+written with conflict markers (@pxref{Conflicts example}).
+Thus if @var{conflict} is subsequently the same as the actual
+modification time of the file it means that the user
+has obviously not resolved the conflict. @var{options}
+contains sticky options (for example @samp{-kb} for a
+binary file). @var{tagdate} contains @samp{T} followed
+by a tag name, or @samp{D} for a date, followed by a
+sticky tag or date. Note that if @var{timestamp}
+contains a pair of timestamps separated by a space,
+rather than a single timestamp, you are dealing with a
+version of @sc{cvs} earlier than @sc{cvs} 1.5 (not
+documented here).
+
+The timezone on the timestamp in CVS/Entries (local or
+universal) should be the same as the operating system
+stores for the timestamp of the file itself. For
+example, on Unix the file's timestamp is in universal
+time (UT), so the timestamp in CVS/Entries should be
+too. On @sc{vms}, the file's timestamp is in local
+time, so @sc{cvs} on @sc{vms} should use local time.
+This rule is so that files do not appear to be modified
+merely because the timezone changed (for example, to or
+from summer time).
address@hidden See comments and calls to gmtime() and friends in
address@hidden src/vers_ts.c (function time_stamp).
+
+If the first character of a line in @file{Entries} is
address@hidden, then it indicates a subdirectory. @samp{D}
+on a line all by itself indicates that the program
+which wrote the @file{Entries} file does record
+subdirectories (therefore, if there is such a line and
+no other lines beginning with @samp{D}, one knows there
+are no subdirectories). Otherwise, the line looks
+like:
+
address@hidden
+D/@var{name}/@var{filler1}/@var{filler2}/@var{filler3}/@var{filler4}
address@hidden example
+
address@hidden
+where @var{name} is the name of the subdirectory, and
+all the @var{filler} fields should be silently ignored,
+for future expansion. Programs which modify
address@hidden files should preserve these fields.
+
+The lines in the @file{Entries} file can be in any order.
+
address@hidden Entries.Log file, in CVS directory
address@hidden CVS/Entries.Log file
address@hidden Entries.Log
+This file does not record any information beyond that
+in @file{Entries}, but it does provide a way to update
+the information without having to rewrite the entire
address@hidden file, including the ability to preserve
+the information even if the program writing
address@hidden and @file{Entries.Log} abruptly aborts.
+Programs which are reading the @file{Entries} file
+should also check for @file{Entries.Log}. If the latter
+exists, they should read @file{Entries} and then apply
+the changes mentioned in @file{Entries.Log}. After
+applying the changes, the recommended practice is to
+rewrite @file{Entries} and then delete @file{Entries.Log}.
+The format of a line in @file{Entries.Log} is a single
+character command followed by a space followed by a
+line in the format specified for a line in
address@hidden The single character command is
address@hidden to indicate that the entry is being added,
address@hidden to indicate that the entry is being removed,
+or any other character to indicate that the entire line
+in @file{Entries.Log} should be silently ignored (for
+future expansion). If the second character of the line
+in @file{Entries.Log} is not a space, then it was
+written by an older version of @sc{cvs} (not documented
+here).
+
+Programs which are writing rather than reading can
+safely ignore @file{Entries.Log} if they so choose.
+
address@hidden Entries.Backup file, in CVS directory
address@hidden CVS/Entries.Backup file
address@hidden Entries.Backup
+This is a temporary file. Recommended usage is to
+write a new entries file to @file{Entries.Backup}, and
+then to rename it (atomically, where possible) to @file{Entries}.
+
address@hidden Entries.Static file, in CVS directory
address@hidden CVS/Entries.Static file
address@hidden Entries.Static
+The only relevant thing about this file is whether it
+exists or not. If it exists, then it means that only
+part of a directory was gotten and @sc{cvs} will
+not create additional files in that directory. To
+clear it, use the @code{update} command with the
address@hidden option, which will get the additional files
+and remove @file{Entries.Static}.
address@hidden FIXME: This needs to be better documented, in places
address@hidden other than Working Directory Storage.
address@hidden FIXCVS: The fact that this setting exists needs to
address@hidden be more visible to the user. For example "cvs
address@hidden status foo", in the case where the file would be
address@hidden gotten except for Entries.Static, might say
address@hidden something to distinguish this from other cases.
address@hidden One thing that periodically gets suggested is to
address@hidden have "cvs update" print something when it skips
address@hidden files due to Entries.Static, but IMHO that kind of
address@hidden noise pretty much makes the Entries.Static feature
address@hidden useless.
+
address@hidden Tag file, in CVS directory
address@hidden CVS/Tag file
address@hidden Sticky tags/dates, per-directory
address@hidden Per-directory sticky tags/dates
address@hidden Tag
+This file contains per-directory sticky tags or dates.
+The first character is @samp{T} for a branch tag,
address@hidden for a non-branch tag, or @samp{D} for a date,
+or another character to mean the file should be
+silently ignored, for future expansion. This character
+is followed by the tag or date. Note that
+per-directory sticky tags or dates are used for things
+like applying to files which are newly added; they
+might not be the same as the sticky tags or dates on
+individual files. For general information on sticky
+tags and dates, see @ref{Sticky tags}.
address@hidden FIXME: This needs to be much better documented,
address@hidden preferably not in the context of "working directory
address@hidden storage".
address@hidden FIXME: The Sticky tags node needs to discuss, or xref to
address@hidden someplace which discusses, per-directory sticky
address@hidden tags and the distinction with per-file sticky tags.
+
address@hidden Notify file, in CVS directory
address@hidden CVS/Notify file
address@hidden Notify
+This file stores notifications (for example, for
address@hidden or @code{unedit}) which have not yet been
+sent to the server. Its format is not yet documented
+here.
+
address@hidden Notify.tmp file, in CVS directory
address@hidden CVS/Notify.tmp file
address@hidden Notify.tmp
+This file is to @file{Notify} as @file{Entries.Backup}
+is to @file{Entries}. That is, to write @file{Notify},
+first write the new contents to @file{Notify.tmp} and
+then (atomically where possible), rename it to
address@hidden
+
address@hidden Base directory, in CVS directory
address@hidden CVS/Base directory
address@hidden Base
+If watches are in use, then an @code{edit} command
+stores the original copy of the file in the @file{Base}
+directory. This allows the @code{unedit} command to
+operate even if it is unable to communicate with the
+server.
+
address@hidden Baserev file, in CVS directory
address@hidden CVS/Baserev file
address@hidden Baserev
+The file lists the revision for each of the files in
+the @file{Base} directory. The format is:
+
address@hidden
address@hidden/@var{rev}/@var{expansion}
address@hidden example
+
address@hidden
+where @var{expansion} should be ignored, to allow for
+future expansion.
+
address@hidden Baserev.tmp file, in CVS directory
address@hidden CVS/Baserev.tmp file
address@hidden Baserev.tmp
+This file is to @file{Baserev} as @file{Entries.Backup}
+is to @file{Entries}. That is, to write @file{Baserev},
+first write the new contents to @file{Baserev.tmp} and
+then (atomically where possible), rename it to
address@hidden
+
address@hidden Template file, in CVS directory
address@hidden CVS/Template file
address@hidden Template
+This file contains the template specified by the
address@hidden file (@pxref{rcsinfo}). It is only used
+by the client; the non-client/server @sc{cvs} consults
address@hidden directly.
address@hidden table
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Intro administrative files
address@hidden The administrative files
address@hidden Administrative files (intro)
address@hidden Modules file
address@hidden CVSROOT, module name
address@hidden Defining modules (intro)
+
address@hidden FIXME: this node should be reorganized into "general
address@hidden information about admin files" and put the "editing
address@hidden admin files" stuff up front rather than jumping into
address@hidden the details of modules right away. Then the
address@hidden Administrative files node can go away, the information
address@hidden on each admin file distributed to a place appropriate
address@hidden to its function, and this node can contain a table
address@hidden listing each file and a @ref to its detailed description.
+
+The directory @file{$CVSROOT/CVSROOT} contains some @dfn{administrative
+files}. @xref{Administrative files}, for a complete description.
+You can use @sc{cvs} without any of these files, but
+some commands work better when at least the
address@hidden file is properly set up.
+
+The most important of these files is the @file{modules}
+file. It defines all modules in the repository. This
+is a sample @file{modules} file.
+
address@hidden FIXME: The CVSROOT line is a goofy example now that
address@hidden mkmodules doesn't exist.
address@hidden
+CVSROOT CVSROOT
+modules CVSROOT modules
+cvs gnu/cvs
+rcs gnu/rcs
+diff gnu/diff
+tc yoyodyne/tc
address@hidden example
+
+The @file{modules} file is line oriented. In its
+simplest form each line contains the name of the
+module, whitespace, and the directory where the module
+resides. The directory is a path relative to
address@hidden The last four lines in the example
+above are examples of such lines.
+
address@hidden FIXME: might want to introduce the concept of options in modules
file
address@hidden (the old example which was here, -i mkmodules, is obsolete).
+
+The line that defines the module called @samp{modules}
+uses features that are not explained here.
address@hidden, for a full explanation of all the
+available features.
+
address@hidden FIXME: subsection without node is bogus
address@hidden Editing administrative files
address@hidden Editing administrative files
address@hidden Administrative files, editing them
+
+You edit the administrative files in the same way that you would edit
+any other module. Use @samp{cvs checkout CVSROOT} to get a working
+copy, edit it, and commit your changes in the normal way.
+
+It is possible to commit an erroneous administrative
+file. You can often fix the error and check in a new
+revision, but sometimes a particularly bad error in the
+administrative file makes it impossible to commit new
+revisions.
address@hidden @xref{Bad administrative files} for a hint
address@hidden about how to solve such situations.
address@hidden -- administrative file checking--
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Multiple repositories
address@hidden Multiple repositories
address@hidden Multiple repositories
address@hidden Repositories, multiple
address@hidden Many repositories
address@hidden Parallel repositories
address@hidden Disjoint repositories
address@hidden CVSROOT, multiple repositories
+
+In some situations it is a good idea to have more than
+one repository, for instance if you have two
+development groups that work on separate projects
+without sharing any code. All you have to do to have
+several repositories is to specify the appropriate
+repository, using the @code{CVSROOT} environment
+variable, the @samp{-d} option to @sc{cvs}, or (once
+you have checked out a working directory) by simply
+allowing @sc{cvs} to use the repository that was used
+to check out the working directory
+(@pxref{Specifying a repository}).
+
+The big advantage of having multiple repositories is
+that they can reside on different servers. With @sc{cvs}
+version 1.10, a single command cannot recurse into
+directories from different repositories. With development
+versions of @sc{cvs}, you can check out code from multiple
+servers into your working directory. @sc{cvs} will
+recurse and handle all the details of making
+connections to as many server machines as necessary to
+perform the requested command. Here is an example of
+how to set up a working directory:
+
address@hidden
+cvs -d server1:/cvs co dir1
+cd dir1
+cvs -d server2:/root co sdir
+cvs update
address@hidden example
+
+The @code{cvs co} commands set up the working
+directory, and then the @code{cvs update} command will
+contact server2, to update the dir1/sdir subdirectory,
+and server1, to update everything else.
+
address@hidden FIXME: Does the FAQ have more about this? I have a
address@hidden dim recollection, but I'm too lazy to check right now.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Creating a repository
address@hidden Creating a repository
+
address@hidden Repository, setting up
address@hidden Creating a repository
address@hidden Setting up a repository
+
+To set up a @sc{cvs} repository, first choose the
+machine and disk on which you want to store the
+revision history of the source files. CPU and memory
+requirements are modest, so most machines should be
+adequate. For details see @ref{Server requirements}.
address@hidden Possible that we should be providing a quick rule of
address@hidden thumb, like the 32M memory for the server. That
address@hidden might increase the number of people who are happy
address@hidden with the answer, without following the xref.
+
+To estimate disk space
+requirements, if you are importing RCS files from
+another system, the size of those files is the
+approximate initial size of your repository, or if you
+are starting without any version history, a rule of
+thumb is to allow for the server approximately three
+times the size of the code to be under @sc{cvs} for the
+repository (you will eventually outgrow this, but not
+for a while). On the machines on which the developers
+will be working, you'll want disk space for
+approximately one working directory for each developer
+(either the entire tree or a portion of it, depending
+on what each developer uses).
+
+The repository should be accessible
+(directly or via a networked file system) from all
+machines which want to use @sc{cvs} in server or local
+mode; the client machines need not have any access to
+it other than via the @sc{cvs} protocol. It is not
+possible to use @sc{cvs} to read from a repository
+which one only has read access to; @sc{cvs} needs to be
+able to create lock files (@pxref{Concurrency}).
+
address@hidden init (subcommand)
+To create a repository, run the @code{cvs init}
+command. It will set up an empty repository in the
address@hidden root specified in the usual way
+(@pxref{Repository}). For example,
+
address@hidden
+cvs -d /usr/local/cvsroot init
address@hidden example
+
address@hidden init} is careful to never overwrite any
+existing files in the repository, so no harm is done if
+you run @code{cvs init} on an already set-up
+repository.
+
address@hidden init} will enable history logging; if you
+don't want that, remove the history file after running
address@hidden init}. @xref{history file}.
+
address@hidden Backing up
address@hidden Backing up a repository
address@hidden Repository, backing up
address@hidden Backing up, repository
+
+There is nothing particularly magical about the files
+in the repository; for the most part it is possible to
+back them up just like any other files. However, there
+are a few issues to consider.
+
address@hidden Locks, cvs, and backups
address@hidden #cvs.rfl, and backups
+The first is that to be paranoid, one should either not
+use @sc{cvs} during the backup, or have the backup
+program lock @sc{cvs} while doing the backup. To not
+use @sc{cvs}, you might forbid logins to machines which
+can access the repository, turn off your @sc{cvs}
+server, or similar mechanisms. The details would
+depend on your operating system and how you have
address@hidden set up. To lock @sc{cvs}, you would create
address@hidden locks in each repository directory.
+See @ref{Concurrency}, for more on @sc{cvs} locks.
+Having said all this, if you just back up without any
+of these precautions, the results are unlikely to be
+particularly dire. Restoring from backup, the
+repository might be in an inconsistent state, but this
+would not be particularly hard to fix manually.
+
+When you restore a repository from backup, assuming
+that changes in the repository were made after the time
+of the backup, working directories which were not
+affected by the failure may refer to revisions which no
+longer exist in the repository. Trying to run @sc{cvs}
+in such directories will typically produce an error
+message. One way to get those changes back into the
+repository is as follows:
+
address@hidden @bullet
address@hidden
+Get a new working directory.
+
address@hidden
+Copy the files from the working directory from before
+the failure over to the new working directory (do not
+copy the contents of the @file{CVS} directories, of
+course).
+
address@hidden
+Working in the new working directory, use commands such
+as @code{cvs update} and @code{cvs diff} to figure out
+what has changed, and then when you are ready, commit
+the changes into the repository.
address@hidden itemize
+
address@hidden Moving a repository
address@hidden Moving a repository
address@hidden Repository, moving
address@hidden Moving a repository
address@hidden Copying a repository
+
+Just as backing up the files in the repository is
+pretty much like backing up any other files, if you
+need to move a repository from one place to another it
+is also pretty much like just moving any other
+collection of files.
+
+The main thing to consider is that working directories
+point to the repository. The simplest way to deal with
+a moved repository is to just get a fresh working
+directory after the move. Of course, you'll want to
+make sure that the old working directory had been
+checked in before the move, or you figured out some
+other way to make sure that you don't lose any
+changes. If you really do want to reuse the existing
+working directory, it should be possible with manual
+surgery on the @file{CVS/Repository} files. You can
+see @ref{Working directory storage}, for information on
+the @file{CVS/Repository} and @file{CVS/Root} files, but
+unless you are sure you want to bother, it probably
+isn't worth it.
address@hidden FIXME: Surgery on CVS/Repository should be avoided
address@hidden by making RELATIVE_REPOS the default.
address@hidden FIXME-maybe: might want some documented way to
address@hidden change the CVS/Root files in some particular tree.
address@hidden But then again, I don't know, maybe just having
address@hidden people do this in perl/shell/&c isn't so bad...
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Remote repositories
address@hidden Remote repositories
address@hidden Repositories, remote
address@hidden Remote repositories
address@hidden Client/Server Operation
address@hidden Server, CVS
address@hidden Remote repositories, port specification
address@hidden Repositories, remote, port specification
address@hidden Client/Server Operation, port specification
address@hidden pserver (client/server connection method), port specification
address@hidden kserver (client/server connection method), port specification
address@hidden gserver (client/server connection method), port specification
address@hidden port, specifying for remote repositories
+
+ Your working copy of the sources can be on a
+different machine than the repository. Using @sc{cvs}
+in this manner is known as @dfn{client/server}
+operation. You run @sc{cvs} on a machine which can
+mount your working directory, known as the
address@hidden, and tell it to communicate to a machine
+which can mount the repository, known as the
address@hidden Generally, using a remote
+repository is just like using a local one, except that
+the format of the repository name is:
+
address@hidden
+[:@var{method}:address@hidden:@var{password}]@@address@hidden:address@hidden/path/to/repository
address@hidden example
+
+Specifying a password in the repository name is not recommended during
+checkout, since this will cause @sc{cvs} to store a cleartext copy of the
+password in each created directory. @code{cvs login} first instead
+(@pxref{Password authentication client}).
+
+The details of exactly what needs to be set up depend
+on how you are connecting to the server.
+
+If @var{method} is not specified, and the repository
+name contains @samp{:}, then the default is @code{ext}
+or @code{server}, depending on your platform; both are
+described in @ref{Connecting via rsh}.
address@hidden Should we try to explain which platforms are which?
address@hidden Platforms like unix and VMS, which only allow
address@hidden privileged programs to bind to sockets <1024 lose on
address@hidden :server:
address@hidden Platforms like Mac and VMS, whose rsh program is
address@hidden unusable or nonexistent, lose on :ext:
address@hidden Platforms like OS/2 and NT probably could plausibly
address@hidden default either way (modulo -b troubles).
+
address@hidden FIXME: We need to have a better way of explaining
address@hidden what method to use. This presentation totally
address@hidden obscures the fact that :ext: and CVS_RSH is the way to
address@hidden use SSH, for example. Plus it incorrectly implies
address@hidden that you need an @code{rsh} binary on the client to use
address@hidden :server:.
address@hidden Also note that rsh not pserver is the right choice if you want
address@hidden users to be able to create their own repositories
address@hidden (because of the --allow-root related issues).
address@hidden
+* Server requirements:: Memory and other resources for servers
+* Connecting via rsh:: Using the @code{rsh} program to connect
+* Password authenticated:: Direct connections using passwords
+* GSSAPI authenticated:: Direct connections using GSSAPI
+* Kerberos authenticated:: Direct connections with kerberos
+* Connecting via fork:: Using a forked @code{cvs server} to connect
address@hidden menu
+
address@hidden Server requirements
address@hidden Server requirements
+
+The quick answer to what sort of machine is suitable as
+a server is that requirements are modest---a server
+with 32M of memory or even less can handle a fairly
+large source tree with a fair amount of activity.
address@hidden Say something about CPU speed too? I'm even less sure
address@hidden what to say on that subject...
+
+The real answer, of course, is more complicated.
+Estimating the known areas of large memory consumption
+should be sufficient to estimate memory requirements.
+There are two such areas documented here; other memory
+consumption should be small by comparison (if you find
+that is not the case, let us know, as described in
address@hidden, so we can update this documentation).
+
+The first area of big memory consumption is large
+checkouts, when using the @sc{cvs} server. The server
+consists of two processes for each client that it is
+serving. Memory consumption on the child process
+should remain fairly small. Memory consumption on the
+parent process, particularly if the network connection
+to the client is slow, can be expected to grow to
+slightly more than the size of the sources in a single
+directory, or two megabytes, whichever is larger.
address@hidden "two megabytes" of course is SERVER_HI_WATER. But
address@hidden we don't mention that here because we are
address@hidden documenting the default configuration of CVS. If it
address@hidden is a "standard" thing to change that value, it
address@hidden should be some kind of run-time configuration.
address@hidden
address@hidden See cvsclient.texi for more on the design decision
address@hidden to not have locks in place while waiting for the
address@hidden client, which is what results in memory consumption
address@hidden as high as this.
+
+Multiplying the size of each @sc{cvs} server by the
+number of servers which you expect to have active at
+one time should give an idea of memory requirements for
+the server. For the most part, the memory consumed by
+the parent process probably can be swap space rather
+than physical memory.
address@hidden Has anyone verified that notion about swap space?
address@hidden I say it based pretty much on guessing that the
address@hidden ->text of the struct buffer_data only gets accessed
address@hidden in a first in, first out fashion, but I haven't
address@hidden looked very closely.
+
address@hidden What about disk usage in /tmp on the server? I think that
address@hidden it can be substantial, but I haven't looked at this
address@hidden again and tried to figure it out ("cvs import" is
address@hidden probably the worst case...).
+
+The second area of large memory consumption is
address@hidden, when checking in large files. This is
+required even for binary files. The rule of thumb is
+to allow about ten times the size of the largest file
+you will want to check in, although five times may be
+adequate. For example, if you want to check in a file
+which is 10 megabytes, you should have 100 megabytes of
+memory on the machine doing the checkin (the server
+machine for client/server, or the machine running
address@hidden for non-client/server). This can be swap
+space rather than physical memory. Because the memory
+is only required briefly, there is no particular need
+to allow memory for more than one such checkin at a
+time.
address@hidden The 5-10 times rule of thumb is from Paul Eggert for
address@hidden GNU diff. I don't think it is in the GNU diff
address@hidden manual or anyplace like that.
address@hidden
address@hidden Probably we could be saying more about
address@hidden non-client/server CVS.
address@hidden I would guess for non-client/server CVS in an NFS
address@hidden environment the biggest issues are the network and
address@hidden the NFS server.
+
+Resource consumption for the client is even more
+modest---any machine with enough capacity to run the
+operating system in question should have little
+trouble.
address@hidden Is that true? I think the client still wants to
address@hidden (bogusly) store entire files in memory at times.
+
+For information on disk space requirements, see
address@hidden a repository}.
+
address@hidden Connecting via rsh
address@hidden Connecting with rsh
+
address@hidden rsh
address@hidden uses the @samp{rsh} protocol to perform these
+operations, so the remote user host needs to have a
address@hidden file which grants access to the local
+user. Note that the program that @sc{cvs} uses for this
+purpose may be specified using the @file{--with-rsh}
+flag to configure.
+
+For example, suppose you are the user @samp{mozart} on
+the local machine @samp{toe.example.com}, and the
+server machine is @samp{faun.example.org}. On
+faun, put the following line into the file
address@hidden in @samp{bach}'s home directory:
+
address@hidden
+toe.example.com mozart
address@hidden example
+
address@hidden
+Then test that @samp{rsh} is working with
+
address@hidden
+rsh -l bach faun.example.org 'echo $PATH'
address@hidden example
+
address@hidden CVS_SERVER, environment variable
+Next you have to make sure that @code{rsh} will be able
+to find the server. Make sure that the path which
address@hidden printed in the above example includes the
+directory containing a program named @code{cvs} which
+is the server. You need to set the path in
address@hidden, @file{.cshrc}, etc., not @file{.login}
+or @file{.profile}. Alternately, you can set the
+environment variable @code{CVS_SERVER} on the client
+machine to the filename of the server you want to use,
+for example @file{/usr/local/bin/cvs-1.6}.
address@hidden FIXME: there should be a way to specify the
address@hidden program in CVSROOT, not CVS_SERVER, so that one can use
address@hidden different ones for different roots. e.g. ":server;cvs=cvs-1.6:"
address@hidden instead of ":server:".
+
+There is no need to edit @file{inetd.conf} or start a
address@hidden server daemon.
+
address@hidden :server:, setting up
address@hidden :ext:, setting up
address@hidden Kerberos, using kerberized rsh
address@hidden SSH (rsh replacement)
address@hidden rsh replacements (Kerberized, SSH, &c)
+There are two access methods that you use in @code{CVSROOT}
+for rsh. @code{:server:} specifies an internal rsh
+client, which is supported only by some @sc{cvs} ports.
address@hidden:ext:} specifies an external rsh program. By
+default this is @code{rsh} (unless otherwise specified
+by the @file{--with-rsh} flag to configure) but you may set the
address@hidden environment variable to invoke another
+program which can access the remote server (for
+example, @code{remsh} on HP-UX 9 because @code{rsh} is
+something different). It must be a program which can
+transmit data to and from the server without modifying
+it; for example the Windows NT @code{rsh} is not
+suitable since it by default translates between CRLF
+and LF. The OS/2 @sc{cvs} port has a hack to pass @samp{-b}
+to @code{rsh} to get around this, but since this could
+potentially cause problems for programs other than the
+standard @code{rsh}, it may change in the future. If
+you set @code{CVS_RSH} to @code{SSH} or some other rsh
+replacement, the instructions in the rest of this
+section concerning @file{.rhosts} and so on are likely
+to be inapplicable; consult the documentation for your rsh
+replacement.
address@hidden FIXME: there should be a way to specify the
address@hidden program in CVSROOT, not CVS_RSH, so that one can use
address@hidden different ones for different roots. e.g. ":ext;rsh=remsh:"
address@hidden instead of ":ext:".
address@hidden See also the comment in src/client.c for rationale
address@hidden concerning "rsh" being the default and never
address@hidden "remsh".
+
+Continuing our example, supposing you want to access
+the module @file{foo} in the repository
address@hidden/usr/local/cvsroot/}, on machine
address@hidden, you are ready to go:
+
address@hidden
+cvs -d :ext:bach@@faun.example.org:/usr/local/cvsroot checkout foo
address@hidden example
+
address@hidden
+(The @file{bach@@} can be omitted if the username is
+the same on both the local and remote hosts.)
+
address@hidden Should we mention "rsh host echo hi" and "rsh host
address@hidden cat" (the latter followed by typing text and ^D)
address@hidden as troubleshooting techniques? Probably yes
address@hidden (people tend to have trouble setting this up),
address@hidden but this kind of thing can be hard to spell out.
+
address@hidden Password authenticated
address@hidden Direct connection with password authentication
+
+The @sc{cvs} client can also connect to the server
+using a password protocol. This is particularly useful
+if using @code{rsh} is not feasible (for example,
+the server is behind a firewall), and Kerberos also is
+not available.
+
+ To use this method, it is necessary to make
+some adjustments on both the server and client sides.
+
address@hidden
+* Password authentication server:: Setting up the server
+* Password authentication client:: Using the client
+* Password authentication security:: What this method does and does not do
address@hidden menu
+
address@hidden Password authentication server
address@hidden Setting up the server for password authentication
+
+First of all, you probably want to tighten the
+permissions on the @file{$CVSROOT} and
address@hidden/CVSROOT} directories. See @ref{Password
+authentication security}, for more details.
+
address@hidden pserver (subcommand)
address@hidden Remote repositories, port specification
address@hidden Repositories, remote, port specification
address@hidden Client/Server Operation, port specification
address@hidden pserver (client/server connection method), port specification
address@hidden kserver (client/server connection method), port specification
address@hidden gserver (client/server connection method), port specification
address@hidden port, specifying for remote repositories
address@hidden Password server, setting up
address@hidden Authenticating server, setting up
address@hidden inetd, configuring for pserver
address@hidden xinetd, configuring for pserver
address@hidden FIXME: this isn't quite right regarding port
address@hidden numbers; CVS looks up "cvspserver" in
address@hidden /etc/services (on unix, but what about non-unix?).
+On the server side, the file @file{/etc/inetd.conf}
+needs to be edited so @code{inetd} knows to run the
+command @code{cvs pserver} when it receives a
+connection on the right port. By default, the port
+number is 2401; it would be different if your client
+were compiled with @code{CVS_AUTH_PORT} defined to
+something else, though. This can also be specified in the CVSROOT variable
+(@pxref{Remote repositories}) or overridden with the CVS_CLIENT_PORT
+environment variable (@pxref{Environment variables}).
+
+ If your @code{inetd} allows raw port numbers in
address@hidden/etc/inetd.conf}, then the following (all on a
+single line in @file{inetd.conf}) should be sufficient:
+
address@hidden
+2401 stream tcp nowait root /usr/local/bin/cvs
+cvs -f --allow-root=/usr/cvsroot pserver
address@hidden example
+
address@hidden
+(You could also use the
address@hidden option to specify a temporary directory.)
+
+The @samp{--allow-root} option specifies the allowable
address@hidden directory. Clients which attempt to use a
+different @sc{cvsroot} directory will not be allowed to
+connect. If there is more than one @sc{cvsroot}
+directory which you want to allow, repeat the option.
+(Unfortunately, many versions of @code{inetd} have very small
+limits on the number of arguments and/or the total length
+of the command. The usual solution to this problem is
+to have @code{inetd} run a shell script which then invokes
address@hidden with the necessary arguments.)
+
+ If your @code{inetd} wants a symbolic service
+name instead of a raw port number, then put this in
address@hidden/etc/services}:
+
address@hidden
+cvspserver 2401/tcp
address@hidden example
+
address@hidden
+and put @code{cvspserver} instead of @code{2401} in @file{inetd.conf}.
+
+If your system uses @code{xinetd} instead of @code{inetd},
+the procedure is slightly different.
+Create a file called @file{/etc/xinetd.d/cvspserver} containing the following:
+
address@hidden
+service cvspserver
address@hidden
+ port = 2401
+ socket_type = stream
+ protocol = tcp
+ wait = no
+ user = root
+ passenv = PATH
+ server = /usr/local/bin/cvs
+ server_args = -f --allow-root=/usr/cvsroot pserver
address@hidden
address@hidden example
+
address@hidden
+(If @code{cvspserver} is defined in @file{/etc/services}, you can omit
+the @code{port} line.)
+
+ Once the above is taken care of, restart your
address@hidden, or do whatever is necessary to force it
+to reread its initialization files.
+
+If you are having trouble setting this up, see
address@hidden
+
address@hidden CVS passwd file
address@hidden passwd (admin file)
+Because the client stores and transmits passwords in
+cleartext (almost---see @ref{Password authentication
+security}, for details), a separate @sc{cvs} password
+file is generally used, so people don't compromise
+their regular passwords when they access the
+repository. This file is
address@hidden/CVSROOT/passwd} (@pxref{Intro
+administrative files}). It uses a colon-separated
+format, similar to @file{/etc/passwd} on Unix systems,
+except that it has fewer fields: @sc{cvs} username,
+optional password, and an optional system username for
address@hidden to run as if authentication succeeds. Here is
+an example @file{passwd} file with five entries:
+
address@hidden
+anonymous:
+bach:ULtgRLXo7NRxs
+spwang:1sOp854gDF3DY
+melissa:tGX1fS8sun6rY:pubcvs
+qproj:XR4EZcEs0szik:pubcvs
address@hidden example
+
address@hidden
+(The passwords are encrypted according to the standard
+Unix @code{crypt()} function, so it is possible to
+paste in passwords directly from regular Unix
address@hidden/etc/passwd} files.)
+
+The first line in the example will grant access to any
address@hidden client attempting to authenticate as user
address@hidden, no matter what password they use,
+including an empty password. (This is typical for
+sites granting anonymous read-only access; for
+information on how to do the "read-only" part, see
address@hidden access}.)
+
+The second and third lines will grant access to
address@hidden and @code{spwang} if they supply their
+respective plaintext passwords.
+
address@hidden User aliases
+The fourth line will grant access to @code{melissa}, if
+she supplies the correct password, but her @sc{cvs}
+operations will actually run on the server side under
+the system user @code{pubcvs}. Thus, there need not be
+any system user named @code{melissa}, but there
address@hidden be one named @code{pubcvs}.
+
+The fifth line shows that system user identities can be
+shared: any client who successfully authenticates as
address@hidden will actually run as @code{pubcvs}, just
+as @code{melissa} does. That way you could create a
+single, shared system user for each project in your
+repository, and give each developer their own line in
+the @file{$CVSROOT/CVSROOT/passwd} file. The @sc{cvs}
+username on each line would be different, but the
+system username would be the same. The reason to have
+different @sc{cvs} usernames is that @sc{cvs} will log their
+actions under those names: when @code{melissa} commits
+a change to a project, the checkin is recorded in the
+project's history under the name @code{melissa}, not
address@hidden And the reason to have them share a
+system username is so that you can arrange permissions
+in the relevant area of the repository such that only
+that account has write-permission there.
+
+If the system-user field is present, all
+password-authenticated @sc{cvs} commands run as that
+user; if no system user is specified, @sc{cvs} simply
+takes the @sc{cvs} username as the system username and
+runs commands as that user. In either case, if there
+is no such user on the system, then the @sc{cvs}
+operation will fail (regardless of whether the client
+supplied a valid password).
+
+The password and system-user fields can both be omitted
+(and if the system-user field is omitted, then also
+omit the colon that would have separated it from the
+encrypted password). For example, this would be a
+valid @file{$CVSROOT/CVSROOT/passwd} file:
+
address@hidden
+anonymous::pubcvs
+fish:rKa5jzULzmhOo:kfogel
+sussman:1sOp854gDF3DY
address@hidden example
+
address@hidden
+When the password field is omitted or empty, then the
+client's authentication attempt will succeed with any
+password, including the empty string. However, the
+colon after the @sc{cvs} username is always necessary,
+even if the password is empty.
+
address@hidden can also fall back to use system authentication.
+When authenticating a password, the server first checks
+for the user in the @file{$CVSROOT/CVSROOT/passwd}
+file. If it finds the user, it will use that entry for
+authentication as described above. But if it does not
+find the user, or if the @sc{cvs} @file{passwd} file
+does not exist, then the server can try to authenticate
+the username and password using the operating system's
+user-lookup routines (this "fallback" behavior can be
+disabled by setting @code{SystemAuth=no} in the
address@hidden @file{config} file, @pxref{config}).
+
+The default fallback behaviour is to look in
address@hidden/etc/passwd} for this system password unless your
+system has PAM (Pluggable Authentication Modules)
+and your @sc{cvs} server executable was configured to
+use it at compile time (using @code{./configure --enable-pam} - see the
+INSTALL file for more). In this case, PAM will be consulted instead.
+This means that @sc{cvs} can be configured to use any password
+authentication source PAM can be configured to use (possibilities
+include a simple UNIX password, NIS, LDAP, and others) in its
+global configuration file (usually @file{/etc/pam.conf}
+or possibly @file{/etc/pam.d/cvs}). See your PAM documentation
+for more details on PAM configuration.
+
+Note that PAM is an experimental feature in @sc{cvs} and feedback is
+encouraged. Please send a mail to one of the @sc{cvs} mailing lists
+(@code{info-cvs@@gnu.org} or @code{bug-cvs@@gnu.org}) if you use the
address@hidden PAM support.
+
address@hidden: Using PAM gives the system administrator much more
+flexibility about how @sc{cvs} users are authenticated but
+no more security than other methods. See below for more.}
+
+CVS needs an "auth" and "account" module in the
+PAM configuration file. A typical PAM configuration
+would therefore have the following lines
+in @file{/etc/pam.conf} to emulate the standard @sc{cvs}
+system @file{/etc/passwd} authentication:
+
address@hidden
+cvs auth required pam_unix.so
+cvs account required pam_unix.so
address@hidden example
+
+The the equivalent @file{/etc/pam.d/cvs} would contain
+
address@hidden
+auth required pam_unix.so
+account required pam_unix.so
address@hidden example
+
+Some systems require a full path to the module so that
address@hidden (Linux) would become something like
address@hidden/usr/lib/security/$ISA/pam_unix.so.1} (Sun Solaris).
+See the @file{contrib/pam} subdirectory of the @sc{cvs}
+source distribution for further example configurations.
+
+The PAM service name given above as "cvs" is just
+the service name in the default configuration amd can be
+set using
address@hidden/configure --with-hardcoded-pam-service-name=<pam-service-name>}
+before compiling. @sc{cvs} can also be configured to use whatever
+name it is invoked as as its PAM service name using
address@hidden/configure --without-hardcoded-pam-service-name}, but this
+feature should not be used if you may not have control of the name
address@hidden will be invoked as.
+
+Be aware, also, that falling back to system
+authentication might be a security risk: @sc{cvs}
+operations would then be authenticated with that user's
+regular login password, and the password flies across
+the network in plaintext. See @ref{Password
+authentication security} for more on this.
+This may be more of a problem with PAM authentication
+because it is likely that the source of the system
+password is some central authentication service like
+LDAP which is also used to authenticate other services.
+
+On the other hand, PAM makes it very easy to change your password
+regularly. If they are given the option of a one-password system for
+all of their activities, users are often more willing to change their
+password on a regular basis.
+
+In the non-PAM configuration where the password is stored in the
address@hidden/passwd} file, it is difficult to change passwords on a
+regular basis since only administrative users (or in some cases
+processes that act as an administrative user) are typicaly given
+access to modify this file. Either there needs to be some
+hand-crafted web page or set-uid program to update the file, or the
+update needs to be done by submitting a request to an administrator to
+perform the duty by hand. In the first case, having to remember to
+update a separate password on a periodic basis can be difficult. In
+the second case, the manual nature of the change will typically mean
+that the password will not be changed unless it is absolutely
+necessary.
+
+Note that PAM administrators should probably avoid configuring
+one-time-passwords (OTP) for @sc{cvs} authentication/authorization. If
+OTPs are desired, the administrator may wish to encourage the use of
+one of the other Client/Server access methods. See the section on
address@hidden repositories} for a list of other methods.
+
+Right now, the only way to put a password in the
address@hidden @file{passwd} file is to paste it there from
+somewhere else. Someday, there may be a @code{cvs
+passwd} command.
+
+Unlike many of the files in @file{$CVSROOT/CVSROOT}, it
+is normal to edit the @file{passwd} file in-place,
+rather than via @sc{cvs}. This is because of the
+possible security risks of having the @file{passwd}
+file checked out to people's working copies. If you do
+want to include the @file{passwd} file in checkouts of
address@hidden/CVSROOT}, see @ref{checkoutlist}.
+
address@hidden We might also suggest using the @code{htpasswd} command
address@hidden from freely available web servers as well, but that
address@hidden would open up a can of worms in that the users next
address@hidden questions are likely to be "where do I get it?" and
address@hidden "how do I use it?"
address@hidden Also note that htpasswd, at least the version I had,
address@hidden likes to clobber the third field.
+
address@hidden Password authentication client
address@hidden Using the client with password authentication
address@hidden Login (subcommand)
address@hidden Password client, using
address@hidden Authenticated client, using
address@hidden :pserver:, setting up
+To run a @sc{cvs} command on a remote repository via
+the password-authenticating server, one specifies the
address@hidden protocol, optional username, repository host, an
+optional port number, and path to the repository. For example:
+
address@hidden
+cvs -d :pserver:faun.example.org:/usr/local/cvsroot checkout someproj
address@hidden example
+
address@hidden
+or
+
address@hidden
+CVSROOT=:pserver:bach@@faun.example.org:2401/usr/local/cvsroot
+cvs checkout someproj
address@hidden example
+
+However, unless you're connecting to a public-access
+repository (i.e., one where that username doesn't
+require a password), you'll need to supply a password or @dfn{log in} first.
+Logging in verifies your password with the repository and stores it in a file.
+It's done with the @code{login} command, which will
+prompt you interactively for the password if you didn't supply one as part of
address@hidden:
+
address@hidden
+cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot login
+CVS password:
address@hidden example
+
address@hidden
+or
+
address@hidden
+cvs -d :pserver:bach:p4ss30rd@@faun.example.org:/usr/local/cvsroot login
address@hidden example
+
+After you enter the password, @sc{cvs} verifies it with
+the server. If the verification succeeds, then that
+combination of username, host, repository, and password
+is permanently recorded, so future transactions with
+that repository won't require you to run @code{cvs
+login}. (If verification fails, @sc{cvs} will exit
+complaining that the password was incorrect, and
+nothing will be recorded.)
+
+The records are stored, by default, in the file
address@hidden/.cvspass}. That file's format is
+human-readable, and to a degree human-editable, but
+note that the passwords are not stored in
+cleartext---they are trivially encoded to protect them
+from "innocent" compromise (i.e., inadvertent viewing
+by a system administrator or other non-malicious
+person).
+
address@hidden CVS_PASSFILE, environment variable
+You can change the default location of this file by
+setting the @code{CVS_PASSFILE} environment variable.
+If you use this variable, make sure you set it
address@hidden @code{cvs login} is run. If you were to
+set it after running @code{cvs login}, then later
address@hidden commands would be unable to look up the
+password for transmission to the server.
+
+Once you have logged in, all @sc{cvs} commands using
+that remote repository and username will authenticate
+with the stored password. So, for example
+
address@hidden
+cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot checkout foo
address@hidden example
+
address@hidden
+should just work (unless the password changes on the
+server side, in which case you'll have to re-run
address@hidden login}).
+
+Note that if the @samp{:pserver:} were not present in
+the repository specification, @sc{cvs} would assume it
+should use @code{rsh} to connect with the server
+instead (@pxref{Connecting via rsh}).
+
+Of course, once you have a working copy checked out and
+are running @sc{cvs} commands from within it, there is
+no longer any need to specify the repository
+explicitly, because @sc{cvs} can deduce the repository
+from the working copy's @file{CVS} subdirectory.
+
address@hidden FIXME: seems to me this needs somewhat more
address@hidden explanation.
address@hidden Logout (subcommand)
+The password for a given remote repository can be
+removed from the @code{CVS_PASSFILE} by using the
address@hidden logout} command.
+
address@hidden Password authentication security
address@hidden Security considerations with password authentication
+
address@hidden Security, of pserver
+The passwords are stored on the client side in a
+trivial encoding of the cleartext, and transmitted in
+the same encoding. The encoding is done only to
+prevent inadvertent password compromises (i.e., a
+system administrator accidentally looking at the file),
+and will not prevent even a naive attacker from gaining
+the password.
+
address@hidden FIXME: The bit about "access to the repository
address@hidden implies general access to the system is *not* specific
address@hidden to pserver; it applies to kerberos and SSH and
address@hidden everything else too. Should reorganize the
address@hidden documentation to make this clear.
+The separate @sc{cvs} password file (@pxref{Password
+authentication server}) allows people
+to use a different password for repository access than
+for login access. On the other hand, once a user has
+non-read-only
+access to the repository, she can execute programs on
+the server system through a variety of means. Thus, repository
+access implies fairly broad system access as well. It
+might be possible to modify @sc{cvs} to prevent that,
+but no one has done so as of this writing.
address@hidden OpenBSD uses chroot() and copies the repository to
address@hidden provide anonymous read-only access (for details see
address@hidden http://www.openbsd.org/anoncvs.shar). While this
address@hidden closes the most obvious holes, I'm not sure it
address@hidden closes enough holes to recommend it (plus it is
address@hidden *very* easy to accidentally screw up a setup of this
address@hidden type).
+
+Note that because the @file{$CVSROOT/CVSROOT} directory
+contains @file{passwd} and other files which are used
+to check security, you must control the permissions on
+this directory as tightly as the permissions on
address@hidden/etc}. The same applies to the @file{$CVSROOT}
+directory itself and any directory
+above it in the tree. Anyone who has write access to
+such a directory will have the ability to become any
+user on the system. Note that these permissions are
+typically tighter than you would use if you are not
+using pserver.
address@hidden TODO: Would be really nice to document/implement a
address@hidden scheme where the CVS server can run as some non-root
address@hidden user, e.g. "cvs". CVSROOT/passwd would contain a
address@hidden bunch of entries of the form foo:xxx:cvs (or the "cvs"
address@hidden would be implicit). This would greatly reduce
address@hidden security risks such as those hinted at in the
address@hidden previous paragraph. I think minor changes to CVS
address@hidden might be required but mostly this would just need
address@hidden someone who wants to play with it, document it, &c.
+
+In summary, anyone who gets the password gets
+repository access (which may imply some measure of general system
+access as well). The password is available to anyone
+who can sniff network packets or read a protected
+(i.e., user read-only) file. If you want real
+security, get Kerberos.
+
address@hidden GSSAPI authenticated
address@hidden Direct connection with GSSAPI
+
address@hidden GSSAPI
address@hidden Security, GSSAPI
address@hidden :gserver:, setting up
address@hidden Kerberos, using :gserver:
+GSSAPI is a generic interface to network security
+systems such as Kerberos 5.
+If you have a working GSSAPI library, you can have
address@hidden connect via a direct @sc{tcp} connection,
+authenticating with GSSAPI.
+
+To do this, @sc{cvs} needs to be compiled with GSSAPI
+support; when configuring @sc{cvs} it tries to detect
+whether GSSAPI libraries using kerberos version 5 are
+present. You can also use the @file{--with-gssapi}
+flag to configure.
+
+The connection is authenticated using GSSAPI, but the
+message stream is @emph{not} authenticated by default.
+You must use the @code{-a} global option to request
+stream authentication.
+
+The data transmitted is @emph{not} encrypted by
+default. Encryption support must be compiled into both
+the client and the server; use the
address@hidden configure option to turn it on.
+You must then use the @code{-x} global option to
+request encryption.
+
+GSSAPI connections are handled on the server side by
+the same server which handles the password
+authentication server; see @ref{Password authentication
+server}. If you are using a GSSAPI mechanism such as
+Kerberos which provides for strong authentication, you
+will probably want to disable the ability to
+authenticate via cleartext passwords. To do so, create
+an empty @file{CVSROOT/passwd} password file, and set
address@hidden in the config file
+(@pxref{config}).
+
+The GSSAPI server uses a principal name of
+cvs/@var{hostname}, where @var{hostname} is the
+canonical name of the server host. You will have to
+set this up as required by your GSSAPI mechanism.
+
+To connect using GSSAPI, use @samp{:gserver:}. For
+example,
+
address@hidden
+cvs -d :gserver:faun.example.org:/usr/local/cvsroot checkout foo
address@hidden example
+
address@hidden Kerberos authenticated
address@hidden Direct connection with kerberos
+
address@hidden Kerberos, using :kserver:
address@hidden Security, kerberos
address@hidden :kserver:, setting up
+The easiest way to use kerberos is to use the kerberos
address@hidden, as described in @ref{Connecting via rsh}.
+The main disadvantage of using rsh is that all the data
+needs to pass through additional programs, so it may be
+slower. So if you have kerberos installed you can
+connect via a direct @sc{tcp} connection,
+authenticating with kerberos.
+
+This section concerns the kerberos network security
+system, version 4. Kerberos version 5 is supported via
+the GSSAPI generic network security interface, as
+described in the previous section.
+
+To do this, @sc{cvs} needs to be compiled with kerberos
+support; when configuring @sc{cvs} it tries to detect
+whether kerberos is present or you can use the
address@hidden flag to configure.
+
+The data transmitted is @emph{not} encrypted by
+default. Encryption support must be compiled into both
+the client and server; use the
address@hidden configure option to turn it
+on. You must then use the @code{-x} global option to
+request encryption.
+
address@hidden CVS_CLIENT_PORT
+You need to edit @file{inetd.conf} on the server
+machine to run @code{cvs kserver}. The client uses
+port 1999 by default; if you want to use another port
+specify it in the @code{CVSROOT} (@pxref{Remote repositories})
+or the @code{CVS_CLIENT_PORT} environment variable
+(@pxref{Environment variables}) on the client.
+
address@hidden kinit
+When you want to use @sc{cvs}, get a ticket in the
+usual way (generally @code{kinit}); it must be a ticket
+which allows you to log into the server machine. Then
+you are ready to go:
+
address@hidden
+cvs -d :kserver:faun.example.org:/usr/local/cvsroot checkout foo
address@hidden example
+
+Previous versions of @sc{cvs} would fall back to a
+connection via rsh; this version will not do so.
+
address@hidden Connecting via fork
address@hidden Connecting with fork
+
address@hidden fork, access method
address@hidden :fork:, setting up
+This access method allows you to connect to a
+repository on your local disk via the remote protocol.
+In other words it does pretty much the same thing as
address@hidden:local:}, but various quirks, bugs and the like are
+those of the remote @sc{cvs} rather than the local
address@hidden
+
+For day-to-day operations you might prefer either
address@hidden:local:} or @code{:fork:}, depending on your
+preferences. Of course @code{:fork:} comes in
+particularly handy in testing or
+debugging @code{cvs} and the remote protocol.
+Specifically, we avoid all of the network-related
+setup/configuration, timeouts, and authentication
+inherent in the other remote access methods but still
+create a connection which uses the remote protocol.
+
+To connect using the @code{fork} method, use
address@hidden:fork:} and the pathname to your local
+repository. For example:
+
address@hidden
+cvs -d :fork:/usr/local/cvsroot checkout foo
address@hidden example
+
address@hidden CVS_SERVER, and :fork:
+As with @code{:ext:}, the server is called @samp{cvs}
+by default, or the value of the @code{CVS_SERVER}
+environment variable.
+
address@hidden
---------------------------------------------------------------------
address@hidden Read-only access
address@hidden Read-only repository access
address@hidden Read-only repository access
address@hidden readers (admin file)
address@hidden writers (admin file)
+
+ It is possible to grant read-only repository
+access to people using the password-authenticated
+server (@pxref{Password authenticated}). (The
+other access methods do not have explicit support for
+read-only users because those methods all assume login
+access to the repository machine anyway, and therefore
+the user can do whatever local file permissions allow
+her to do.)
+
+ A user who has read-only access can do only
+those @sc{cvs} operations which do not modify the
+repository, except for certain ``administrative'' files
+(such as lock files and the history file). It may be
+desirable to use this feature in conjunction with
+user-aliasing (@pxref{Password authentication server}).
+
+Unlike with previous versions of @sc{cvs}, read-only
+users should be able merely to read the repository, and
+not to execute programs on the server or otherwise gain
+unexpected levels of access. Or to be more accurate,
+the @emph{known} holes have been plugged. Because this
+feature is new and has not received a comprehensive
+security audit, you should use whatever level of
+caution seems warranted given your attitude concerning
+security.
+
+ There are two ways to specify read-only access
+for a user: by inclusion, and by exclusion.
+
+ "Inclusion" means listing that user
+specifically in the @file{$CVSROOT/CVSROOT/readers}
+file, which is simply a newline-separated list of
+users. Here is a sample @file{readers} file:
+
address@hidden
+melissa
+splotnik
+jrandom
address@hidden example
+
address@hidden
+ (Don't forget the newline after the last user.)
+
+ "Exclusion" means explicitly listing everyone
+who has @emph{write} access---if the file
+
address@hidden
+$CVSROOT/CVSROOT/writers
address@hidden example
+
address@hidden
+exists, then only
+those users listed in it have write access, and
+everyone else has read-only access (of course, even the
+read-only users still need to be listed in the
address@hidden @file{passwd} file). The
address@hidden file has the same format as the
address@hidden file.
+
+ Note: if your @sc{cvs} @file{passwd}
+file maps cvs users onto system users (@pxref{Password
+authentication server}), make sure you deny or grant
+read-only access using the @emph{cvs} usernames, not
+the system usernames. That is, the @file{readers} and
address@hidden files contain cvs usernames, which may
+or may not be the same as system usernames.
+
+ Here is a complete description of the server's
+behavior in deciding whether to grant read-only or
+read-write access:
+
+ If @file{readers} exists, and this user is
+listed in it, then she gets read-only access. Or if
address@hidden exists, and this user is NOT listed in
+it, then she also gets read-only access (this is true
+even if @file{readers} exists but she is not listed
+there). Otherwise, she gets full read-write access.
+
+ Of course there is a conflict if the user is
+listed in both files. This is resolved in the more
+conservative way, it being better to protect the
+repository too much than too little: such a user gets
+read-only access.
+
address@hidden Server temporary directory
address@hidden Temporary directories for the server
address@hidden Temporary directories, and server
address@hidden Server, temporary directories
+
+While running, the @sc{cvs} server creates temporary
+directories. They are named
+
address@hidden
address@hidden
address@hidden example
+
address@hidden
+where @var{pid} is the process identification number of
+the server.
+They are located in the directory specified by
+the @samp{-T} global option (@pxref{Global options}),
+the @code{TMPDIR} environment variable (@pxref{Environment variables}),
+or, failing that, @file{/tmp}.
+
+In most cases the server will remove the temporary
+directory when it is done, whether it finishes normally
+or abnormally. However, there are a few cases in which
+the server does not or cannot remove the temporary
+directory, for example:
+
address@hidden @bullet
address@hidden
+If the server aborts due to an internal server error,
+it may preserve the directory to aid in debugging
+
address@hidden
+If the server is killed in a way that it has no way of
+cleaning up (most notably, @samp{kill -KILL} on unix).
+
address@hidden
+If the system shuts down without an orderly shutdown,
+which tells the server to clean up.
address@hidden itemize
+
+In cases such as this, you will need to manually remove
+the @address@hidden directories. As long as
+there is no server running with process identification
+number @var{pid}, it is safe to do so.
+
address@hidden
---------------------------------------------------------------------
address@hidden Starting a new project
address@hidden Starting a project with CVS
address@hidden Starting a project with CVS
address@hidden Creating a project
+
address@hidden --moduledb--
+Because renaming files and moving them between
+directories is somewhat inconvenient, the first thing
+you do when you start a new project should be to think
+through your file organization. It is not impossible
+to rename or move files, but it does increase the
+potential for confusion and @sc{cvs} does have some
+quirks particularly in the area of renaming
+directories. @xref{Moving files}.
+
+What to do next depends on the situation at hand.
+
address@hidden
+* Setting up the files:: Getting the files into the repository
+* Defining the module:: How to make a module of the files
address@hidden menu
address@hidden -- File permissions!
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Setting up the files
address@hidden Setting up the files
+
+The first step is to create the files inside the repository. This can
+be done in a couple of different ways.
+
address@hidden -- The contributed scripts
address@hidden
+* From files:: This method is useful with old projects
+ where files already exists.
+* From other version control systems:: Old projects where you want to
+ preserve history from another system.
+* From scratch:: Creating a directory tree from scratch.
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden From files
address@hidden Creating a directory tree from a number of files
address@hidden Importing files
+
+When you begin using @sc{cvs}, you will probably already have several
+projects that can be
+put under @sc{cvs} control. In these cases the easiest way is to use the
address@hidden command. An example is probably the easiest way to
+explain how to use it. If the files you want to install in
address@hidden reside in @address@hidden, and you want them to appear in the
+repository as @file{$CVSROOT/yoyodyne/@var{rdir}}, you can do this:
+
address@hidden
+$ cd @var{wdir}
+$ cvs import -m "Imported sources" yoyodyne/@var{rdir} yoyo start
address@hidden example
+
+Unless you supply a log message with the @samp{-m}
+flag, @sc{cvs} starts an editor and prompts for a
+message. The string @samp{yoyo} is a @dfn{vendor tag},
+and @samp{start} is a @dfn{release tag}. They may fill
+no purpose in this context, but since @sc{cvs} requires
+them they must be present. @xref{Tracking sources}, for
+more information about them.
+
+You can now verify that it worked, and remove your
+original source directory.
address@hidden FIXME: Need to say more about "verify that it
address@hidden worked". What should the user look for in the output
address@hidden from "diff -r"?
+
address@hidden
+$ cd ..
+$ cvs checkout yoyodyne/@var{rdir} # @r{Explanation below}
+$ diff -r @var{wdir} yoyodyne/@var{rdir}
+$ rm -r @var{wdir}
address@hidden example
+
address@hidden
+Erasing the original sources is a good idea, to make sure that you do
+not accidentally edit them in @var{wdir}, bypassing @sc{cvs}.
+Of course, it would be wise to make sure that you have
+a backup of the sources before you remove them.
+
+The @code{checkout} command can either take a module
+name as argument (as it has done in all previous
+examples) or a path name relative to @code{$CVSROOT},
+as it did in the example above.
+
+It is a good idea to check that the permissions
address@hidden sets on the directories inside @code{$CVSROOT}
+are reasonable, and that they belong to the proper
+groups. @xref{File permissions}.
+
+If some of the files you want to import are binary, you
+may want to use the wrappers features to specify which
+files are binary and which are not. @xref{Wrappers}.
+
address@hidden The node name is too long, but I am having trouble
address@hidden thinking of something more concise.
address@hidden From other version control systems
address@hidden Creating Files From Other Version Control Systems
address@hidden Importing files, from other version control systems
+
+If you have a project which you are maintaining with
+another version control system, such as @sc{rcs}, you
+may wish to put the files from that project into
address@hidden, and preserve the revision history of the
+files.
+
address@hidden @asis
address@hidden RCS, importing files from
address@hidden From RCS
+If you have been using @sc{rcs}, find the @sc{rcs}
+files---usually a file named @file{foo.c} will have its
address@hidden file in @file{RCS/foo.c,v} (but it could be
+other places; consult the @sc{rcs} documentation for
+details). Then create the appropriate directories in
address@hidden if they do not already exist. Then copy the
+files into the appropriate directories in the @sc{cvs}
+repository (the name in the repository must be the name
+of the source file with @samp{,v} added; the files go
+directly in the appropriate directory of the repository,
+not in an @file{RCS} subdirectory). This is one of the
+few times when it is a good idea to access the @sc{cvs}
+repository directly, rather than using @sc{cvs}
+commands. Then you are ready to check out a new
+working directory.
address@hidden Someday there probably should be a "cvs import -t
address@hidden rcs" or some such. It could even create magic
address@hidden branches. It could also do something about the case
address@hidden where the RCS file had a (non-magic) "0" branch.
+
+The @sc{rcs} file should not be locked when you move it
+into @sc{cvs}; if it is, @sc{cvs} will have trouble
+letting you operate on it.
address@hidden What is the easiest way to unlock your files if you
address@hidden have them locked? Especially if you have a lot of them?
address@hidden This is a CVS bug/misfeature; importing RCS files
address@hidden should ignore whether they are locked and leave them in
address@hidden an unlocked state. Yet another reason for a separate
address@hidden "import RCS file" command.
+
address@hidden How many is "many"? Or do they just import RCS files?
address@hidden From another version control system
+Many version control systems have the ability to export
address@hidden files in the standard format. If yours does,
+export the @sc{rcs} files and then follow the above
+instructions.
+
+Failing that, probably your best bet is to write a
+script that will check out the files one revision at a
+time using the command line interface to the other
+system, and then check the revisions into @sc{cvs}.
+The @file{sccs2rcs} script mentioned below may be a
+useful example to follow.
+
address@hidden SCCS, importing files from
address@hidden From SCCS
+There is a script in the @file{contrib} directory of
+the @sc{cvs} source distribution called @file{sccs2rcs}
+which converts @sc{sccs} files to @sc{rcs} files.
+Note: you must run it on a machine which has both
address@hidden and @sc{rcs} installed, and like everything
+else in contrib it is unsupported (your mileage may
+vary).
+
address@hidden PVCS, importing files from
address@hidden From PVCS
+There is a script in the @file{contrib} directory of
+the @sc{cvs} source distribution called @file{pvcs_to_rcs}
+which converts @sc{pvcs} archives to @sc{rcs} files.
+You must run it on a machine which has both
address@hidden and @sc{rcs} installed, and like everything
+else in contrib it is unsupported (your mileage may
+vary). See the comments in the script for details.
address@hidden table
address@hidden CMZ and/or PATCHY were systems that were used in the
address@hidden high energy physics community (especially for
address@hidden CERNLIB). CERN has replaced them with CVS, but the
address@hidden CAR format seems to live on as a way to submit
address@hidden changes. There is a program car2cvs which converts
address@hidden but I'm not sure where one gets a copy.
address@hidden Not sure it is worth mentioning here, since it would
address@hidden appear to affect only one particular community.
address@hidden Best page for more information is:
address@hidden http://wwwcn1.cern.ch/asd/cvs/index.html
address@hidden See also:
address@hidden http://ecponion.cern.ch/ecpsa/cernlib.html
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden From scratch
address@hidden Creating a directory tree from scratch
+
address@hidden Also/instead should be documenting
address@hidden $ cvs co -l .
address@hidden $ mkdir tc
address@hidden $ cvs add tc
address@hidden $ cd tc
address@hidden $ mkdir man
address@hidden $ cvs add man
address@hidden etc.
address@hidden Using import to create the directories only is
address@hidden probably a somewhat confusing concept.
+For a new project, the easiest thing to do is probably
+to create an empty directory structure, like this:
+
address@hidden
+$ mkdir tc
+$ mkdir tc/man
+$ mkdir tc/testing
address@hidden example
+
+After that, you use the @code{import} command to create
+the corresponding (empty) directory structure inside
+the repository:
+
address@hidden
+$ cd tc
+$ cvs import -m "Created directory structure" yoyodyne/@var{dir} yoyo start
address@hidden example
+
+Then, use @code{add} to add files (and new directories)
+as they appear.
+
+Check that the permissions @sc{cvs} sets on the
+directories inside @code{$CVSROOT} are reasonable.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Defining the module
address@hidden Defining the module
address@hidden Defining a module
address@hidden Editing the modules file
address@hidden Module, defining
address@hidden Modules file, changing
+
+The next step is to define the module in the
address@hidden file. This is not strictly necessary,
+but modules can be convenient in grouping together
+related files and directories.
+
+In simple cases these steps are sufficient to define a module.
+
address@hidden
address@hidden
+Get a working copy of the modules file.
+
address@hidden
+$ cvs checkout CVSROOT/modules
+$ cd CVSROOT
address@hidden example
+
address@hidden
+Edit the file and insert a line that defines the module. @xref{Intro
+administrative files}, for an introduction. @xref{modules}, for a full
+description of the modules file. You can use the
+following line to define the module @samp{tc}:
+
address@hidden
+tc yoyodyne/tc
address@hidden example
+
address@hidden
+Commit your changes to the modules file.
+
address@hidden
+$ cvs commit -m "Added the tc module." modules
address@hidden example
+
address@hidden
+Release the modules module.
+
address@hidden
+$ cd ..
+$ cvs release -d CVSROOT
address@hidden example
address@hidden enumerate
+
address@hidden
---------------------------------------------------------------------
address@hidden Revisions
address@hidden Revisions
+
+For many uses of @sc{cvs}, one doesn't need to worry
+too much about revision numbers; @sc{cvs} assigns
+numbers such as @code{1.1}, @code{1.2}, and so on, and
+that is all one needs to know. However, some people
+prefer to have more knowledge and control concerning
+how @sc{cvs} assigns revision numbers.
+
+If one wants to keep track of a set of revisions
+involving more than one file, such as which revisions
+went into a particular release, one uses a @dfn{tag},
+which is a symbolic revision which can be assigned to a
+numeric revision in each file.
+
address@hidden
+* Revision numbers:: The meaning of a revision number
+* Versions revisions releases:: Terminology used in this manual
+* Assigning revisions:: Assigning revisions
+* Tags:: Tags--Symbolic revisions
+* Tagging the working directory:: The cvs tag command
+* Tagging by date/tag:: The cvs rtag command
+* Modifying tags:: Adding, renaming, and deleting tags
+* Tagging add/remove:: Tags with adding and removing files
+* Sticky tags:: Certain tags are persistent
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Revision numbers
address@hidden Revision numbers
address@hidden Revision numbers
address@hidden Revision tree
address@hidden Linear development
address@hidden Number, revision-
address@hidden Decimal revision number
address@hidden Branch number
address@hidden Number, branch
+
+Each version of a file has a unique @dfn{revision
+number}. Revision numbers look like @samp{1.1},
address@hidden, @samp{1.3.2.2} or even @samp{1.3.2.2.4.5}.
+A revision number always has an even number of
+period-separated decimal integers. By default revision
+1.1 is the first revision of a file. Each successive
+revision is given a new number by increasing the
+rightmost number by one. The following figure displays
+a few revisions, with newer revisions to the right.
+
address@hidden
+ +-----+ +-----+ +-----+ +-----+ +-----+
+ ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
+ +-----+ +-----+ +-----+ +-----+ +-----+
address@hidden example
+
+It is also possible to end up with numbers containing
+more than one period, for example @samp{1.3.2.2}. Such
+revisions represent revisions on branches
+(@pxref{Branching and merging}); such revision numbers
+are explained in detail in @ref{Branches and
+revisions}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Versions revisions releases
address@hidden Versions, revisions and releases
address@hidden Revisions, versions and releases
address@hidden Versions, revisions and releases
address@hidden Releases, revisions and versions
+
+A file can have several versions, as described above.
+Likewise, a software product can have several versions.
+A software product is often given a version number such
+as @samp{4.1.1}.
+
+Versions in the first sense are called @dfn{revisions}
+in this document, and versions in the second sense are
+called @dfn{releases}. To avoid confusion, the word
address@hidden is almost never used in this document.
+
address@hidden Assigning revisions
address@hidden Assigning revisions
+
address@hidden We avoid the "major revision" terminology. It seems
address@hidden like jargon. Hopefully "first number" is clear enough.
address@hidden
address@hidden Well, in the context of software release numbers,
address@hidden "major" and "minor" release or version numbers are
address@hidden documented in at least the GNU Coding Standards, but I'm
address@hidden still not sure I find that a valid reason to apply the
address@hidden terminology to RCS revision numbers. "First", "Second",
address@hidden "subsequent", and so on is almost surely clearer,
address@hidden especially to a novice reader. -DRP
+By default, @sc{cvs} will assign numeric revisions by
+leaving the first number the same and incrementing the
+second number. For example, @code{1.1}, @code{1.2},
address@hidden, etc.
+
+When adding a new file, the second number will always
+be one and the first number will equal the highest
+first number of any file in that directory. For
+example, the current directory contains files whose
+highest numbered revisions are @code{1.7}, @code{3.1},
+and @code{4.12}, then an added file will be given the
+numeric revision @code{4.1}.
+
address@hidden This is sort of redundant with something we said a
address@hidden while ago. Somewhere we need a better way of
address@hidden introducing how the first number can be anything
address@hidden except "1", perhaps. Also I don't think this
address@hidden presentation is clear on why we are discussing releases
address@hidden and first numbers of numeric revisions in the same
address@hidden breath.
+Normally there is no reason to care
+about the revision numbers---it is easier to treat them
+as internal numbers that @sc{cvs} maintains, and tags
+provide a better way to distinguish between things like
+release 1 versus release 2 of your product
+(@pxref{Tags}). However, if you want to set the
+numeric revisions, the @samp{-r} option to @code{cvs
+commit} can do that. The @samp{-r} option implies the
address@hidden option, in the sense that it causes the
+files to be committed even if they are not modified.
+
+For example, to bring all your files up to
+revision 3.0 (including those that haven't changed),
+you might invoke:
+
address@hidden
+$ cvs commit -r 3.0
address@hidden example
+
+Note that the number you specify with @samp{-r} must be
+larger than any existing revision number. That is, if
+revision 3.0 exists, you cannot @samp{cvs commit
+-r 1.3}. If you want to maintain several releases in
+parallel, you need to use a branch (@pxref{Branching and merging}).
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Tags
address@hidden Tags--Symbolic revisions
address@hidden Tags
+
+The revision numbers live a life of their own. They
+need not have anything at all to do with the release
+numbers of your software product. Depending
+on how you use @sc{cvs} the revision numbers might change several times
+between two releases. As an example, some of the
+source files that make up @sc{rcs} 5.6 have the following
+revision numbers:
address@hidden RCS revision numbers
+
address@hidden
+ci.c 5.21
+co.c 5.9
+ident.c 5.3
+rcs.c 5.12
+rcsbase.h 5.11
+rcsdiff.c 5.10
+rcsedit.c 5.11
+rcsfcmp.c 5.9
+rcsgen.c 5.10
+rcslex.c 5.11
+rcsmap.c 5.2
+rcsutil.c 5.10
address@hidden example
+
address@hidden tag (subcommand), introduction
address@hidden Tags, symbolic name
address@hidden Symbolic name (tag)
address@hidden Name, symbolic (tag)
address@hidden HEAD, as reserved tag name
address@hidden BASE, as reserved tag name
+You can use the @code{tag} command to give a symbolic name to a
+certain revision of a file. You can use the @samp{-v} flag to the
address@hidden command to see all tags that a file has, and
+which revision numbers they represent. Tag names must
+start with an uppercase or lowercase letter and can
+contain uppercase and lowercase letters, digits,
address@hidden, and @samp{_}. The two tag names @code{BASE}
+and @code{HEAD} are reserved for use by @sc{cvs}. It
+is expected that future names which are special to
address@hidden will be specially named, for example by
+starting with @samp{.}, rather than being named analogously to
address@hidden and @code{HEAD}, to avoid conflicts with
+actual tag names.
address@hidden Including a character such as % or = has also been
address@hidden suggested as the naming convention for future
address@hidden special tag names. Starting with . is nice because
address@hidden that is not a legal tag name as far as RCS is concerned.
address@hidden FIXME: CVS actually accepts quite a few characters
address@hidden in tag names, not just the ones documented above
address@hidden (see RCS_check_tag). RCS
address@hidden defines legitimate tag names by listing illegal
address@hidden characters rather than legal ones. CVS is said to lose its
address@hidden mind if you try to use "/" (try making such a tag sticky
address@hidden and using "cvs status" client/server--see remote
address@hidden protocol format for entries line for probable cause).
address@hidden TODO: The testsuite
address@hidden should test for whatever are documented above as
address@hidden officially-OK tag names, and CVS should at least reject
address@hidden characters that won't work, like "/".
+
+You'll want to choose some convention for naming tags,
+based on information such as the name of the program
+and the version number of the release. For example,
+one might take the name of the program, immediately
+followed by the version number with @samp{.} changed to
address@hidden, so that @sc{cvs} 1.9 would be tagged with the name
address@hidden If you choose a consistent convention,
+then you won't constantly be guessing whether a tag is
address@hidden or @code{cvs1_9} or what. You might
+even want to consider enforcing your convention in the
+taginfo file (@pxref{user-defined logging}).
address@hidden Might be nice to say more about using taginfo this
address@hidden way, like giving an example, or pointing out any particular
address@hidden issues which arise.
+
address@hidden Adding a tag
address@hidden Tags, example
+The following example shows how you can add a tag to a
+file. The commands must be issued inside your working
+directory. That is, you should issue the
+command in the directory where @file{backend.c}
+resides.
+
address@hidden
+$ cvs tag rel-0-4 backend.c
+T backend.c
+$ cvs status -v backend.c
+===================================================================
+File: backend.c Status: Up-to-date
+
+ Version: 1.4 Tue Dec 1 14:39:01 1992
+ RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v
+ Sticky Tag: (none)
+ Sticky Date: (none)
+ Sticky Options: (none)
+
+ Existing Tags:
+ rel-0-4 (revision: 1.4)
+
address@hidden example
+
+For a complete summary of the syntax of @code{cvs tag},
+including the various options, see @ref{Invoking CVS}.
+
+There is seldom reason to tag a file in isolation. A more common use is
+to tag all the files that constitute a module with the same tag at
+strategic points in the development life-cycle, such as when a release
+is made.
+
address@hidden
+$ cvs tag rel-1-0 .
+cvs tag: Tagging .
+T Makefile
+T backend.c
+T driver.c
+T frontend.c
+T parser.c
address@hidden example
+
address@hidden
+(When you give @sc{cvs} a directory as argument, it generally applies the
+operation to all the files in that directory, and (recursively), to any
+subdirectories that it may contain. @xref{Recursive behavior}.)
+
address@hidden Retrieving an old revision using tags
address@hidden Tags, retrieving old revisions
+The @code{checkout} command has a flag, @samp{-r}, that lets you check out
+a certain revision of a module. This flag makes it easy to
+retrieve the sources that make up release 1.0 of the module @samp{tc} at
+any time in the future:
+
address@hidden
+$ cvs checkout -r rel-1-0 tc
address@hidden example
+
address@hidden
+This is useful, for instance, if someone claims that there is a bug in
+that release, but you cannot find the bug in the current working copy.
+
+You can also check out a module as it was at any given date.
address@hidden options}. When specifying @samp{-r} to
+any of these commands, you will need beware of sticky
+tags; see @ref{Sticky tags}.
+
+When you tag more than one file with the same tag you
+can think about the tag as "a curve drawn through a
+matrix of filename vs. revision number." Say we have 5
+files with the following revisions:
+
address@hidden
address@hidden
+ file1 file2 file3 file4 file5
+
+ 1.1 1.1 1.1 1.1 /--1.1* <-*- TAG
+ 1.2*- 1.2 1.2 -1.2*-
+ 1.3 \- 1.3*- 1.3 / 1.3
+ 1.4 \ 1.4 / 1.4
+ \-1.5*- 1.5
+ 1.6
address@hidden group
address@hidden example
+
+At some time in the past, the @code{*} versions were tagged.
+You can think of the tag as a handle attached to the curve
+drawn through the tagged revisions. When you pull on
+the handle, you get all the tagged revisions. Another
+way to look at it is that you "sight" through a set of
+revisions that is "flat" along the tagged revisions,
+like this:
+
address@hidden
address@hidden
+ file1 file2 file3 file4 file5
+
+ 1.1
+ 1.2
+ 1.1 1.3 _
+ 1.1 1.2 1.4 1.1 /
+ 1.2*----1.3*----1.5*----1.2*----1.1 (--- <--- Look here
+ 1.3 1.6 1.3 \_
+ 1.4 1.4
+ 1.5
address@hidden group
address@hidden example
+
address@hidden Tagging the working directory
address@hidden Specifying what to tag from the working directory
+
address@hidden tag (subcommand)
+The example in the previous section demonstrates one of
+the most common ways to choose which revisions to tag.
+Namely, running the @code{cvs tag} command without
+arguments causes @sc{cvs} to select the revisions which
+are checked out in the current working directory. For
+example, if the copy of @file{backend.c} in working
+directory was checked out from revision 1.4, then
address@hidden will tag revision 1.4. Note that the tag is
+applied immediately to revision 1.4 in the repository;
+tagging is not like modifying a file, or other
+operations in which one first modifies the working
+directory and then runs @code{cvs commit} to transfer
+that modification to the repository.
+
+One potentially surprising aspect of the fact that
address@hidden tag} operates on the repository is that you
+are tagging the checked-in revisions, which may differ
+from locally modified files in your working directory.
+If you want to avoid doing this by mistake, specify the
address@hidden option to @code{cvs tag}. If there are any
+locally modified files, @sc{cvs} will abort with an
+error before it tags any files:
+
address@hidden
+$ cvs tag -c rel-0-4
+cvs tag: backend.c is locally modified
+cvs [tag aborted]: correct the above errors first!
address@hidden example
+
address@hidden Tagging by date/tag
address@hidden Specifying what to tag by date or revision
address@hidden rtag (subcommand)
+
+The @code{cvs rtag} command tags the repository as of a
+certain date or time (or can be used to tag the latest
+revision). @code{rtag} works directly on the
+repository contents (it requires no prior checkout and
+does not look for a working directory).
+
+The following options specify which date or revision to
+tag. See @ref{Common options}, for a complete
+description of them.
+
address@hidden @code
address@hidden -D @var{date}
+Tag the most recent revision no later than @var{date}.
+
address@hidden -f
+Only useful with the @samp{-D @var{date}} or @samp{-r @var{tag}}
+flags. If no matching revision is found, use the most
+recent revision (instead of ignoring the file).
+
address@hidden -r @var{tag}
+Only tag those files that contain existing tag @var{tag}.
address@hidden table
+
+The @code{cvs tag} command also allows one to specify
+files by revision or date, using the same @samp{-r},
address@hidden, and @samp{-f} options. However, this
+feature is probably not what you want. The reason is
+that @code{cvs tag} chooses which files to tag based on
+the files that exist in the working directory, rather
+than the files which existed as of the given tag/date.
+Therefore, you are generally better off using @code{cvs
+rtag}. The exceptions might be cases like:
+
address@hidden
+cvs tag -r 1.4 stable backend.c
address@hidden example
+
address@hidden Modifying tags
address@hidden Deleting, moving, and renaming tags
+
address@hidden Also see:
address@hidden "How do I move or rename a magic branch tag?"
address@hidden in the FAQ (I think the issues it talks about still
address@hidden apply, but this could use some sanity.sh work).
+
+Normally one does not modify tags. They exist in order
+to record the history of the repository and so deleting
+them or changing their meaning would, generally, not be
+what you want.
+
+However, there might be cases in which one uses a tag
+temporarily or accidentally puts one in the wrong
+place. Therefore, one might delete, move, or rename a
+tag.
+
address@hidden
address@hidden: the commands in this section are
+dangerous; they permanently discard historical
+information and it can be difficult or impossible to
+recover from errors. If you are a @sc{cvs}
+administrator, you may consider restricting these
+commands with taginfo (@pxref{user-defined logging}).}
+
address@hidden Deleting tags
address@hidden Deleting branch tags
address@hidden Removing tags
address@hidden Removing branch tags
address@hidden Tags, deleting
address@hidden Branch tags, deleting
+To delete a tag, specify the @samp{-d} option to either
address@hidden tag} or @code{cvs rtag}. For example:
+
address@hidden
+cvs rtag -d rel-0-4 tc
address@hidden example
+
address@hidden
+deletes the non-branch tag @code{rel-0-4} from the module @code{tc}.
+In the event that branch tags are encountered within the repository
+with the given name, a warning message will be issued and the branch
+tag will not be deleted. If you are absolutely certain you know what
+you are doing, the @code{-B} option may be specified to allow deletion
+of branch tags. In that case, any non-branch tags encountered will
+trigger warnings and will not be deleted.
+
address@hidden
address@hidden: Moving branch tags is very dangerous! If you think
+you need the @code{-B} option, think again and ask your @sc{cvs}
+administrator about it (if that isn't you). There is almost certainly
+another way to accomplish what you want to accomplish.}
+
address@hidden Moving tags
address@hidden Moving branch tags
address@hidden Tags, moving
address@hidden Branch tags, moving
+When we say @dfn{move} a tag, we mean to make the same
+name point to different revisions. For example, the
address@hidden tag may currently point to revision 1.4
+of @file{backend.c} and perhaps we want to make it
+point to revision 1.6. To move a non-branch tag, specify the
address@hidden option to either @code{cvs tag} or @code{cvs
+rtag}. For example, the task just mentioned might be
+accomplished as:
+
address@hidden
+cvs tag -r 1.6 -F stable backend.c
address@hidden example
+
address@hidden
+If any branch tags are encountered in the repository
+with the given name, a warning is issued and the branch
+tag is not disturbed. If you are absolutely certain you
+wish to move the branch tag, the @code{-B} option may be specified.
+In that case, non-branch tags encountered with the given
+name are ignored with a warning message.
+
address@hidden
address@hidden: Moving branch tags is very dangerous! If you think you
+need the @code{-B} option, think again and ask your @sc{cvs}
+administrator about it (if that isn't you). There is almost certainly
+another way to accomplish what you want to accomplish.}
+
address@hidden Renaming tags
address@hidden Tags, renaming
+When we say @dfn{rename} a tag, we mean to make a
+different name point to the same revisions as the old
+tag. For example, one may have misspelled the tag name
+and want to correct it (hopefully before others are
+relying on the old spelling). To rename a tag, first
+create a new tag using the @samp{-r} option to
address@hidden rtag}, and then delete the old name. (Caution:
+this method will not work with branch tags.)
+This leaves the new tag on exactly the
+same files as the old tag. For example:
+
address@hidden
+cvs rtag -r old-name-0-4 rel-0-4 tc
+cvs rtag -d old-name-0-4 tc
address@hidden example
+
address@hidden Tagging add/remove
address@hidden Tagging and adding and removing files
+
+The subject of exactly how tagging interacts with
+adding and removing files is somewhat obscure; for the
+most part @sc{cvs} will keep track of whether files
+exist or not without too much fussing. By default,
+tags are applied to only files which have a revision
+corresponding to what is being tagged. Files which did
+not exist yet, or which were already removed, simply
+omit the tag, and @sc{cvs} knows to treat the absence
+of a tag as meaning that the file didn't exist as of
+that tag.
+
+However, this can lose a small amount of information.
+For example, suppose a file was added and then removed.
+Then, if the tag is missing for that file, there is no
+way to know whether the tag refers to the time before
+the file was added, or the time after it was removed.
+If you specify the @samp{-r} option to @code{cvs rtag},
+then @sc{cvs} tags the files which have been removed,
+and thereby avoids this problem. For example, one
+might specify @code{-r HEAD} to tag the head.
+
+On the subject of adding and removing files, the
address@hidden rtag} command has a @samp{-a} option which
+means to clear the tag from removed files that would
+not otherwise be tagged. For example, one might
+specify this option in conjunction with @samp{-F} when
+moving a tag. If one moved a tag without @samp{-a},
+then the tag in the removed files might still refer to
+the old revision, rather than reflecting the fact that
+the file had been removed. I don't think this is
+necessary if @samp{-r} is specified, as noted above.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Sticky tags
address@hidden Sticky tags
address@hidden Sticky tags
address@hidden Tags, sticky
+
address@hidden A somewhat related issue is per-directory sticky
address@hidden tags (see comment at CVS/Tag in node Working
address@hidden directory storage); we probably want to say
address@hidden something like "you can set a sticky tag for only
address@hidden some files, but you don't want to" or some such.
+
+Sometimes a working copy's revision has extra data
+associated with it, for example it might be on a branch
+(@pxref{Branching and merging}), or restricted to
+versions prior to a certain date by @samp{checkout -D}
+or @samp{update -D}. Because this data persists --
+that is, it applies to subsequent commands in the
+working copy -- we refer to it as @dfn{sticky}.
+
+Most of the time, stickiness is an obscure aspect of
address@hidden that you don't need to think about. However,
+even if you don't want to use the feature, you may need
+to know @emph{something} about sticky tags (for
+example, how to avoid them!).
+
+You can use the @code{status} command to see if any
+sticky tags or dates are set:
+
address@hidden
+$ cvs status driver.c
+===================================================================
+File: driver.c Status: Up-to-date
+
+ Version: 1.7.2.1 Sat Dec 5 19:35:03 1992
+ RCS Version: 1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v
+ Sticky Tag: rel-1-0-patches (branch: 1.7.2)
+ Sticky Date: (none)
+ Sticky Options: (none)
+
address@hidden example
+
address@hidden Resetting sticky tags
address@hidden Sticky tags, resetting
address@hidden Deleting sticky tags
+The sticky tags will remain on your working files until
+you delete them with @samp{cvs update -A}. The
address@hidden option merges local changes into the version of the
+file from the head of the trunk, removing any sticky tags,
+dates, or options. See @ref{update} for more on the operation
+of @code{cvs update}.
+
address@hidden Sticky date
+The most common use of sticky tags is to identify which
+branch one is working on, as described in
address@hidden branches}. However, non-branch
+sticky tags have uses as well. For example,
+suppose that you want to avoid updating your working
+directory, to isolate yourself from possibly
+destabilizing changes other people are making. You
+can, of course, just refrain from running @code{cvs
+update}. But if you want to avoid updating only a
+portion of a larger tree, then sticky tags can help.
+If you check out a certain revision (such as 1.4) it
+will become sticky. Subsequent @code{cvs update}
+commands will
+not retrieve the latest revision until you reset the
+tag with @code{cvs update -A}. Likewise, use of the
address@hidden option to @code{update} or @code{checkout}
+sets a @dfn{sticky date}, which, similarly, causes that
+date to be used for future retrievals.
+
+People often want to retrieve an old version of
+a file without setting a sticky tag. This can
+be done with the @samp{-p} option to @code{checkout} or
address@hidden, which sends the contents of the file to
+standard output. For example:
address@hidden
+$ cvs update -p -r 1.1 file1 >file1
+===================================================================
+Checking out file1
+RCS: /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v
+VERS: 1.1
+***************
+$
address@hidden example
+
+However, this isn't the easiest way, if you are asking
+how to undo a previous checkin (in this example, put
address@hidden back to the way it was as of revision
+1.1). In that case you are better off using the
address@hidden option to @code{update}; for further
+discussion see @ref{Merging two revisions}.
+
address@hidden
---------------------------------------------------------------------
address@hidden Branching and merging
address@hidden Branching and merging
address@hidden Branching
address@hidden Merging
address@hidden Copying changes
address@hidden Main trunk and branches
address@hidden Revision tree, making branches
address@hidden Branches, copying changes between
address@hidden Changes, copying between branches
address@hidden Modifications, copying between branches
+
address@hidden allows you to isolate changes onto a separate
+line of development, known as a @dfn{branch}. When you
+change files on a branch, those changes do not appear
+on the main trunk or other branches.
+
+Later you can move changes from one branch to another
+branch (or the main trunk) by @dfn{merging}. Merging
+involves first running @code{cvs update -j}, to merge
+the changes into the working directory.
+You can then commit that revision, and thus effectively
+copy the changes onto another branch.
+
address@hidden
+* Branches motivation:: What branches are good for
+* Creating a branch:: Creating a branch
+* Accessing branches:: Checking out and updating branches
+* Branches and revisions:: Branches are reflected in revision numbers
+* Magic branch numbers:: Magic branch numbers
+* Merging a branch:: Merging an entire branch
+* Merging more than once:: Merging from a branch several times
+* Merging two revisions:: Merging differences between two revisions
+* Merging adds and removals:: What if files are added or removed?
+* Merging and keywords:: Avoiding conflicts due to keyword substitution
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Branches motivation
address@hidden What branches are good for
address@hidden Branches motivation
address@hidden What branches are good for
address@hidden Motivation for branches
+
address@hidden FIXME: this node mentions one way to use branches,
address@hidden but it is by no means the only way. For example,
address@hidden the technique of committing a new feature on a branch,
address@hidden until it is ready for the main trunk. The whole
address@hidden thing is generally speaking more akin to the
address@hidden "Revision management" node although it isn't clear to
address@hidden me whether policy matters should be centralized or
address@hidden distributed throughout the relevant sections.
+Suppose that release 1.0 of tc has been made. You are continuing to
+develop tc, planning to create release 1.1 in a couple of months. After a
+while your customers start to complain about a fatal bug. You check
+out release 1.0 (@pxref{Tags}) and find the bug
+(which turns out to have a trivial fix). However, the current revision
+of the sources are in a state of flux and are not expected to be stable
+for at least another month. There is no way to make a
+bugfix release based on the newest sources.
+
+The thing to do in a situation like this is to create a @dfn{branch} on
+the revision trees for all the files that make up
+release 1.0 of tc. You can then make
+modifications to the branch without disturbing the main trunk. When the
+modifications are finished you can elect to either incorporate them on
+the main trunk, or leave them on the branch.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Creating a branch
address@hidden Creating a branch
address@hidden Creating a branch
address@hidden Branch, creating a
address@hidden tag (subcommand), creating a branch using
address@hidden rtag (subcommand), creating a branch using
+
+You can create a branch with @code{tag -b}; for
+example, assuming you're in a working copy:
+
address@hidden
+$ cvs tag -b rel-1-0-patches
address@hidden example
+
address@hidden FIXME: we should be more explicit about the value of
address@hidden having a tag on the branchpoint. For example
address@hidden "cvs tag rel-1-0-patches-branchpoint" before
address@hidden the "cvs tag -b". This points out that
address@hidden rel-1-0-patches is a pretty awkward name for
address@hidden this example (more so than for the rtag example
address@hidden below).
+
+This splits off a branch based on the current revisions
+in the working copy, assigning that branch the name
address@hidden
+
+It is important to understand that branches get created
+in the repository, not in the working copy. Creating a
+branch based on current revisions, as the above example
+does, will @emph{not} automatically switch the working
+copy to be on the new branch. For information on how
+to do that, see @ref{Accessing branches}.
+
+You can also create a branch without reference to any
+working copy, by using @code{rtag}:
+
address@hidden
+$ cvs rtag -b -r rel-1-0 rel-1-0-patches tc
address@hidden example
+
address@hidden rel-1-0} says that this branch should be
+rooted at the revision that
+corresponds to the tag @samp{rel-1-0}. It need not
+be the most recent revision -- it's often useful to
+split a branch off an old revision (for example, when
+fixing a bug in a past release otherwise known to be
+stable).
+
+As with @samp{tag}, the @samp{-b} flag tells
address@hidden to create a branch (rather than just a
+symbolic revision name). Note that the numeric
+revision number that matches @samp{rel-1-0} will
+probably be different from file to file.
+
+So, the full effect of the command is to create a new
+branch -- named @samp{rel-1-0-patches} -- in module
address@hidden, rooted in the revision tree at the point tagged
+by @samp{rel-1-0}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Accessing branches
address@hidden Accessing branches
address@hidden Check out a branch
address@hidden Retrieve a branch
address@hidden Access a branch
address@hidden Identifying a branch
address@hidden Branch, check out
address@hidden Branch, retrieving
address@hidden Branch, accessing
address@hidden Branch, identifying
+
+You can retrieve a branch in one of two ways: by
+checking it out fresh from the repository, or by
+switching an existing working copy over to the branch.
+
+To check out a branch from the repository, invoke
address@hidden with the @samp{-r} flag, followed by
+the tag name of the branch (@pxref{Creating a branch}):
+
address@hidden
+$ cvs checkout -r rel-1-0-patches tc
address@hidden example
+
+Or, if you already have a working copy, you can switch
+it to a given branch with @samp{update -r}:
+
address@hidden
+$ cvs update -r rel-1-0-patches tc
address@hidden example
+
address@hidden
+or equivalently:
+
address@hidden
+$ cd tc
+$ cvs update -r rel-1-0-patches
address@hidden example
+
+It does not matter if the working copy was originally
+on the main trunk or on some other branch -- the above
+command will switch it to the named branch. And
+similarly to a regular @samp{update} command,
address@hidden -r} merges any changes you have made,
+notifying you of conflicts where they occur.
+
+Once you have a working copy tied to a particular
+branch, it remains there until you tell it otherwise.
+This means that changes checked in from the working
+copy will add new revisions on that branch, while
+leaving the main trunk and other branches unaffected.
+
address@hidden Branches, sticky
+To find out what branch a working copy is on, you can
+use the @samp{status} command. In its output, look for
+the field named @samp{Sticky tag} (@pxref{Sticky tags})
+-- that's @sc{cvs}'s way of telling you the branch, if
+any, of the current working files:
+
address@hidden
+$ cvs status -v driver.c backend.c
+===================================================================
+File: driver.c Status: Up-to-date
+
+ Version: 1.7 Sat Dec 5 18:25:54 1992
+ RCS Version: 1.7 /u/cvsroot/yoyodyne/tc/driver.c,v
+ Sticky Tag: rel-1-0-patches (branch: 1.7.2)
+ Sticky Date: (none)
+ Sticky Options: (none)
+
+ Existing Tags:
+ rel-1-0-patches (branch: 1.7.2)
+ rel-1-0 (revision: 1.7)
+
+===================================================================
+File: backend.c Status: Up-to-date
+
+ Version: 1.4 Tue Dec 1 14:39:01 1992
+ RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v
+ Sticky Tag: rel-1-0-patches (branch: 1.4.2)
+ Sticky Date: (none)
+ Sticky Options: (none)
+
+ Existing Tags:
+ rel-1-0-patches (branch: 1.4.2)
+ rel-1-0 (revision: 1.4)
+ rel-0-4 (revision: 1.4)
+
address@hidden example
+
+Don't be confused by the fact that the branch numbers
+for each file are different (@samp{1.7.2} and
address@hidden respectively). The branch tag is the
+same, @samp{rel-1-0-patches}, and the files are
+indeed on the same branch. The numbers simply reflect
+the point in each file's revision history at which the
+branch was made. In the above example, one can deduce
+that @samp{driver.c} had been through more changes than
address@hidden before this branch was created.
+
+See @ref{Branches and revisions} for details about how
+branch numbers are constructed.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Branches and revisions
address@hidden Branches and revisions
address@hidden Branch number
address@hidden Number, branch
address@hidden Revision numbers (branches)
+
+Ordinarily, a file's revision history is a linear
+series of increments (@pxref{Revision numbers}):
+
address@hidden
+ +-----+ +-----+ +-----+ +-----+ +-----+
+ ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
+ +-----+ +-----+ +-----+ +-----+ +-----+
address@hidden example
+
+However, @sc{cvs} is not limited to linear development. The
address@hidden tree} can be split into @dfn{branches},
+where each branch is a self-maintained line of
+development. Changes made on one branch can easily be
+moved back to the main trunk.
+
+Each branch has a @dfn{branch number}, consisting of an
+odd number of period-separated decimal integers. The
+branch number is created by appending an integer to the
+revision number where the corresponding branch forked
+off. Having branch numbers allows more than one branch
+to be forked off from a certain revision.
+
address@hidden 3500
+All revisions on a branch have revision numbers formed
+by appending an ordinal number to the branch number.
+The following figure illustrates branching with an
+example.
+
address@hidden
address@hidden This example used to have a 1.2.2.4 revision, which
address@hidden might help clarify that development can continue on
address@hidden 1.2.2. Might be worth reinstating if it can be done
address@hidden without overfull hboxes.
address@hidden
+ +-------------+
+ Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 !
+ / +-------------+
+ /
+ /
+ +---------+ +---------+ +---------+
+Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
+ / +---------+ +---------+ +---------+
+ /
+ /
++-----+ +-----+ +-----+ +-----+ +-----+
+! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
++-----+ +-----+ +-----+ +-----+ +-----+
+ !
+ !
+ ! +---------+ +---------+ +---------+
+Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 !
+ +---------+ +---------+ +---------+
+
address@hidden group
address@hidden example
+
address@hidden -- However, at least for me the figure is not enough. I
suggest more
address@hidden -- text to accompany it. "A picture is worth a thousand
words", so you
address@hidden -- have to make sure the reader notices the couple of hundred
words
address@hidden -- *you* had in mind more than the others!
+
address@hidden -- Why an even number of segments? This section implies that
this is
address@hidden -- how the main trunk is distinguished from branch roots, but
you never
address@hidden -- explicitly say that this is the purpose of the [by itself
rather
address@hidden -- surprising] restriction to an even number of segments.
+
+The exact details of how the branch number is
+constructed is not something you normally need to be
+concerned about, but here is how it works: When
address@hidden creates a branch number it picks the first
+unused even integer, starting with 2. So when you want
+to create a branch from revision 6.4 it will be
+numbered 6.4.2. All branch numbers ending in a zero
+(such as 6.4.0) are used internally by @sc{cvs}
+(@pxref{Magic branch numbers}). The branch 1.1.1 has a
+special meaning. @xref{Tracking sources}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Magic branch numbers
address@hidden Magic branch numbers
+
address@hidden Want xref to here from "log"?
+
+This section describes a @sc{cvs} feature called
address@hidden branches}. For most purposes, you need not
+worry about magic branches; @sc{cvs} handles them for
+you. However, they are visible to you in certain
+circumstances, so it may be useful to have some idea of
+how it works.
+
+Externally, branch numbers consist of an odd number of
+dot-separated decimal integers. @xref{Revision
+numbers}. That is not the whole truth, however. For
+efficiency reasons @sc{cvs} sometimes inserts an extra 0
+in the second rightmost position (1.2.4 becomes
+1.2.0.4, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so
+on).
+
address@hidden does a pretty good job at hiding these so
+called magic branches, but in a few places the hiding
+is incomplete:
+
address@hidden @bullet
address@hidden
+The magic branch number appears in the output from
address@hidden log}.
address@hidden What output should appear instead?
+
address@hidden
+You cannot specify a symbolic branch name to @code{cvs
+admin}.
+
address@hidden itemize
+
address@hidden Can CVS do this automatically the first time
address@hidden you check something in to that branch? Should
address@hidden it?
+You can use the @code{admin} command to reassign a
+symbolic name to a branch the way @sc{rcs} expects it
+to be. If @code{R4patches} is assigned to the branch
+1.4.2 (magic branch number 1.4.0.2) in file
address@hidden you can do this:
+
address@hidden
+$ cvs admin -NR4patches:1.4.2 numbers.c
address@hidden example
+
+It only works if at least one revision is already
+committed on the branch. Be very careful so that you
+do not assign the tag to the wrong number. (There is
+no way to see how the tag was assigned yesterday).
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Merging a branch
address@hidden Merging an entire branch
address@hidden Merging a branch
address@hidden -j (merging branches)
+
+You can merge changes made on a branch into your working copy by giving
+the @samp{-j @var{branchname}} flag to the @code{update} subcommand. With one
address@hidden @var{branchname}} option it merges the changes made between the
+greatest common ancestor (GCA) of the branch and the destination revision (in
+the simple case below the GCA is the point where the branch forked) and the
+newest revision on that branch into your working copy.
+
address@hidden Join
+The @samp{-j} stands for ``join''.
+
address@hidden Branch merge example
address@hidden Example, branch merge
address@hidden Merge, branch example
+Consider this revision tree:
+
address@hidden
++-----+ +-----+ +-----+ +-----+
+! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 ! <- The main trunk
++-----+ +-----+ +-----+ +-----+
+ !
+ !
+ ! +---------+ +---------+
+Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
+ +---------+ +---------+
address@hidden example
+
address@hidden
+The branch 1.2.2 has been given the tag (symbolic name) @samp{R1fix}. The
+following example assumes that the module @samp{mod} contains only one
+file, @file{m.c}.
+
address@hidden
+$ cvs checkout mod # @r{Retrieve the latest revision, 1.4}
+
+$ cvs update -j R1fix m.c # @r{Merge all changes made on the branch,}
+ # @r{i.e. the changes between revision 1.2}
+ # @r{and 1.2.2.2, into your working copy}
+ # @r{of the file.}
+
+$ cvs commit -m "Included R1fix" # @r{Create revision 1.5.}
address@hidden example
+
+A conflict can result from a merge operation. If that
+happens, you should resolve it before committing the
+new revision. @xref{Conflicts example}.
+
+If your source files contain keywords (@pxref{Keyword substitution}),
+you might be getting more conflicts than strictly necessary. See
address@hidden and keywords}, for information on how to avoid this.
+
+The @code{checkout} command also supports the @samp{-j @var{branchname}} flag.
The
+same effect as above could be achieved with this:
+
address@hidden
+$ cvs checkout -j R1fix mod
+$ cvs commit -m "Included R1fix"
address@hidden example
+
+It should be noted that @code{update -j @var{tagname}} will also work but may
+not produce the desired result. @xref{Merging adds and removals}, for more.
+
address@hidden Merging more than once
address@hidden Merging from a branch several times
+
+Continuing our example, the revision tree now looks
+like this:
+
address@hidden
++-----+ +-----+ +-----+ +-----+ +-----+
+! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
++-----+ +-----+ +-----+ +-----+ +-----+
+ ! *
+ ! *
+ ! +---------+ +---------+
+Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
+ +---------+ +---------+
address@hidden example
+
address@hidden
+where the starred line represents the merge from the
address@hidden branch to the main trunk, as just
+discussed.
+
+Now suppose that development continues on the
address@hidden branch:
+
address@hidden
++-----+ +-----+ +-----+ +-----+ +-----+
+! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
++-----+ +-----+ +-----+ +-----+ +-----+
+ ! *
+ ! *
+ ! +---------+ +---------+ +---------+
+Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
+ +---------+ +---------+ +---------+
address@hidden example
+
address@hidden
+and then you want to merge those new changes onto the
+main trunk. If you just use the @code{cvs update -j
+R1fix m.c} command again, @sc{cvs} will attempt to
+merge again the changes which you have already merged,
+which can have undesirable side effects.
+
+So instead you need to specify that you only want to
+merge the changes on the branch which have not yet been
+merged into the trunk. To do that you specify two
address@hidden options, and @sc{cvs} merges the changes from
+the first revision to the second revision. For
+example, in this case the simplest way would be
+
address@hidden
+cvs update -j 1.2.2.2 -j R1fix m.c # @r{Merge changes from 1.2.2.2 to the}
+ # @r{head of the R1fix branch}
address@hidden example
+
+The problem with this is that you need to specify the
+1.2.2.2 revision manually. A slightly better approach
+might be to use the date the last merge was done:
+
address@hidden
+cvs update -j R1fix:yesterday -j R1fix m.c
address@hidden example
+
+Better yet, tag the R1fix branch after every merge into
+the trunk, and then use that tag for subsequent merges:
+
address@hidden
+cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Merging two revisions
address@hidden Merging differences between any two revisions
address@hidden Merging two revisions
address@hidden Revisions, merging differences between
address@hidden Differences, merging
+
+With two @samp{-j @var{revision}} flags, the @code{update}
+(and @code{checkout}) command can merge the differences
+between any two revisions into your working file.
+
address@hidden Undoing a change
address@hidden Removing a change
address@hidden
+$ cvs update -j 1.5 -j 1.3 backend.c
address@hidden example
+
address@hidden
+will undo all changes made between revision
+1.3 and 1.5. Note the order of the revisions!
+
+If you try to use this option when operating on
+multiple files, remember that the numeric revisions will
+probably be very different between the various files.
+You almost always use symbolic
+tags rather than revision numbers when operating on
+multiple files.
+
address@hidden Restoring old version of removed file
address@hidden Resurrecting old version of dead file
+Specifying two @samp{-j} options can also undo file
+removals or additions. For example, suppose you have
+a file
+named @file{file1} which existed as revision 1.1, and
+you then removed it (thus adding a dead revision 1.2).
+Now suppose you want to add it again, with the same
+contents it had previously. Here is how to do it:
+
address@hidden
+$ cvs update -j 1.2 -j 1.1 file1
+U file1
+$ cvs commit -m test
+Checking in file1;
+/tmp/cvs-sanity/cvsroot/first-dir/file1,v <-- file1
+new revision: 1.3; previous revision: 1.2
+done
+$
address@hidden example
+
address@hidden Merging adds and removals
address@hidden Merging can add or remove files
+
+If the changes which you are merging involve removing
+or adding some files, @code{update -j} will reflect
+such additions or removals.
+
address@hidden FIXME: This example needs a lot more explanation.
address@hidden We also need other examples for some of the other
address@hidden cases (not all--there are too many--as long as we present a
address@hidden coherent general principle).
+For example:
address@hidden
+cvs update -A
+touch a b c
+cvs add a b c ; cvs ci -m "added" a b c
+cvs tag -b branchtag
+cvs update -r branchtag
+touch d ; cvs add d
+rm a ; cvs rm a
+cvs ci -m "added d, removed a"
+cvs update -A
+cvs update -jbranchtag
address@hidden example
+
+After these commands are executed and a @samp{cvs commit} is done,
+file @file{a} will be removed and file @file{d} added in the main branch.
address@hidden (which was determined by trying it)
+
+Note that using a single static tag (@samp{-j @var{tagname}})
+rather than a dynamic tag (@samp{-j @var{branchname}}) to merge
+changes from a branch will usually not remove files which were removed on the
+branch since @sc{cvs} does not automatically add static tags to dead revisions.
+The exception to this rule occurs when
+a static tag has been attached to a dead revision manually. Use the branch tag
+to merge all changes from the branch or use two static tags as merge endpoints
+to be sure that all intended changes are propagated in the merge.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Merging and keywords
address@hidden Merging and keywords
address@hidden Merging, and keyword substitution
address@hidden Keyword substitution, and merging
address@hidden -j (merging branches), and keyword substitution
address@hidden -kk, to avoid conflicts during a merge
+
+If you merge files containing keywords (@pxref{Keyword
+substitution}), you will normally get numerous
+conflicts during the merge, because the keywords are
+expanded differently in the revisions which you are
+merging.
+
+Therefore, you will often want to specify the
address@hidden (@pxref{Substitution modes}) switch to the
+merge command line. By substituting just the name of
+the keyword, not the expanded value of that keyword,
+this option ensures that the revisions which you are
+merging will be the same as each other, and avoid
+spurious conflicts.
+
+For example, suppose you have a file like this:
+
address@hidden
+ +---------+
+ _! 1.1.2.1 ! <- br1
+ / +---------+
+ /
+ /
++-----+ +-----+
+! 1.1 !----! 1.2 !
++-----+ +-----+
address@hidden example
+
address@hidden
+and your working directory is currently on the trunk
+(revision 1.2). Then you might get the following
+results from a merge:
+
address@hidden
+$ cat file1
+key $ Revision: 1.2 $
+. . .
+$ cvs update -j br1
+U file1
+RCS file: /cvsroot/first-dir/file1,v
+retrieving revision 1.1
+retrieving revision 1.1.2.1
+Merging differences between 1.1 and 1.1.2.1 into file1
+rcsmerge: warning: conflicts during merge
+$ cat file1
address@hidden<<<<<<< file1
+key $ Revision: 1.2 $
address@hidden
+key $ Revision: 1.1.2.1 $
address@hidden>>>>>>> 1.1.2.1
+. . .
address@hidden example
+
+What happened was that the merge tried to merge the
+differences between 1.1 and 1.1.2.1 into your working
+directory. So, since the keyword changed from
address@hidden: 1.1} to @code{Revision: 1.1.2.1},
address@hidden tried to merge that change into your working
+directory, which conflicted with the fact that your
+working directory had contained @code{Revision: 1.2}.
+
+Here is what happens if you had used @samp{-kk}:
+
address@hidden
+$ cat file1
+key $ Revision: 1.2 $
+. . .
+$ cvs update -kk -j br1
+U file1
+RCS file: /cvsroot/first-dir/file1,v
+retrieving revision 1.1
+retrieving revision 1.1.2.1
+Merging differences between 1.1 and 1.1.2.1 into file1
+$ cat file1
+key $ Revision$
+. . .
address@hidden example
+
+What is going on here is that revision 1.1 and 1.1.2.1
+both expand as plain @code{Revision}, and therefore
+merging the changes between them into the working
+directory need not change anything. Therefore, there
+is no conflict.
+
address@hidden: In versions of @sc{cvs} prior to 1.12.2, there was a
+major problem with using @samp{-kk} on merges. Namely, @samp{-kk}
+overrode any default keyword expansion mode set in the archive file in
+the repository. This could, unfortunately for some users, cause data
+corruption in binary files (with a default keyword expansion mode set
+to @samp{-kb}). Therefore, when a repository contained binary files,
+conflicts had to be dealt with manually rather than using @samp{-kk} in
+a merge command.}
+
+In @sc{cvs} version 1.12.2 and later, the keyword expansion mode
+provided on the command line to any @sc{cvs} command no longer
+overrides the @samp{-kb} keyword expansion mode setting for binary
+files, though it will still override other default keyword expansion
+modes. You can now safely merge using @samp{-kk} to avoid spurious conflicts
+on lines containing RCS keywords, even when your repository contains
+binary files.
+
address@hidden
---------------------------------------------------------------------
address@hidden Recursive behavior
address@hidden Recursive behavior
address@hidden Recursive (directory descending)
address@hidden Directory, descending
address@hidden Descending directories
address@hidden Subdirectories
+
+Almost all of the subcommands of @sc{cvs} work
+recursively when you specify a directory as an
+argument. For instance, consider this directory
+structure:
+
address@hidden
+ @code{$HOME}
+ |
+ address@hidden
+ | |
+ address@hidden
+ | (internal @sc{cvs} files)
+ address@hidden
+ address@hidden
+ address@hidden
+ address@hidden
+ address@hidden
+ address@hidden
+ | |
+ | address@hidden
+ | | (internal @sc{cvs} files)
+ | address@hidden
+ |
+ address@hidden
+ |
+ address@hidden
+ | (internal @sc{cvs} files)
+ address@hidden
+ address@hidden
address@hidden example
+
address@hidden
+If @file{tc} is the current working directory, the
+following is true:
+
address@hidden @bullet
address@hidden
address@hidden update testing} is equivalent to
+
address@hidden
+cvs update testing/testpgm.t testing/test2.t
address@hidden example
+
address@hidden
address@hidden update testing man} updates all files in the
+subdirectories
+
address@hidden
address@hidden update .} or just @samp{cvs update} updates
+all files in the @code{tc} directory
address@hidden itemize
+
+If no arguments are given to @code{update} it will
+update all files in the current working directory and
+all its subdirectories. In other words, @file{.} is a
+default argument to @code{update}. This is also true
+for most of the @sc{cvs} subcommands, not only the
address@hidden command.
+
+The recursive behavior of the @sc{cvs} subcommands can be
+turned off with the @samp{-l} option.
+Conversely, the @samp{-R} option can be used to force recursion if
address@hidden is specified in @file{~/.cvsrc} (@pxref{~/.cvsrc}).
+
address@hidden
+$ cvs update -l # @r{Don't update files in subdirectories}
address@hidden example
+
address@hidden
---------------------------------------------------------------------
address@hidden Adding and removing
address@hidden Adding, removing, and renaming files and directories
+
+In the course of a project, one will often add new
+files. Likewise with removing or renaming, or with
+directories. The general concept to keep in mind in
+all these cases is that instead of making an
+irreversible change you want @sc{cvs} to record the
+fact that a change has taken place, just as with
+modifying an existing file. The exact mechanisms to do
+this in @sc{cvs} vary depending on the situation.
+
address@hidden
+* Adding files:: Adding files
+* Removing files:: Removing files
+* Removing directories:: Removing directories
+* Moving files:: Moving and renaming files
+* Moving directories:: Moving and renaming directories
address@hidden menu
+
address@hidden Adding files
address@hidden Adding files to a directory
address@hidden Adding files
+
+To add a new file to a directory, follow these steps.
+
address@hidden @bullet
address@hidden
+You must have a working copy of the directory.
address@hidden the source}.
+
address@hidden
+Create the new file inside your working copy of the directory.
+
address@hidden
+Use @samp{cvs add @var{filename}} to tell @sc{cvs} that you
+want to version control the file. If the file contains
+binary data, specify @samp{-kb} (@pxref{Binary files}).
+
address@hidden
+Use @samp{cvs commit @var{filename}} to actually check
+in the file into the repository. Other developers
+cannot see the file until you perform this step.
address@hidden itemize
+
+You can also use the @code{add} command to add a new
+directory.
address@hidden FIXCVS and/or FIXME: Adding a directory doesn't
address@hidden require the commit step. This probably can be
address@hidden considered a CVS bug, but it is possible we should
address@hidden warn people since this behavior probably won't be
address@hidden changing right away.
+
+Unlike most other commands, the @code{add} command is
+not recursive. You cannot even type @samp{cvs add
+foo/bar}! Instead, you have to
address@hidden FIXCVS: This is, of course, not a feature. It is
address@hidden just that no one has gotten around to fixing "cvs add
address@hidden foo/bar".
+
address@hidden
+$ cd foo
+$ cvs add bar
address@hidden example
+
address@hidden add (subcommand)
address@hidden Command {cvs add} address@hidden kflag] address@hidden message]
files @dots{}
+
+Schedule @var{files} to be added to the repository.
+The files or directories specified with @code{add} must
+already exist in the current directory. To add a whole
+new directory hierarchy to the source repository (for
+example, files received from a third-party vendor), use
+the @code{import} command instead. @xref{import}.
+
+The added files are not placed in the source repository
+until you use @code{commit} to make the change
+permanent. Doing an @code{add} on a file that was
+removed with the @code{remove} command will undo the
+effect of the @code{remove}, unless a @code{commit}
+command intervened. @xref{Removing files}, for an
+example.
+
+The @samp{-k} option specifies the default way that
+this file will be checked out; for more information see
address@hidden modes}.
+
address@hidden As noted in BUGS, -m is broken client/server (Nov
address@hidden 96). Also see testsuite log2-* tests.
+The @samp{-m} option specifies a description for the
+file. This description appears in the history log (if
+it is enabled, @pxref{history file}). It will also be
+saved in the version history inside the repository when
+the file is committed. The @code{log} command displays
+this description. The description can be changed using
address@hidden -t}. @xref{admin}. If you omit the
address@hidden @var{description}} flag, an empty string will
+be used. You will not be prompted for a description.
address@hidden deffn
+
+For example, the following commands add the file
address@hidden to the repository:
+
address@hidden This example used to specify
address@hidden -m "Optimizer and code generation passes."
address@hidden to the cvs add command, but that doesn't work
address@hidden client/server (see log2 in sanity.sh). Should fix CVS,
address@hidden but also seems strange to document things which
address@hidden don't work...
address@hidden
+$ cvs add backend.c
+$ cvs commit -m "Early version. Not yet compilable." backend.c
address@hidden example
+
+When you add a file it is added only on the branch
+which you are working on (@pxref{Branching and merging}). You can
+later merge the additions to another branch if you want
+(@pxref{Merging adds and removals}).
address@hidden Should we mention that earlier versions of CVS
address@hidden lacked this feature (1.3) or implemented it in a buggy
address@hidden way (well, 1.8 had many bugs in cvs update -j)?
address@hidden Should we mention the bug/limitation regarding a
address@hidden file being a regular file on one branch and a directory
address@hidden on another?
address@hidden FIXME: This needs an example, or several, here or
address@hidden elsewhere, for it to make much sense.
address@hidden Somewhere we need to discuss the aspects of death
address@hidden support which don't involve branching, I guess.
address@hidden Like the ability to re-create a release from a tag.
+
address@hidden
---------------------------------------------------------------------
address@hidden Removing files
address@hidden Removing files
address@hidden Removing files
address@hidden Deleting files
+
address@hidden FIXME: this node wants to be split into several
address@hidden smaller nodes. Could make these children of
address@hidden "Adding and removing", probably (death support could
address@hidden be its own section, for example, as could the
address@hidden various bits about undoing mistakes in adding and
address@hidden removing).
+Directories change. New files are added, and old files
+disappear. Still, you want to be able to retrieve an
+exact copy of old releases.
+
+Here is what you can do to remove a file,
+but remain able to retrieve old revisions:
+
address@hidden @bullet
address@hidden FIXME: should probably be saying something about
address@hidden having a working directory in the first place.
address@hidden
+Make sure that you have not made any uncommitted
+modifications to the file. @xref{Viewing differences},
+for one way to do that. You can also use the
address@hidden or @code{update} command. If you remove
+the file without committing your changes, you will of
+course not be able to retrieve the file as it was
+immediately before you deleted it.
+
address@hidden
+Remove the file from your working copy of the directory.
+You can for instance use @code{rm}.
+
address@hidden
+Use @samp{cvs remove @var{filename}} to tell @sc{cvs} that
+you really want to delete the file.
+
address@hidden
+Use @samp{cvs commit @var{filename}} to actually
+perform the removal of the file from the repository.
address@hidden itemize
+
address@hidden FIXME: Somehow this should be linked in with a more
address@hidden general discussion of death support. I don't know
address@hidden whether we want to use the term "death support" or
address@hidden not (we can perhaps get by without it), but we do
address@hidden need to discuss the "dead" state in "cvs log" and
address@hidden related subjects. The current discussion is
address@hidden scattered around, and not xref'd to each other.
address@hidden FIXME: I think this paragraph wants to be moved
address@hidden later down, at least after the first example.
+When you commit the removal of the file, @sc{cvs}
+records the fact that the file no longer exists. It is
+possible for a file to exist on only some branches and
+not on others, or to re-add another file with the same
+name later. @sc{cvs} will correctly create or not create
+the file, based on the @samp{-r} and @samp{-D} options
+specified to @code{checkout} or @code{update}.
+
address@hidden FIXME: This style seems to clash with how we
address@hidden document things in general.
address@hidden Remove (subcommand)
address@hidden Command {cvs remove} [options] files @dots{}
+
+Schedule file(s) to be removed from the repository
+(files which have not already been removed from the
+working directory are not processed). This command
+does not actually remove the file from the repository
+until you commit the removal. For a full list of
+options, see @ref{Invoking CVS}.
address@hidden deffn
+
+Here is an example of removing several files:
+
address@hidden
+$ cd test
+$ rm *.c
+$ cvs remove
+cvs remove: Removing .
+cvs remove: scheduling a.c for removal
+cvs remove: scheduling b.c for removal
+cvs remove: use 'cvs commit' to remove these files permanently
+$ cvs ci -m "Removed unneeded files"
+cvs commit: Examining .
+cvs commit: Committing .
address@hidden example
+
+As a convenience you can remove the file and @code{cvs
+remove} it in one step, by specifying the @samp{-f}
+option. For example, the above example could also be
+done like this:
+
address@hidden
+$ cd test
+$ cvs remove -f *.c
+cvs remove: scheduling a.c for removal
+cvs remove: scheduling b.c for removal
+cvs remove: use 'cvs commit' to remove these files permanently
+$ cvs ci -m "Removed unneeded files"
+cvs commit: Examining .
+cvs commit: Committing .
address@hidden example
+
+If you execute @code{remove} for a file, and then
+change your mind before you commit, you can undo the
address@hidden with an @code{add} command.
+
address@hidden FIXME: what if you change your mind after you commit
address@hidden it? (answer is also "cvs add" but we don't say that...).
address@hidden We need some index entries for thinks like "undoing
address@hidden removal" too.
+
address@hidden
+$ ls
+CVS ja.h oj.c
+$ rm oj.c
+$ cvs remove oj.c
+cvs remove: scheduling oj.c for removal
+cvs remove: use 'cvs commit' to remove this file permanently
+$ cvs add oj.c
+U oj.c
+cvs add: oj.c, version 1.1.1.1, resurrected
address@hidden example
+
+If you realize your mistake before you run the
address@hidden command you can use @code{update} to
+resurrect the file:
+
address@hidden
+$ rm oj.c
+$ cvs update oj.c
+cvs update: warning: oj.c was lost
+U oj.c
address@hidden example
+
+When you remove a file it is removed only on the branch
+which you are working on (@pxref{Branching and merging}). You can
+later merge the removals to another branch if you want
+(@pxref{Merging adds and removals}).
+
address@hidden Removing directories
address@hidden Removing directories
address@hidden Removing directories
address@hidden Directories, removing
+
+In concept removing directories is somewhat similar to
+removing files---you want the directory to not exist in
+your current working directories, but you also want to
+be able to retrieve old releases in which the directory
+existed.
+
+The way that you remove a directory is to remove all
+the files in it. You don't remove the directory
+itself; there is no way to do that.
+Instead you specify the @samp{-P} option to
address@hidden update} or @code{cvs checkout},
+which will cause @sc{cvs} to remove empty
+directories from working directories.
+(Note that @code{cvs export} always removes empty directories.)
+Probably the
+best way to do this is to always specify @samp{-P}; if
+you want an empty directory then put a dummy file (for
+example @file{.keepme}) in it to prevent @samp{-P} from
+removing it.
+
address@hidden I'd try to give a rationale for this, but I'm not
address@hidden sure there is a particularly convincing one. What
address@hidden we would _like_ is for CVS to do a better job of version
address@hidden controlling whether directories exist, to eliminate the
address@hidden need for -P and so that a file can be a directory in
address@hidden one revision and a regular file in another.
+Note that @samp{-P} is implied by the @samp{-r} or @samp{-D}
+options of @code{checkout}. This way
address@hidden will be able to correctly create the directory
+or not depending on whether the particular version you
+are checking out contains any files in that directory.
+
address@hidden
---------------------------------------------------------------------
address@hidden Moving files
address@hidden Moving and renaming files
address@hidden Moving files
address@hidden Renaming files
address@hidden Files, moving
+
+Moving files to a different directory or renaming them
+is not difficult, but some of the ways in which this
+works may be non-obvious. (Moving or renaming a
+directory is even harder. @xref{Moving directories}.).
+
+The examples below assume that the file @var{old} is renamed to
address@hidden
+
address@hidden
+* Outside:: The normal way to Rename
+* Inside:: A tricky, alternative way
+* Rename by copying:: Another tricky, alternative way
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Outside
address@hidden The Normal way to Rename
+
address@hidden More rename issues. Not sure whether these are
address@hidden worth documenting; I'm putting them here because
address@hidden it seems to be as good a place as any to try to
address@hidden set down the issues.
address@hidden * "cvs annotate" will annotate either the new
address@hidden file or the old file; it cannot annotate _each
address@hidden line_ based on whether it was last changed in the
address@hidden new or old file. Unlike "cvs log", where the
address@hidden consequences of having to select either the new
address@hidden or old name seem fairly benign, this may be a
address@hidden real advantage to having CVS know about renames
address@hidden other than as a deletion and an addition.
+
+The normal way to move a file is to copy @var{old} to
address@hidden, and then issue the normal @sc{cvs} commands
+to remove @var{old} from the repository, and add
address@hidden to it.
address@hidden The following sentence is not true: one must cd into
address@hidden the directory to run "cvs add".
address@hidden (Both @var{old} and @var{new} could
address@hidden contain relative paths, for example @file{foo/bar.c}).
+
address@hidden
+$ mv @var{old} @var{new}
+$ cvs remove @var{old}
+$ cvs add @var{new}
+$ cvs commit -m "Renamed @var{old} to @var{new}" @var{old} @var{new}
address@hidden example
+
+This is the simplest way to move a file, it is not
+error-prone, and it preserves the history of what was
+done. Note that to access the history of the file you
+must specify the old or the new name, depending on what
+portion of the history you are accessing. For example,
address@hidden log @var{old}} will give the log up until the
+time of the rename.
+
+When @var{new} is committed its revision numbers will
+start again, usually at 1.1, so if that bothers you,
+use the @samp{-r rev} option to commit. For more
+information see @ref{Assigning revisions}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Inside
address@hidden Moving the history file
+
+This method is more dangerous, since it involves moving
+files inside the repository. Read this entire section
+before trying it out!
+
address@hidden
+$ cd $CVSROOT/@var{dir}
+$ mv @var{old},v @var{new},v
address@hidden example
+
address@hidden
+Advantages:
+
address@hidden @bullet
address@hidden
+The log of changes is maintained intact.
+
address@hidden
+The revision numbers are not affected.
address@hidden itemize
+
address@hidden
+Disadvantages:
+
address@hidden @bullet
address@hidden
+Old releases cannot easily be fetched from the
+repository. (The file will show up as @var{new} even
+in revisions from the time before it was renamed).
+
address@hidden
+There is no log information of when the file was renamed.
+
address@hidden
+Nasty things might happen if someone accesses the history file
+while you are moving it. Make sure no one else runs any of the @sc{cvs}
+commands while you move it.
address@hidden itemize
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Rename by copying
address@hidden Copying the history file
+
+This way also involves direct modifications to the
+repository. It is safe, but not without drawbacks.
+
address@hidden
+# @r{Copy the @sc{rcs} file inside the repository}
+$ cd $CVSROOT/@var{dir}
+$ cp @var{old},v @var{new},v
+# @r{Remove the old file}
+$ cd ~/@var{dir}
+$ rm @var{old}
+$ cvs remove @var{old}
+$ cvs commit @var{old}
+# @r{Remove all tags from @var{new}}
+$ cvs update @var{new}
+$ cvs log @var{new} # @r{Remember the non-branch tag names}
+$ cvs tag -d @var{tag1} @var{new}
+$ cvs tag -d @var{tag2} @var{new}
address@hidden
address@hidden example
+
+By removing the tags you will be able to check out old
+revisions.
+
address@hidden
+Advantages:
+
address@hidden @bullet
address@hidden
address@hidden FIXME: Is this true about -D now that we have death
address@hidden support? See 5B.3 in the FAQ.
+Checking out old revisions works correctly, as long as
+you use @address@hidden and not @address@hidden
+to retrieve the revisions.
+
address@hidden
+The log of changes is maintained intact.
+
address@hidden
+The revision numbers are not affected.
address@hidden itemize
+
address@hidden
+Disadvantages:
+
address@hidden @bullet
address@hidden
+You cannot easily see the history of the file across the rename.
+
address@hidden itemize
+
address@hidden
---------------------------------------------------------------------
address@hidden Moving directories
address@hidden Moving and renaming directories
address@hidden Moving directories
address@hidden Renaming directories
address@hidden Directories, moving
+
+The normal way to rename or move a directory is to
+rename or move each file within it as described in
address@hidden Then check out with the @samp{-P}
+option, as described in @ref{Removing directories}.
+
+If you really want to hack the repository to rename or
+delete a directory in the repository, you can do it
+like this:
+
address@hidden
address@hidden
+Inform everyone who has a checked out copy of the directory that the
+directory will be renamed. They should commit all
+their changes, and remove their working copies,
+before you take the steps below.
+
address@hidden
+Rename the directory inside the repository.
+
address@hidden
+$ cd $CVSROOT/@var{parent-dir}
+$ mv @var{old-dir} @var{new-dir}
address@hidden example
+
address@hidden
+Fix the @sc{cvs} administrative files, if necessary (for
+instance if you renamed an entire module).
+
address@hidden
+Tell everyone that they can check out again and continue
+working.
+
address@hidden enumerate
+
+If someone had a working copy the @sc{cvs} commands will
+cease to work for him, until he removes the directory
+that disappeared inside the repository.
+
+It is almost always better to move the files in the
+directory instead of moving the directory. If you move the
+directory you are unlikely to be able to retrieve old
+releases correctly, since they probably depend on the
+name of the directories.
+
address@hidden
---------------------------------------------------------------------
address@hidden History browsing
address@hidden History browsing
address@hidden History browsing
address@hidden Traceability
address@hidden Isolation
+
+
address@hidden kind of lame, in a lot of ways the above text inside
address@hidden the @ignore motivates this chapter better
+Once you have used @sc{cvs} to store a version control
+history---what files have changed when, how, and by
+whom, there are a variety of mechanisms for looking
+through the history.
+
address@hidden FIXME: should also be talking about how you look at
address@hidden old revisions (e.g. "cvs update -p -r 1.2 foo.c").
address@hidden
+* log messages:: Log messages
+* history database:: The history database
+* user-defined logging:: User-defined logging
+* annotate:: What revision modified each line of a file?
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden log messages
address@hidden Log messages
+
address@hidden FIXME: @xref to place where we talk about how to
address@hidden specify message to commit.
+Whenever you commit a file you specify a log message.
+
address@hidden FIXME: bring the information here, and get rid of or
address@hidden greatly shrink the "log" node.
+To look through the log messages which have been
+specified for every revision which has been committed,
+use the @code{cvs log} command (@pxref{log}).
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden history database
address@hidden The history database
+
address@hidden FIXME: bring the information from the history file
address@hidden and history nodes here. Rewrite it to be motivated
address@hidden better (start out by clearly explaining what gets
address@hidden logged in history, for example).
+You can use the history file (@pxref{history file}) to
+log various @sc{cvs} actions. To retrieve the
+information from the history file, use the @code{cvs
+history} command (@pxref{history}).
+
+Note: you can control what is logged to this file by using the
address@hidden keyword in the @file{CVSROOT/config} file
+(@pxref{config}).
+
address@hidden
address@hidden The history database has many problems:
address@hidden * It is very unclear what field means what. This
address@hidden could be improved greatly by better documentation,
address@hidden but there are still non-orthogonalities (for
address@hidden example, tag does not record the "repository"
address@hidden field but most records do).
address@hidden * Confusion about files, directories, and modules.
address@hidden Some commands record one, some record others.
address@hidden * File removal is not logged. There is an 'R'
address@hidden record type documented, but CVS never uses it.
address@hidden * Tags are only logged for the "cvs rtag" command,
address@hidden not "cvs tag". The fix for this is not completely
address@hidden clear (see above about modules vs. files).
address@hidden * Are there other cases of operations that are not
address@hidden logged? One would hope for all changes to the
address@hidden repository to be logged somehow (particularly
address@hidden operations like tagging, "cvs admin -k", and other
address@hidden operations which do not record a history that one
address@hidden can get with "cvs log"). Operations on the working
address@hidden directory, like export, get, and release, are a
address@hidden second category also covered by the current "cvs
address@hidden history".
address@hidden * The history file does not record the options given
address@hidden to a command. The most serious manifestation of
address@hidden this is perhaps that it doesn't record whether a command
address@hidden was recursive. It is not clear to me whether one
address@hidden wants to log at a level very close to the command
address@hidden line, as a sort of way of logging each command
address@hidden (more or less), or whether one wants
address@hidden to log more at the level of what was changed (or
address@hidden something in between), but either way the current
address@hidden information has pretty big gaps.
address@hidden * Further details about a tag--like whether it is a
address@hidden branch tag or, if a non-branch tag, which branch it
address@hidden is on. One can find out this information about the
address@hidden tag as it exists _now_, but if the tag has been
address@hidden moved, one doesn't know what it was like at the time
address@hidden the history record was written.
address@hidden * Whether operating on a particular tag, date, or
address@hidden options was implicit (sticky) or explicit.
address@hidden
address@hidden Another item, only somewhat related to the above, is a
address@hidden way to control what is logged in the history file.
address@hidden This is probably the only good way to handle
address@hidden different people having different ideas about
address@hidden information/space tradeoffs.
address@hidden
address@hidden It isn't really clear that it makes sense to try to
address@hidden patch up the history file format as it exists now to
address@hidden include all that stuff. It might be better to
address@hidden design a whole new CVSROOT/nhistory file and "cvs
address@hidden nhistory" command, or some such, or in some other
address@hidden way trying to come up with a clean break from the
address@hidden past, which can address the above concerns. Another
address@hidden open question is how/whether this relates to
address@hidden taginfo/loginfo/etc.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden user-defined logging
address@hidden User-defined logging
+
address@hidden FIXME: should probably also mention the fact the -l
address@hidden global option can disable most of the mechanisms
address@hidden discussed here (why? What is the -l global option for?).
address@hidden
address@hidden FIXME: probably should centralize this information
address@hidden here, at least to some extent. Maybe by moving the
address@hidden loginfo, etc., nodes here and replacing
address@hidden the "user-defined logging" node with one node for
address@hidden each method.
+You can customize @sc{cvs} to log various kinds of
+actions, in whatever manner you choose. These
+mechanisms operate by executing a script at various
+times. The script might append a message to a file
+listing the information and the programmer who created
+it, or send mail to a group of developers, or, perhaps,
+post a message to a particular newsgroup. To log
+commits, use the @file{loginfo} file (@pxref{loginfo}).
address@hidden FIXME: What is difference between doing it in the
address@hidden modules file and using loginfo/taginfo? Why should
address@hidden user use one or the other?
+To log commits, checkouts, exports, and tags,
+respectively, you can also use the @samp{-i},
address@hidden, @samp{-e}, and @samp{-t} options in the
+modules file. For a more flexible way of giving
+notifications to various users, which requires less in
+the way of keeping centralized scripts up to date, use
+the @code{cvs watch add} command (@pxref{Getting
+Notified}); this command is useful even if you are not
+using @code{cvs watch on}.
+
address@hidden taginfo
address@hidden Exit status, of taginfo
+The @file{taginfo} file defines programs to execute
+when someone executes a @code{tag} or @code{rtag}
+command. The @file{taginfo} file has the standard form
+for administrative files (@pxref{Administrative
+files}), where each line is a regular expression
+followed by a command to execute. The arguments passed
+to the command are, in order, the @var{tagname},
address@hidden (@code{add} for @code{tag},
address@hidden for @code{tag -F}, and @code{del} for
address@hidden -d}), @var{repository}, and any remaining are
+pairs of @var{filename} @var{revision}. A non-zero
+exit of the filter program will cause the tag to be
+aborted.
+
+Here is an example of using taginfo to log tag and rtag
+commands. In the taginfo file put:
+
address@hidden
+ALL /usr/local/cvsroot/CVSROOT/loggit
address@hidden example
+
address@hidden
+Where @file{/usr/local/cvsroot/CVSROOT/loggit} contains the
+following script:
+
address@hidden
+#!/bin/sh
+echo "$@@" >>/home/kingdon/cvsroot/CVSROOT/taglog
address@hidden example
+
address@hidden annotate
address@hidden Annotate command
address@hidden annotate (subcommand)
+
address@hidden Command {cvs annotate} address@hidden address@hidden
rev}|@code{-D date}] files @dots{}
+
+For each file in @var{files}, print the head revision
+of the trunk, together with information on the last
+modification for each line. For example:
+
address@hidden
+$ cvs annotate ssfile
+Annotations for ssfile
+***************
+1.1 (mary 27-Mar-96): ssfile line 1
+1.2 (joe 28-Mar-96): ssfile line 2
address@hidden example
+
+The file @file{ssfile} currently contains two lines.
+The @code{ssfile line 1} line was checked in by
address@hidden on March 27. Then, on March 28, @code{joe}
+added a line @code{ssfile line 2}, without modifying
+the @code{ssfile line 1} line. This report doesn't
+tell you anything about lines which have been deleted
+or replaced; you need to use @code{cvs diff} for that
+(@pxref{diff}).
+
address@hidden deffn
+
+The options to @code{cvs annotate} are listed in
address@hidden CVS}, and can be used to select the files
+and revisions to annotate. The options are described
+in more detail there and in @ref{Common options}.
+
address@hidden FIXME: maybe an example using the options? Just
address@hidden what it means to select a revision might be worth a
address@hidden few words of explanation ("you want to see who
address@hidden changed this line *before* 1.4"...).
+
address@hidden
---------------------------------------------------------------------
address@hidden Binary files
address@hidden Handling binary files
address@hidden Binary files
+
+The most common use for @sc{cvs} is to store text
+files. With text files, @sc{cvs} can merge revisions,
+display the differences between revisions in a
+human-visible fashion, and other such operations.
+However, if you are willing to give up a few of these
+abilities, @sc{cvs} can store binary files. For
+example, one might store a web site in @sc{cvs}
+including both text files and binary images.
+
address@hidden
+* Binary why:: More details on issues with binary files
+* Binary howto:: How to store them
address@hidden menu
+
address@hidden Binary why
address@hidden The issues with binary files
+
+While the need to manage binary files may seem obvious
+if the files that you customarily work with are binary,
+putting them into version control does present some
+additional issues.
+
+One basic function of version control is to show the
+differences between two revisions. For example, if
+someone else checked in a new version of a file, you
+may wish to look at what they changed and determine
+whether their changes are good. For text files,
address@hidden provides this functionality via the @code{cvs
+diff} command. For binary files, it may be possible to
+extract the two revisions and then compare them with a
+tool external to @sc{cvs} (for example, word processing
+software often has such a feature). If there is no
+such tool, one must track changes via other mechanisms,
+such as urging people to write good log messages, and
+hoping that the changes they actually made were the
+changes that they intended to make.
+
+Another ability of a version control system is the
+ability to merge two revisions. For @sc{cvs} this
+happens in two contexts. The first is when users make
+changes in separate working directories
+(@pxref{Multiple developers}). The second is when one
+merges explicitly with the @samp{update -j} command
+(@pxref{Branching and merging}).
+
+In the case of text
+files, @sc{cvs} can merge changes made independently,
+and signal a conflict if the changes conflict. With
+binary files, the best that @sc{cvs} can do is present
+the two different copies of the file, and leave it to
+the user to resolve the conflict. The user may choose
+one copy or the other, or may run an external merge
+tool which knows about that particular file format, if
+one exists.
+Note that having the user merge relies primarily on the
+user to not accidentally omit some changes, and thus is
+potentially error prone.
+
+If this process is thought to be undesirable, the best
+choice may be to avoid merging. To avoid the merges
+that result from separate working directories, see the
+discussion of reserved checkouts (file locking) in
address@hidden developers}. To avoid the merges
+resulting from branches, restrict use of branches.
+
address@hidden Binary howto
address@hidden How to store binary files
+
+There are two issues with using @sc{cvs} to store
+binary files. The first is that @sc{cvs} by default
+converts line endings between the canonical form in
+which they are stored in the repository (linefeed
+only), and the form appropriate to the operating system
+in use on the client (for example, carriage return
+followed by line feed for Windows NT).
+
+The second is that a binary file might happen to
+contain data which looks like a keyword (@pxref{Keyword
+substitution}), so keyword expansion must be turned
+off.
+
address@hidden FIXME: the third is that one can't do merges with
address@hidden binary files. xref to Multiple Developers and the
address@hidden reserved checkout issues.
+
+The @samp{-kb} option available with some @sc{cvs}
+commands insures that neither line ending conversion
+nor keyword expansion will be done.
+
+Here is an example of how you can create a new file
+using the @samp{-kb} flag:
+
address@hidden
+$ echo '$ Id$' > kotest
+$ cvs add -kb -m"A test file" kotest
+$ cvs ci -m"First checkin; contains a keyword" kotest
address@hidden example
+
+If a file accidentally gets added without @samp{-kb},
+one can use the @code{cvs admin} command to recover.
+For example:
+
address@hidden
+$ echo '$ Id$' > kotest
+$ cvs add -m"A test file" kotest
+$ cvs ci -m"First checkin; contains a keyword" kotest
+$ cvs admin -kb kotest
+$ cvs update -A kotest
+# @r{For non-unix systems:}
+# @r{Copy in a good copy of the file from outside CVS}
+$ cvs commit -m "make it binary" kotest
address@hidden example
+
address@hidden Trying to describe this for both unix and non-unix
address@hidden in the same description is very confusing. Might
address@hidden want to split the two, or just ditch the unix "shortcut"
address@hidden (unixheads don't do much with binary files, anyway).
address@hidden This used to say "(Try the above example, and do a
address@hidden @code{cat kotest} after every command)". But that
address@hidden only really makes sense for the unix case.
+When you check in the file @file{kotest} the file is
+not preserved as a binary file, because you did not
+check it in as a binary file. The @code{cvs
+admin -kb} command sets the default keyword
+substitution method for this file, but it does not
+alter the working copy of the file that you have. If you need to
+cope with line endings (that is, you are using
address@hidden on a non-unix system), then you need to
+check in a new copy of the file, as shown by the
address@hidden commit} command above.
+On unix, the @code{cvs update -A} command suffices.
address@hidden FIXME: should also describe what the *other users*
address@hidden need to do, if they have checked out copies which
address@hidden have been corrupted by lack of -kb. I think maybe
address@hidden "cvs update -kb" or "cvs
address@hidden update -A" would suffice, although the user who
address@hidden reported this suggested removing the file, manually
address@hidden removing it from CVS/Entries, and then "cvs update"
+(Note that you can use @code{cvs log} to determine the default keyword
+substitution method for a file and @code{cvs status} to determine
+the keyword substitution method for a working copy.)
+
+However, in using @code{cvs admin -k} to change the
+keyword expansion, be aware that the keyword expansion
+mode is not version controlled. This means that, for
+example, that if you have a text file in old releases,
+and a binary file with the same name in new releases,
address@hidden provides no way to check out the file in text
+or binary mode depending on what version you are
+checking out. There is no good workaround for this
+problem.
+
+You can also set a default for whether @code{cvs add}
+and @code{cvs import} treat a file as binary based on
+its name; for example you could say that files who
+names end in @samp{.exe} are binary. @xref{Wrappers}.
+There is currently no way to have @sc{cvs} detect
+whether a file is binary based on its contents. The
+main difficulty with designing such a feature is that
+it is not clear how to distinguish between binary and
+non-binary files, and the rules to apply would vary
+considerably with the operating system.
address@hidden For example, it would be good on MS-DOS-family OSes
address@hidden for anything containing ^Z to be binary. Having
address@hidden characters with the 8th bit set imply binary is almost
address@hidden surely a bad idea in the context of ISO-8859-* and
address@hidden other such character sets. On VMS or the Mac, we
address@hidden could use the OS's file typing. This is a
address@hidden commonly-desired feature, and something of this sort
address@hidden may make sense. But there are a lot of pitfalls here.
address@hidden
address@hidden Another, probably better, way to tell is to read the
address@hidden file in text mode, write it to a temp file in text
address@hidden mode, and then do a binary mode compare of the two
address@hidden files. If they differ, it is a binary file. This
address@hidden might have problems on VMS (or some other system
address@hidden with several different text modes), but in general
address@hidden should be relatively portable. The only other
address@hidden downside I can think of is that it would be fairly
address@hidden slow, but that is perhaps a small price to pay for
address@hidden not having your files corrupted. Another issue is
address@hidden what happens if you import a text file with bare
address@hidden linefeeds on Windows. Such files will show up on
address@hidden Windows sometimes (I think some native windows
address@hidden programs even write them, on occasion). Perhaps it
address@hidden is reasonable to treat such files as binary; after
address@hidden all it is something of a presumption to assume that
address@hidden the user would want the linefeeds converted to CRLF.
+
address@hidden
---------------------------------------------------------------------
address@hidden Multiple developers
address@hidden Multiple developers
address@hidden Multiple developers
address@hidden Team of developers
address@hidden File locking
address@hidden Locking files
address@hidden Working copy
address@hidden Reserved checkouts
address@hidden Unreserved checkouts
address@hidden RCS-style locking
+
+When more than one person works on a software project
+things often get complicated. Often, two people try to
+edit the same file simultaneously. One solution, known
+as @dfn{file locking} or @dfn{reserved checkouts}, is
+to allow only one person to edit each file at a time.
+This is the only solution with some version control
+systems, including @sc{rcs} and @sc{sccs}. Currently
+the usual way to get reserved checkouts with @sc{cvs}
+is the @code{cvs admin -l} command (@pxref{admin
+options}). This is not as nicely integrated into
address@hidden as the watch features, described below, but it
+seems that most people with a need for reserved
+checkouts find it adequate.
address@hidden Or "find it better than worrying about implementing
address@hidden nicely integrated reserved checkouts" or ...?
+It also may be possible to use the watches
+features described below, together with suitable
+procedures (not enforced by software), to avoid having
+two people edit at the same time.
+
address@hidden Our unreserved checkout model might not
address@hidden be quite the same as others. For example, I
address@hidden think that some systems will tend to create a branch
address@hidden in the case where CVS prints "up-to-date check failed".
address@hidden It isn't clear to me whether we should try to
address@hidden explore these subtleties; it could easily just
address@hidden confuse people.
+The default model with @sc{cvs} is known as
address@hidden checkouts}. In this model, developers
+can edit their own @dfn{working copy} of a file
+simultaneously. The first person that commits his
+changes has no automatic way of knowing that another
+has started to edit it. Others will get an error
+message when they try to commit the file. They must
+then use @sc{cvs} commands to bring their working copy
+up to date with the repository revision. This process
+is almost automatic.
+
address@hidden FIXME? should probably use the word "watch" here, to
address@hidden tie this into the text below and above.
address@hidden also supports mechanisms which facilitate
+various kinds of communication, without actually
+enforcing rules like reserved checkouts do.
+
+The rest of this chapter describes how these various
+models work, and some of the issues involved in
+choosing between them.
+
+
address@hidden
+* File status:: A file can be in several states
+* Updating a file:: Bringing a file up-to-date
+* Conflicts example:: An informative example
+* Informing others:: To cooperate you must inform
+* Concurrency:: Simultaneous repository access
+* Watches:: Mechanisms to track who is editing files
+* Choosing a model:: Reserved or unreserved checkouts?
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden File status
address@hidden File status
address@hidden File status
address@hidden Status of a file
+
address@hidden Shouldn't this start with an example or something,
address@hidden introducing the unreserved checkout model? Before we
address@hidden dive into listing states?
+Based on what operations you have performed on a
+checked out file, and what operations others have
+performed to that file in the repository, one can
+classify a file in a number of states. The states, as
+reported by the @code{status} command, are:
+
address@hidden The order of items is chosen to group logically
address@hidden similar outputs together.
address@hidden People who want alphabetical can use the index...
address@hidden @asis
address@hidden Up-to-date
address@hidden Up-to-date
+The file is identical with the latest revision in the
+repository for the branch in use.
address@hidden FIXME: should we clarify "in use"? The answer is
address@hidden sticky tags, and trying to distinguish branch sticky
address@hidden tags from non-branch sticky tags seems rather awkward
address@hidden here.
address@hidden FIXME: What happens with non-branch sticky tags? Is
address@hidden a stuck file "Up-to-date" or "Needs checkout" or what?
+
address@hidden Locally Modified
address@hidden Locally Modified
+You have edited the file, and not yet committed your changes.
+
address@hidden Locally Added
address@hidden Locally Added
+You have added the file with @code{add}, and not yet
+committed your changes.
address@hidden There are many cases involving the file being
address@hidden added/removed/modified in the working directory, and
address@hidden added/removed/modified in the repository, which we
address@hidden don't try to describe here. I'm not sure that "cvs
address@hidden status" produces a non-confusing output in most of
address@hidden those cases.
+
address@hidden Locally Removed
address@hidden Locally Removed
+You have removed the file with @code{remove}, and not yet
+committed your changes.
+
address@hidden Needs Checkout
address@hidden Needs Checkout
+Someone else has committed a newer revision to the
+repository. The name is slightly misleading; you will
+ordinarily use @code{update} rather than
address@hidden to get that newer revision.
+
address@hidden Needs Patch
address@hidden Needs Patch
address@hidden See also newb-123j0 in sanity.sh (although that case
address@hidden should probably be changed rather than documented).
+Like Needs Checkout, but the @sc{cvs} server will send
+a patch rather than the entire file. Sending a patch or
+sending an entire file accomplishes the same thing.
+
address@hidden Needs Merge
address@hidden Needs Merge
+Someone else has committed a newer revision to the repository, and you
+have also made modifications to the file.
+
address@hidden Unresolved Conflict
address@hidden Unresolved Conflict
address@hidden FIXCVS - This file status needs to be changed to some more
informative
address@hidden text that distinguishes it more clearly from each of the Locally
Added,
address@hidden File had conflicts on merge, and Unknown status types, but an
exact and
address@hidden succinct wording escapes me at the moment.
+A file with the same name as this new file has been added to the repository
+from a second workspace. This file will need to be moved out of the way
+to allow an @code{update} to complete.
+
address@hidden File had conflicts on merge
address@hidden File had conflicts on merge
address@hidden is it worth saying that this message was "Unresolved
address@hidden Conflict" in CVS 1.9 and earlier? I'm inclined to
address@hidden think that is unnecessarily confusing to new users.
+This is like Locally Modified, except that a previous
address@hidden command gave a conflict. If you have not
+already done so, you need to
+resolve the conflict as described in @ref{Conflicts example}.
+
address@hidden Unknown
address@hidden Unknown
address@hidden doesn't know anything about this file. For
+example, you have created a new file and have not run
address@hidden
address@hidden
address@hidden "Entry Invalid" and "Classify Error" are also in the
address@hidden status.c. The latter definitely indicates a CVS bug
address@hidden (should it be worded more like "internal error" so
address@hidden people submit bug reports if they see it?). The former
address@hidden I'm not as sure; I haven't tracked down whether/when it
address@hidden appears in "cvs status" output.
+
address@hidden table
+
+To help clarify the file status, @code{status} also
+reports the @code{Working revision} which is the
+revision that the file in the working directory derives
+from, and the @code{Repository revision} which is the
+latest revision in the repository for the branch in
+use.
address@hidden FIXME: should we clarify "in use"? The answer is
address@hidden sticky tags, and trying to distinguish branch sticky
address@hidden tags from non-branch sticky tags seems rather awkward
address@hidden here.
address@hidden FIXME: What happens with non-branch sticky tags?
address@hidden What is the Repository Revision there? See the
address@hidden comment at vn_rcs in cvs.h, which is kind of
address@hidden confused--we really need to document better what this
address@hidden field contains.
address@hidden Q: Should we document "New file!" and other such
address@hidden outputs or are they self-explanatory?
address@hidden FIXME: what about the date to the right of "Working
address@hidden revision"? It doesn't appear with client/server and
address@hidden seems unnecessary (redundant with "ls -l") so
address@hidden perhaps it should be removed for non-client/server too?
address@hidden FIXME: Need some examples.
address@hidden FIXME: Working revision can also be something like
address@hidden "-1.3" for a locally removed file. Not at all
address@hidden self-explanatory (and it is possible that CVS should
address@hidden be changed rather than documenting this).
+
address@hidden Would be nice to have an @example showing output
address@hidden from cvs status, with comments showing the xref
address@hidden where each part of the output is described. This
address@hidden might fit in nicely if it is desirable to split this
address@hidden node in two; one to introduce "cvs status" and one
address@hidden to list each of the states.
+The options to @code{status} are listed in
address@hidden CVS}. For information on its @code{Sticky tag}
+and @code{Sticky date} output, see @ref{Sticky tags}.
+For information on its @code{Sticky options} output,
+see the @samp{-k} option in @ref{update options}.
+
+You can think of the @code{status} and @code{update}
+commands as somewhat complementary. You use
address@hidden to bring your files up to date, and you
+can use @code{status} to give you some idea of what an
address@hidden would do (of course, the state of the
+repository might change before you actually run
address@hidden). In fact, if you want a command to
+display file status in a more brief format than is
+displayed by the @code{status} command, you can invoke
+
address@hidden update, to display file status
address@hidden
+$ cvs -n -q update
address@hidden example
+
+The @samp{-n} option means to not actually do the
+update, but merely to display statuses; the @samp{-q}
+option avoids printing the name of each directory. For
+more information on the @code{update} command, and
+these options, see @ref{Invoking CVS}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Updating a file
address@hidden Bringing a file up to date
address@hidden Bringing a file up to date
address@hidden Updating a file
address@hidden Merging a file
address@hidden Update, introduction
+
+When you want to update or merge a file, use the @code{update}
+command. For files that are not up to date this is roughly equivalent
+to a @code{checkout} command: the newest revision of the file is
+extracted from the repository and put in your working directory.
+
+Your modifications to a file are never lost when you
+use @code{update}. If no newer revision exists,
+running @code{update} has no effect. If you have
+edited the file, and a newer revision is available,
address@hidden will merge all changes into your working copy.
+
+For instance, imagine that you checked out revision 1.4 and started
+editing it. In the meantime someone else committed revision 1.5, and
+shortly after that revision 1.6. If you run @code{update} on the file
+now, @sc{cvs} will incorporate all changes between revision 1.4 and 1.6 into
+your file.
+
address@hidden Overlap
+If any of the changes between 1.4 and 1.6 were made too
+close to any of the changes you have made, an
address@hidden occurs. In such cases a warning is
+printed, and the resulting file includes both
+versions of the lines that overlap, delimited by
+special markers.
address@hidden, for a complete description of the
address@hidden command.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Conflicts example
address@hidden Conflicts example
address@hidden Merge, an example
address@hidden Example of merge
address@hidden driver.c (merge example)
+
+Suppose revision 1.4 of @file{driver.c} contains this:
+
address@hidden
+#include <stdio.h>
+
+void main()
address@hidden
+ parse();
+ if (nerr == 0)
+ gencode();
+ else
+ fprintf(stderr, "No code generated.\n");
+ exit(nerr == 0 ? 0 : 1);
address@hidden
address@hidden example
+
address@hidden
+Revision 1.6 of @file{driver.c} contains this:
+
address@hidden
+#include <stdio.h>
+
+int main(int argc,
+ char **argv)
address@hidden
+ parse();
+ if (argc != 1)
+ @{
+ fprintf(stderr, "tc: No args expected.\n");
+ exit(1);
+ @}
+ if (nerr == 0)
+ gencode();
+ else
+ fprintf(stderr, "No code generated.\n");
+ exit(!!nerr);
address@hidden
address@hidden example
+
address@hidden
+Your working copy of @file{driver.c}, based on revision
+1.4, contains this before you run @samp{cvs update}:
address@hidden -- Really include "cvs"?
+
address@hidden
+#include <stdlib.h>
+#include <stdio.h>
+
+void main()
address@hidden
+ init_scanner();
+ parse();
+ if (nerr == 0)
+ gencode();
+ else
+ fprintf(stderr, "No code generated.\n");
+ exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
address@hidden
address@hidden example
+
address@hidden
+You run @samp{cvs update}:
address@hidden -- Really include "cvs"?
+
address@hidden
+$ cvs update driver.c
+RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v
+retrieving revision 1.4
+retrieving revision 1.6
+Merging differences between 1.4 and 1.6 into driver.c
+rcsmerge warning: overlaps during merge
+cvs update: conflicts found in driver.c
+C driver.c
address@hidden example
+
address@hidden
address@hidden Conflicts (merge example)
address@hidden tells you that there were some conflicts.
+Your original working file is saved unmodified in
address@hidden The new version of
address@hidden contains this:
+
address@hidden
+#include <stdlib.h>
+#include <stdio.h>
+
+int main(int argc,
+ char **argv)
address@hidden
+ init_scanner();
+ parse();
+ if (argc != 1)
+ @{
+ fprintf(stderr, "tc: No args expected.\n");
+ exit(1);
+ @}
+ if (nerr == 0)
+ gencode();
+ else
+ fprintf(stderr, "No code generated.\n");
address@hidden<<<<<<< driver.c
+ exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
address@hidden
+ exit(!!nerr);
address@hidden>>>>>>> 1.6
address@hidden
address@hidden example
+
address@hidden
address@hidden Markers, conflict
address@hidden Conflict markers
address@hidden <<<<<<<
address@hidden >>>>>>>
address@hidden =======
+
+Note how all non-overlapping modifications are incorporated in your working
+copy, and that the overlapping section is clearly marked with
address@hidden<<<<<<<}, @samp{=======} and @samp{>>>>>>>}.
+
address@hidden Resolving a conflict
address@hidden Conflict resolution
+You resolve the conflict by editing the file, removing the markers and
+the erroneous line. Suppose you end up with this file:
address@hidden -- Add xref to the pcl-cvs manual when it talks
address@hidden -- about this.
address@hidden
+#include <stdlib.h>
+#include <stdio.h>
+
+int main(int argc,
+ char **argv)
address@hidden
+ init_scanner();
+ parse();
+ if (argc != 1)
+ @{
+ fprintf(stderr, "tc: No args expected.\n");
+ exit(1);
+ @}
+ if (nerr == 0)
+ gencode();
+ else
+ fprintf(stderr, "No code generated.\n");
+ exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
address@hidden
address@hidden example
+
address@hidden
+You can now go ahead and commit this as revision 1.7.
+
address@hidden
+$ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c
+Checking in driver.c;
+/usr/local/cvsroot/yoyodyne/tc/driver.c,v <-- driver.c
+new revision: 1.7; previous revision: 1.6
+done
address@hidden example
+
+For your protection, @sc{cvs} will refuse to check in a
+file if a conflict occurred and you have not resolved
+the conflict. Currently to resolve a conflict, you
+must change the timestamp on the file. In previous
+versions of @sc{cvs}, you also needed to
+insure that the file contains no conflict markers.
+Because
+your file may legitimately contain conflict markers (that
+is, occurrences of @samp{>>>>>>> } at the start of a
+line that don't mark a conflict), the current
+version of @sc{cvs} will print a warning and proceed to
+check in the file.
address@hidden The old behavior was really icky; the only way out
address@hidden was to start hacking on
address@hidden the @code{CVS/Entries} file or other such workarounds.
address@hidden
address@hidden If the timestamp thing isn't considered nice enough,
address@hidden maybe there should be a "cvs resolved" command
address@hidden which clears the conflict indication. For a nice user
address@hidden interface, this should be invoked by an interactive
address@hidden merge tool like emerge rather than by the user
address@hidden directly--such a tool can verify that the user has
address@hidden really dealt with each conflict.
+
address@hidden emerge
+If you use release 1.04 or later of pcl-cvs (a @sc{gnu}
+Emacs front-end for @sc{cvs}) you can use an Emacs
+package called emerge to help you resolve conflicts.
+See the documentation for pcl-cvs.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Informing others
address@hidden Informing others about commits
address@hidden Informing others
address@hidden Spreading information
address@hidden Mail, automatic mail on commit
+
+It is often useful to inform others when you commit a
+new revision of a file. The @samp{-i} option of the
address@hidden file, or the @file{loginfo} file, can be
+used to automate this process. @xref{modules}.
address@hidden You can use these features of @sc{cvs}
+to, for instance, instruct @sc{cvs} to mail a
+message to all developers, or post a message to a local
+newsgroup.
address@hidden -- More text would be nice here.
+
address@hidden Concurrency
address@hidden Several developers simultaneously attempting to run CVS
+
address@hidden Locks, cvs, introduction
address@hidden For a discussion of *why* CVS creates locks, see
address@hidden the comment at the start of src/lock.c
+If several developers try to run @sc{cvs} at the same
+time, one may get the following message:
+
address@hidden
+[11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo
address@hidden example
+
address@hidden #cvs.rfl, removing
address@hidden #cvs.wfl, removing
address@hidden #cvs.lock, removing
address@hidden will try again every 30 seconds, and either
+continue with the operation or print the message again,
+if it still needs to wait. If a lock seems to stick
+around for an undue amount of time, find the person
+holding the lock and ask them about the cvs command
+they are running. If they aren't running a cvs
+command, look in the repository directory mentioned in
+the message and remove files which they own whose names
+start with @file{#cvs.rfl},
address@hidden, or @file{#cvs.lock}.
+
+Note that these locks are to protect @sc{cvs}'s
+internal data structures and have no relationship to
+the word @dfn{lock} in the sense used by
address@hidden refers to reserved checkouts
+(@pxref{Multiple developers}).
+
+Any number of people can be reading from a given
+repository at a time; only when someone is writing do
+the locks prevent other people from reading or writing.
+
address@hidden Atomic transactions, lack of
address@hidden Transactions, atomic, lack of
address@hidden the following talks about what one might call commit/update
address@hidden atomicity.
address@hidden Probably also should say something about
address@hidden commit/commit atomicity, that is, "An update will
address@hidden not get partial versions of more than one commit".
address@hidden CVS currently has this property and I guess we can
address@hidden make it a documented feature.
address@hidden For example one person commits
address@hidden a/one.c and b/four.c and another commits a/two.c and
address@hidden b/three.c. Then an update cannot get the new a/one.c
address@hidden and a/two.c and the old b/four.c and b/three.c.
+One might hope for the following property:
+
address@hidden
+If someone commits some changes in one cvs command,
+then an update by someone else will either get all the
+changes, or none of them.
address@hidden quotation
+
address@hidden
+but @sc{cvs} does @emph{not} have this property. For
+example, given the files
+
address@hidden
+a/one.c
+a/two.c
+b/three.c
+b/four.c
address@hidden example
+
address@hidden
+if someone runs
+
address@hidden
+cvs ci a/two.c b/three.c
address@hidden example
+
address@hidden
+and someone else runs @code{cvs update} at the same
+time, the person running @code{update} might get only
+the change to @file{b/three.c} and not the change to
address@hidden/two.c}.
+
address@hidden Watches
address@hidden Mechanisms to track who is editing files
address@hidden Watches
+
+For many groups, use of @sc{cvs} in its default mode is
+perfectly satisfactory. Users may sometimes go to
+check in a modification only to find that another
+modification has intervened, but they deal with it and
+proceed with their check in. Other groups prefer to be
+able to know who is editing what files, so that if two
+people try to edit the same file they can choose to
+talk about who is doing what when rather than be
+surprised at check in time. The features in this
+section allow such coordination, while retaining the
+ability of two developers to edit the same file at the
+same time.
+
address@hidden Some people might ask why CVS does not enforce the
address@hidden rule on chmod, by requiring a cvs edit before a cvs
address@hidden commit. The main reason is that it could always be
address@hidden circumvented--one could edit the file, and
address@hidden then when ready to check it in, do the cvs edit and put
address@hidden in the new contents and do the cvs commit. One
address@hidden implementation note: if we _do_ want to have cvs commit
address@hidden require a cvs edit, we should store the state on
address@hidden whether the cvs edit has occurred in the working
address@hidden directory, rather than having the server try to keep
address@hidden track of what working directories exist.
address@hidden FIXME: should the above discussion be part of the
address@hidden manual proper, somewhere, not just in a comment?
+For maximum benefit developers should use @code{cvs
+edit} (not @code{chmod}) to make files read-write to
+edit them, and @code{cvs release} (not @code{rm}) to
+discard a working directory which is no longer in use,
+but @sc{cvs} is not able to enforce this behavior.
+
address@hidden I'm a little dissatisfied with this presentation,
address@hidden because "watch on"/"edit"/"editors" are one set of
address@hidden functionality, and "watch add"/"watchers" is another
address@hidden which is somewhat orthogonal even though they interact in
address@hidden various ways. But I think it might be
address@hidden confusing to describe them separately (e.g. "watch
address@hidden add" with loginfo). I don't know.
+
address@hidden
+* Setting a watch:: Telling CVS to watch certain files
+* Getting Notified:: Telling CVS to notify you
+* Editing files:: How to edit a file which is being watched
+* Watch information:: Information about who is watching and editing
+* Watches Compatibility:: Watches interact poorly with CVS 1.6 or earlier
address@hidden menu
+
address@hidden Setting a watch
address@hidden Telling CVS to watch certain files
+
+To enable the watch features, you first specify that
+certain files are to be watched.
+
address@hidden watch on (subcommand)
address@hidden Command {cvs watch on} address@hidden address@hidden@dots{}
+
address@hidden Read-only files, and watches
+Specify that developers should run @code{cvs edit}
+before editing @var{files}. @sc{cvs} will create working
+copies of @var{files} read-only, to remind developers
+to run the @code{cvs edit} command before working on
+them.
+
+If @var{files} includes the name of a directory, @sc{cvs}
+arranges to watch all files added to the corresponding
+repository directory, and sets a default for files
+added in the future; this allows the user to set
+notification policies on a per-directory basis. The
+contents of the directory are processed recursively,
+unless the @code{-l} option is given.
+The @code{-R} option can be used to force recursion if the @code{-l}
+option is set in @file{~/.cvsrc} (@pxref{~/.cvsrc}).
+
+If @var{files} is omitted, it defaults to the current directory.
+
address@hidden watch off (subcommand)
address@hidden deffn
+
address@hidden Command {cvs watch off} address@hidden address@hidden@dots{}
+
+Do not create @var{files} read-only on checkout; thus,
+developers will not be reminded to use @code{cvs edit}
+and @code{cvs unedit}.
+
+The @var{files} and options are processed as for @code{cvs
+watch on}.
+
address@hidden deffn
+
address@hidden Getting Notified
address@hidden Telling CVS to notify you
+
+You can tell @sc{cvs} that you want to receive
+notifications about various actions taken on a file.
+You can do this without using @code{cvs watch on} for
+the file, but generally you will want to use @code{cvs
+watch on}, to remind developers to use the @code{cvs edit}
+command.
+
address@hidden watch add (subcommand)
address@hidden Command {cvs watch add} address@hidden address@hidden
@address@hidden address@hidden@dots{}
+
+Add the current user to the list of people to receive notification of
+work done on @var{files}.
+
+The @code{-a} option specifies what kinds of events @sc{cvs} should notify
+the user about. @var{action} is one of the following:
+
address@hidden @code
+
address@hidden edit
+Another user has applied the @code{cvs edit} command (described
+below) to a watched file.
+
address@hidden commit
+Another user has committed changes to one of the named @var{files}.
+
address@hidden unedit
+Another user has abandoned editing a file (other than by committing changes).
+They can do this in several ways, by:
+
address@hidden @bullet
+
address@hidden
+applying the @code{cvs unedit} command (described below) to the file
+
address@hidden
+applying the @code{cvs release} command (@pxref{release}) to the file's parent
directory
+(or recursively to a directory more than one level up)
+
address@hidden
+deleting the file and allowing @code{cvs update} to recreate it
+
address@hidden itemize
+
address@hidden all
+All of the above.
+
address@hidden none
+None of the above. (This is useful with @code{cvs edit},
+described below.)
+
address@hidden table
+
+The @code{-a} option may appear more than once, or not at all. If
+omitted, the action defaults to @code{all}.
+
+The @var{files} and options are processed as for
address@hidden watch on}.
+
address@hidden deffn
+
+
address@hidden watch remove (subcommand)
address@hidden Command {cvs watch remove} address@hidden address@hidden
@address@hidden address@hidden@dots{}
+
+Remove a notification request established using @code{cvs watch add};
+the arguments are the same. If the @code{-a} option is present, only
+watches for the specified actions are removed.
+
address@hidden deffn
+
address@hidden notify (admin file)
+When the conditions exist for notification, @sc{cvs}
+calls the @file{notify} administrative file. Edit
address@hidden as one edits the other administrative
+files (@pxref{Intro administrative files}). This
+file follows the usual conventions for administrative
+files (@pxref{syntax}), where each line is a regular
+expression followed by a command to execute. The
+command should contain a single occurrence of @samp{%s}
+which will be replaced by the user to notify; the rest
+of the information regarding the notification will be
+supplied to the command on standard input. The
+standard thing to put in the @code{notify} file is the
+single line:
+
address@hidden
+ALL mail %s -s "CVS notification"
address@hidden example
+
address@hidden
+This causes users to be notified by electronic mail.
address@hidden FIXME: should it be this hard to set up this
address@hidden behavior (and the result when one fails to do so,
address@hidden silent failure to notify, so non-obvious)? Should
address@hidden CVS give a warning if no line in notify matches (and
address@hidden document the use of "DEFAULT :" for the case where
address@hidden skipping the notification is indeed desired)?
+
address@hidden users (admin file)
+Note that if you set this up in the straightforward
+way, users receive notifications on the server machine.
+One could of course write a @file{notify} script which
+directed notifications elsewhere, but to make this
+easy, @sc{cvs} allows you to associate a notification
+address for each user. To do so create a file
address@hidden in @file{CVSROOT} with a line for each
+user in the format @var{user}:@var{value}. Then
+instead of passing the name of the user to be notified
+to @file{notify}, @sc{cvs} will pass the @var{value}
+(normally an email address on some other machine).
+
address@hidden does not notify you for your own changes.
+Currently this check is done based on whether the user
+name of the person taking the action which triggers
+notification matches the user name of the person
+getting notification. In fact, in general, the watches
+features only track one edit by each user. It probably
+would be more useful if watches tracked each working
+directory separately, so this behavior might be worth
+changing.
address@hidden "behavior might be worth changing" is an effort to
address@hidden point to future directions while also not promising
address@hidden that "they" (as in "why don't they fix CVS to....")
address@hidden will do this.
address@hidden one implementation issue is identifying whether a
address@hidden working directory is same or different. Comparing
address@hidden pathnames/hostnames is hopeless, but having the server
address@hidden supply a serial number which the client stores in the
address@hidden CVS directory as a magic cookie should work.
+
address@hidden Editing files
address@hidden How to edit a file which is being watched
+
address@hidden Checkout, as term for getting ready to edit
+Since a file which is being watched is checked out
+read-only, you cannot simply edit it. To make it
+read-write, and inform others that you are planning to
+edit it, use the @code{cvs edit} command. Some systems
+call this a @dfn{checkout}, but @sc{cvs} uses that term
+for obtaining a copy of the sources (@pxref{Getting the
+source}), an operation which those systems call a
address@hidden or a @dfn{fetch}.
address@hidden Issue to think about: should we transition CVS
address@hidden towards the "get" terminology? "cvs get" is already a
address@hidden synonym for "cvs checkout" and that section of the
address@hidden manual refers to "Getting the source". If this is
address@hidden done, needs to be done gingerly (for example, we should
address@hidden still accept "checkout" in .cvsrc files indefinitely
address@hidden even if the CVS's messages are changed from "cvs checkout: "
address@hidden to "cvs get: ").
address@hidden There is a concern about whether "get" is not as
address@hidden good for novices because it is a more general term
address@hidden than "checkout" (and thus arguably harder to assign
address@hidden a technical meaning for).
+
address@hidden edit (subcommand)
address@hidden Command {cvs edit} address@hidden address@hidden @address@hidden
address@hidden@dots{}
+
+Prepare to edit the working files @var{files}. @sc{cvs} makes the
address@hidden read-write, and notifies users who have requested
address@hidden notification for any of @var{files}.
+
+The @code{cvs edit} command accepts the same options as the
address@hidden watch add} command, and establishes a temporary watch for the
+user on @var{files}; @sc{cvs} will remove the watch when @var{files} are
address@hidden or @code{commit}ted. If the user does not wish to
+receive notifications, she should specify @code{-a none}.
+
+The @var{files} and the options are processed as for the @code{cvs
+watch} commands.
+
+
address@hidden deffn
+
+Normally when you are done with a set of changes, you
+use the @code{cvs commit} command, which checks in your
+changes and returns the watched files to their usual
+read-only state. But if you instead decide to abandon
+your changes, or not to make any changes, you can use
+the @code{cvs unedit} command.
+
address@hidden unedit (subcommand)
address@hidden Abandoning work
address@hidden Reverting to repository version
address@hidden Command {cvs unedit} address@hidden address@hidden@dots{}
+
+Abandon work on the working files @var{files}, and revert them to the
+repository versions on which they are based. @sc{cvs} makes those
address@hidden read-only for which users have requested notification using
address@hidden watch on}. @sc{cvs} notifies users who have requested
@code{unedit}
+notification for any of @var{files}.
+
+The @var{files} and options are processed as for the
address@hidden watch} commands.
+
+If watches are not in use, the @code{unedit} command
+probably does not work, and the way to revert to the
+repository version is with the command @code{cvs update -C file}
+(@pxref{update}).
+The meaning is
+not precisely the same; the latter may also
+bring in some changes which have been made in the
+repository since the last time you updated.
address@hidden It would be a useful enhancement to CVS to make
address@hidden unedit work in the non-watch case as well.
address@hidden deffn
+
+When using client/server @sc{cvs}, you can use the
address@hidden edit} and @code{cvs unedit} commands even if
address@hidden is unable to successfully communicate with the
+server; the notifications will be sent upon the next
+successful @sc{cvs} command.
+
address@hidden Watch information
address@hidden Information about who is watching and editing
+
address@hidden watchers (subcommand)
address@hidden Command {cvs watchers} address@hidden address@hidden@dots{}
+
+List the users currently watching changes to @var{files}. The report
+includes the files being watched, and the mail address of each watcher.
+
+The @var{files} and options are processed as for the
address@hidden watch} commands.
+
address@hidden deffn
+
+
address@hidden editors (subcommand)
address@hidden Command {cvs editors} address@hidden address@hidden@dots{}
+
+List the users currently working on @var{files}. The report
+includes the mail address of each user, the time when the user began
+working with the file, and the host and path of the working directory
+containing the file.
+
+The @var{files} and options are processed as for the
address@hidden watch} commands.
+
address@hidden deffn
+
address@hidden Watches Compatibility
address@hidden Using watches with old versions of CVS
+
address@hidden CVS 1.6, and watches
+If you use the watch features on a repository, it
+creates @file{CVS} directories in the repository and
+stores the information about watches in that directory.
+If you attempt to use @sc{cvs} 1.6 or earlier with the
+repository, you get an error message such as the
+following (all on one line):
+
address@hidden
+cvs update: cannot open CVS/Entries for reading:
+No such file or directory
address@hidden example
+
address@hidden
+and your operation will likely be aborted. To use the
+watch features, you must upgrade all copies of @sc{cvs}
+which use that repository in local or server mode. If
+you cannot upgrade, use the @code{watch off} and
address@hidden remove} commands to remove all watches, and
+that will restore the repository to a state which
address@hidden 1.6 can cope with.
+
address@hidden Choosing a model
address@hidden Choosing between reserved or unreserved checkouts
address@hidden Choosing, reserved or unreserved checkouts
+
+Reserved and unreserved checkouts each have pros and
+cons. Let it be said that a lot of this is a matter of
+opinion or what works given different groups' working
+styles, but here is a brief description of some of the
+issues. There are many ways to organize a team of
+developers. @sc{cvs} does not try to enforce a certain
+organization. It is a tool that can be used in several
+ways.
+
+Reserved checkouts can be very counter-productive. If
+two persons want to edit different parts of a file,
+there may be no reason to prevent either of them from
+doing so. Also, it is common for someone to take out a
+lock on a file, because they are planning to edit it,
+but then forget to release the lock.
+
address@hidden "many groups"? specifics? cites to papers on this?
address@hidden some way to weasel-word it a bit more so we don't
address@hidden need facts :-)?
+People, especially people who are familiar with
+reserved checkouts, often wonder how often conflicts
+occur if unreserved checkouts are used, and how
+difficult they are to resolve. The experience with
+many groups is that they occur rarely and usually are
+relatively straightforward to resolve.
+
+The rarity of serious conflicts may be surprising, until one realizes
+that they occur only when two developers disagree on the proper design
+for a given section of code; such a disagreement suggests that the
+team has not been communicating properly in the first place. In order
+to collaborate under @emph{any} source management regimen, developers
+must agree on the general design of the system; given this agreement,
+overlapping changes are usually straightforward to merge.
+
+In some cases unreserved checkouts are clearly
+inappropriate. If no merge tool exists for the kind of
+file you are managing (for example word processor files
+or files edited by Computer Aided Design programs), and
+it is not desirable to change to a program which uses a
+mergeable data format, then resolving conflicts is
+going to be unpleasant enough that you generally will
+be better off to simply avoid the conflicts instead, by
+using reserved checkouts.
+
+The watches features described above in @ref{Watches}
+can be considered to be an intermediate model between
+reserved checkouts and unreserved checkouts. When you
+go to edit a file, it is possible to find out who else
+is editing it. And rather than having the system
+simply forbid both people editing the file, it can tell
+you what the situation is and let you figure out
+whether it is a problem in that particular case or not.
+Therefore, for some groups it can be considered the
+best of both the reserved checkout and unreserved
+checkout worlds.
+
address@hidden
---------------------------------------------------------------------
address@hidden Revision management
address@hidden Revision management
address@hidden Revision management
+
address@hidden -- This chapter could be expanded a lot.
address@hidden -- Experiences are very welcome!
+
+If you have read this far, you probably have a pretty
+good grasp on what @sc{cvs} can do for you. This
+chapter talks a little about things that you still have
+to decide.
+
+If you are doing development on your own using @sc{cvs}
+you could probably skip this chapter. The questions
+this chapter takes up become more important when more
+than one person is working in a repository.
+
address@hidden
+* When to commit:: Some discussion on the subject
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden When to commit
address@hidden When to commit?
address@hidden When to commit
address@hidden Committing, when to
address@hidden Policy
+
+Your group should decide which policy to use regarding
+commits. Several policies are possible, and as your
+experience with @sc{cvs} grows you will probably find
+out what works for you.
+
+If you commit files too quickly you might commit files
+that do not even compile. If your partner updates his
+working sources to include your buggy file, he will be
+unable to compile the code. On the other hand, other
+persons will not be able to benefit from the
+improvements you make to the code if you commit very
+seldom, and conflicts will probably be more common.
+
+It is common to only commit files after making sure
+that they can be compiled. Some sites require that the
+files pass a test suite. Policies like this can be
+enforced using the commitinfo file
+(@pxref{commitinfo}), but you should think twice before
+you enforce such a convention. By making the
+development environment too controlled it might become
+too regimented and thus counter-productive to the real
+goal, which is to get software written.
+
address@hidden
---------------------------------------------------------------------
address@hidden Keyword substitution
address@hidden Keyword substitution
address@hidden Keyword substitution
address@hidden Keyword expansion
address@hidden Identifying files
+
address@hidden Be careful when editing this chapter.
address@hidden Remember that this file is kept under
address@hidden version control, so we must not accidentally
address@hidden include a valid keyword in the running text.
+
+As long as you edit source files inside a working
+directory you can always find out the state of
+your files via @samp{cvs status} and @samp{cvs log}.
+But as soon as you export the files from your
+development environment it becomes harder to identify
+which revisions they are.
+
address@hidden can use a mechanism known as @dfn{keyword
+substitution} (or @dfn{keyword expansion}) to help
+identifying the files. Embedded strings of the form
address@hidden@var{keyword}$} and
address@hidden@var{keyword}:@dots{}$} in a file are replaced
+with strings of the form
address@hidden@var{keyword}:@var{value}$} whenever you obtain
+a new revision of the file.
+
address@hidden
+* Keyword list:: Keywords
+* Using keywords:: Using keywords
+* Avoiding substitution:: Avoiding substitution
+* Substitution modes:: Substitution modes
+* Configuring keyword expansion:: Configuring keyword expansion
+* Log keyword:: Problems with the $ Log$ keyword.
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Keyword list
address@hidden Keyword List
address@hidden Keyword List
+
address@hidden FIXME: need some kind of example here I think,
address@hidden perhaps in a
address@hidden "Keyword intro" node. The intro in the "Keyword
address@hidden substitution" node itself seems OK, but to launch
address@hidden into a list of the keywords somehow seems too abrupt.
+
+This is a list of the keywords:
+
address@hidden @code
address@hidden Author keyword
address@hidden $ Author$
+The login name of the user who checked in the revision.
+
address@hidden CVSHeader keyword
address@hidden $ CVSHeader
+A standard header (similar to $ Header$, but with
+the CVS root stripped off). It contains the relative
+pathname of the @sc{rcs} file to the CVS root, the
+revision number, the date (UTC), the author, the state,
+and the locker (if locked). Files will normally never
+be locked when you use @sc{cvs}.
+
+Note that this keyword has only been recently
+introduced to @sc{cvs} and may cause problems with
+existing installations if $ CVSHeader$ is already
+in the files for a different purpose. This keyword may
+be excluded using the @code{KeywordExpansion=eCVSHeader}
+in the @file{CVSROOT/config} file.
+See @ref{Configuring keyword expansion} for more details.
+
address@hidden Date keyword
address@hidden $ Date$
+The date and time (UTC) the revision was checked in.
+
address@hidden Header keyword
address@hidden $ Header$
+A standard header containing the full pathname of the
address@hidden file, the revision number, the date (UTC), the
+author, the state, and the locker (if locked). Files
+will normally never be locked when you use @sc{cvs}.
+
address@hidden Id keyword
address@hidden $ Id$
+Same as @code{$ Header$}, except that the @sc{rcs}
+filename is without a path.
+
address@hidden Name keyword
address@hidden $ Name$
+Tag name used to check out this file. The keyword is
+expanded only if one checks out with an explicit tag
+name. For example, when running the command @code{cvs
+co -r first}, the keyword expands to @samp{Name: first}.
+
address@hidden Locker keyword
address@hidden $ Locker$
+The login name of the user who locked the revision
+(empty if not locked, which is the normal case unless
address@hidden admin -l} is in use).
+
address@hidden Log keyword
address@hidden $ Log$
+The log message supplied during commit, preceded by a
+header containing the @sc{rcs} filename, the revision
+number, the author, and the date (UTC). Existing log
+messages are @emph{not} replaced. Instead, the new log
+message is inserted after @code{$ Log:@dots{}$}.
+Each new line is prefixed with the same string which
+precedes the @code{$Log} keyword. For example, if the
+file contains:
+
address@hidden
+ /* Here is what people have been up to:
+ *
+ * $ Log: frob.c,v $
+ * Revision 1.1 1997/01/03 14:23:51 joe
+ * Add the superfrobnicate option
+ *
+ */
address@hidden example
+
address@hidden
+then additional lines which are added when expanding
+the @code{$Log} keyword will be preceded by @samp{ * }.
+Unlike previous versions of @sc{cvs} and @sc{rcs}, the
address@hidden leader} from the @sc{rcs} file is not used.
+The @code{$Log} keyword is useful for
+accumulating a complete change log in a source file,
+but for several reasons it can be problematic.
address@hidden keyword}.
+
address@hidden RCSfile keyword
address@hidden $ RCSfile$
+The name of the RCS file without a path.
+
address@hidden Revision keyword
address@hidden $ Revision$
+The revision number assigned to the revision.
+
address@hidden Source keyword
address@hidden $ Source$
+The full pathname of the RCS file.
+
address@hidden State keyword
address@hidden $ State$
+The state assigned to the revision. States can be
+assigned with @code{cvs admin -s}---see @ref{admin options}.
+
address@hidden Local keyword
address@hidden Local keyword
+The @code{LocalKeyword} option in the @file{CVSROOT/config} file
+may be used to specify a local keyword which is to be
+used as an alias for one of the other keywords. For
+example, if the @file{CVSROOT/config} file contains
+a line with @code{LocalKeyword=MYBSD=CVSHeader}, then a
+file with the local keyword $ MYBSD$ will be
+expanded as if it were a $ CVSHeader$ keyword. If
+the src/frob.c file contained this keyword, it might
+look something like this:
+
address@hidden
+ /*
+ * $ MYBSD: src/frob.c,v 1.1 2003/05/04 09:27:45 john Exp $
+ */
address@hidden example
+
+Many repositories make use of a such a ``local
+keyword'' feature. An old patch to @sc{cvs} provided
+the @code{LocalKeyword} feature using a @code{tag=}
+option and called this the ``custom tag'' or ``local
+tag'' feature. It was used in conjunction with the
+what they called the @code{tagexpand=} option. In
address@hidden this other option is known as the
address@hidden option.
+See @ref{Configuring keyword expansion} for more
+details.
+
+Examples from popular projects include:
+$ FreeBSD$, $ NetBSD$,
+$ OpenBSD$, $ XFree86$,
+$ Xorg$.
+
+The advantage of this is that you can include your
+local version information in a file using this local
+keyword without disrupting the upstream version
+information (which may be a different local keyword or
+a standard keyword). Allowing bug reports and the like
+to more properly identify the source of the original
+bug to the third-party and reducing the number of
+conflicts that arise during an import of a new version.
+
+All keyword expansion except the local keyword may be
+disabled using the @code{KeywordExpansion} option in
+the @file{CVSROOT/config} file---see
address@hidden keyword expansion} for more details.
+
address@hidden table
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Using keywords
address@hidden Using keywords
+
+To include a keyword string you simply include the
+relevant text string, such as @code{$ Id$}, inside the
+file, and commit the file. @sc{cvs} will automatically
+expand the string as part of the commit operation.
+
+It is common to embed the @code{$ Id$} string in
+the source files so that it gets passed through to
+generated files. For example, if you are managing
+computer program source code, you might include a
+variable which is initialized to contain that string.
+Or some C compilers may provide a @code{#pragma ident}
+directive. Or a document management system might
+provide a way to pass a string through to generated
+files.
+
address@hidden Would be nice to give an example, but doing this in
address@hidden portable C is not possible and the problem with
address@hidden picking any one language (VMS HELP files, Ada,
address@hidden troff, whatever) is that people use CVS for all
address@hidden kinds of files.
+
address@hidden Ident (shell command)
+The @code{ident} command (which is part of the @sc{rcs}
+package) can be used to extract keywords and their
+values from a file. This can be handy for text files,
+but it is even more useful for extracting keywords from
+binary files.
+
address@hidden
+$ ident samp.c
+samp.c:
+ $ Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
+$ gcc samp.c
+$ ident a.out
+a.out:
+ $ Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
address@hidden example
+
address@hidden What (shell command)
address@hidden is another popular revision control system.
+It has a command, @code{what}, which is very similar to
address@hidden and used for the same purpose. Many sites
+without @sc{rcs} have @sc{sccs}. Since @code{what}
+looks for the character sequence @code{@@(#)} it is
+easy to include keywords that are detected by either
+command. Simply prefix the keyword with the
+magic @sc{sccs} phrase, like this:
+
address@hidden
+static char *id="@@(#) $ Id: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $";
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Avoiding substitution
address@hidden Avoiding substitution
+
+Keyword substitution has its disadvantages. Sometimes
+you might want the literal text string
address@hidden Author$} to appear inside a file without
address@hidden interpreting it as a keyword and expanding it
+into something like @samp{$ Author: ceder $}.
+
+There is unfortunately no way to selectively turn off
+keyword substitution. You can use @samp{-ko}
+(@pxref{Substitution modes}) to turn off keyword
+substitution entirely.
+
+In many cases you can avoid using keywords in
+the source, even though they appear in the final
+product. For example, the source for this manual
+contains @samp{$@@address@hidden@}Author$} whenever the text
address@hidden Author$} should appear. In @code{nroff}
+and @code{troff} you can embed the null-character
address@hidden&} inside the keyword for a similar effect.
+
+It is also possible to specify an explicit list of
+keywords to include or exclude using the
address@hidden option in the
address@hidden/config} file--see @ref{Configuring keyword expansion}
+for more details. This feature is intended primarily
+for use with the @code{LocalKeyword} option--see
address@hidden list}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Substitution modes
address@hidden Substitution modes
address@hidden Keyword substitution, changing modes
address@hidden -k (keyword substitution)
address@hidden Kflag
+
address@hidden FIXME: This could be made more coherent, by expanding it
address@hidden with more examples or something.
+Each file has a stored default substitution mode, and
+each working directory copy of a file also has a
+substitution mode. The former is set by the @samp{-k}
+option to @code{cvs add} and @code{cvs admin}; the
+latter is set by the @samp{-k} or @samp{-A} options to @code{cvs
+checkout} or @code{cvs update}. @code{cvs diff} also
+has a @samp{-k} option. For some examples,
+see @ref{Binary files}, and @ref{Merging and keywords}.
address@hidden The fact that -A is overloaded to mean both reset
address@hidden sticky options and reset sticky tags/dates is
address@hidden somewhat questionable. Perhaps there should be
address@hidden separate options to reset sticky options (e.g. -k
address@hidden A") and tags/dates (someone suggested -r HEAD could
address@hidden do this instead of setting a sticky tag of "HEAD"
address@hidden as in the status quo but I haven't thought much
address@hidden about that idea. Of course -r .reset or something
address@hidden could be coined if this needs to be a new option).
address@hidden On the other hand, having -A mean "get things back
address@hidden into the state after a fresh checkout" has a certain
address@hidden appeal, and maybe there is no sufficient reason for
address@hidden creeping featurism in this area.
+
+The modes available are:
+
address@hidden @samp
address@hidden -kkv
+Generate keyword strings using the default form, e.g.
address@hidden Revision: 5.7 $} for the @code{Revision}
+keyword.
+
address@hidden -kkvl
+Like @samp{-kkv}, except that a locker's name is always
+inserted if the given revision is currently locked.
+The locker's name is only relevant if @code{cvs admin
+-l} is in use.
+
address@hidden -kk
+Generate only keyword names in keyword strings; omit
+their values. For example, for the @code{Revision}
+keyword, generate the string @code{$ Revision$}
+instead of @code{$ Revision: 5.7 $}. This option
+is useful to ignore differences due to keyword
+substitution when comparing different revisions of a
+file (@pxref{Merging and keywords}).
+
address@hidden -ko
+Generate the old keyword string, present in the working
+file just before it was checked in. For example, for
+the @code{Revision} keyword, generate the string
address@hidden Revision: 1.1 $} instead of
address@hidden Revision: 5.7 $} if that is how the
+string appeared when the file was checked in.
+
address@hidden -kb
+Like @samp{-ko}, but also inhibit conversion of line
+endings between the canonical form in which they are
+stored in the repository (linefeed only), and the form
+appropriate to the operating system in use on the
+client. For systems, like unix, which use linefeed
+only to terminate lines, this is very similar to
address@hidden For more information on binary files, see
address@hidden files}. In @sc{cvs} version 1.12.2 and later
address@hidden, as set by @code{cvs add}, @code{cvs admin}, or
address@hidden import} may not be overridden by a @samp{-k} option
+specified on the command line.
+
address@hidden -kv
+Generate only keyword values for keyword strings. For
+example, for the @code{Revision} keyword, generate the string
address@hidden instead of @code{$ Revision: 5.7 $}.
+This can help generate files in programming languages
+where it is hard to strip keyword delimiters like
address@hidden Revision: $} from a string. However,
+further keyword substitution cannot be performed once
+the keyword names are removed, so this option should be
+used with care.
+
+One often would like to use @samp{-kv} with @code{cvs
address@hidden But be aware that doesn't
+handle an export containing binary files correctly.
+
address@hidden table
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Configuring keyword expansion
address@hidden Configuring Keyord Expansion
address@hidden Configuring keyword expansion
+
+In a repository that includes third-party software on
+vendor branches, it is sometimes helpful to configure
+CVS to use a local keyword instead of the standard
+$ Id$ or $ Header$ keywords. Examples from
+real projects includ, $ Xorg$, $ XFree86$,
+$ FreeBSD$, $ NetBSD$,
+$ OpenBSD$, and even $ dotat$.
+The advantage of this is that
+you can include your local version information in a
+file using this local keyword (sometimes called a
+``custom tag'' or a ``local tag'') without disrupting
+the upstream version information (which may be a
+different local keyword or a standard keyword). In
+these cases, it is typically desirable to disable the
+expansion of all keywords except the configured local
+keyword.
+
+The @code{KeywordExpansion} option in the
address@hidden/config} file is intended to allow for the
+either the explicit exclusion of a keyword or list of
+keywords, or for the explicit inclusion of a keyword or
+a list of keywords. This list may include the
address@hidden that has been configured.
+
+The @code{KeywordExpansion} option is followed by
address@hidden and the next character may either be @code{i}
+to start an inclusion list or @code{e} to start an
+exclusion list. If the following lines were added to
+the @file{CVSROOT/config} file:
+
address@hidden
+ # Add a "MyBSD" keyword and restrict keyword
+ # expansion
+ LocalKeyword=MyBSD=CVSHeader
+ KeywordExpand=iMyBSD
address@hidden example
+
+then only the $ MyBSD$ keyword would be expanded.
+A list may be used. The this example:
+
address@hidden
+ # Add a "MyBSD" keyword and restrict keyword
+ # expansion to the MyBSD, Name and Date keywords.
+ LocalKeyword=MyBSD=CVSHeader
+ KeywordExpand=iMyBSD,Name,Date
address@hidden example
+
+would allow $ MyBSD$, $ Name$, and
+$ Date$ to be expanded.
+
+It is also possible to configure an exclusion list
+using the following:
+
address@hidden
+ # Do not expand the non-RCS keyword CVSHeader
+ KeywordExpand=eCVSHeader
address@hidden example
+
+This allows @sc{cvs} to ignore the recently introduced
+$ CVSHeader$ keyword and retain all of the
+others. The exclusion entry could also contain the
+standard RCS keyword list, but this could be confusing
+to users that expect RCS keywords to be expanded, so
+ycare should be taken to properly set user expectations
+for a repository that is configured in that manner.
+
+If there is a desire to not have any RCS keywords
+expanded and not use the @code{-ko} flags everywhere,
+an administrator may disable all keyword expansion
+using the @file{CVSROOT/config} line:
+
address@hidden
+ # Do not expand any RCS keywords
+ KeywordExpand=i
address@hidden example
+
+this could be confusing to users that expect RCS
+keywords like $ Id$ to be expanded properly,
+so care should be taken to properly set user
+expectations for a repository so configured.
+
+It should be noted that a patch to provide both the
address@hidden and @code{LocalKeyword} features
+has been around a long time. However, that patch
+implemented these features using @code{tag=} and
address@hidden keywords and those keywords are NOT
+recognized.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Log keyword
address@hidden Problems with the $ Log$ keyword.
+
+The @code{$ Log$} keyword is somewhat
+controversial. As long as you are working on your
+development system the information is easily accessible
+even if you do not use the @code{$ Log$}
+keyword---just do a @code{cvs log}. Once you export
+the file the history information might be useless
+anyhow.
+
+A more serious concern is that @sc{cvs} is not good at
+handling @code{$ Log$} entries when a branch is
+merged onto the main trunk. Conflicts often result
+from the merging operation.
address@hidden Might want to check whether the CVS implementation
address@hidden of RCS_merge has this problem the same way rcsmerge
address@hidden does. I would assume so....
+
+People also tend to "fix" the log entries in the file
+(correcting spelling mistakes and maybe even factual
+errors). If that is done the information from
address@hidden log} will not be consistent with the
+information inside the file. This may or may not be a
+problem in real life.
+
+It has been suggested that the @code{$ Log$}
+keyword should be inserted @emph{last} in the file, and
+not in the files header, if it is to be used at all.
+That way the long list of change messages will not
+interfere with everyday source file browsing.
+
address@hidden
---------------------------------------------------------------------
address@hidden Tracking sources
address@hidden Tracking third-party sources
address@hidden Third-party sources
address@hidden Tracking sources
+
address@hidden FIXME: Need discussion of added and removed files.
address@hidden FIXME: This doesn't really adequately introduce the
address@hidden concepts of "vendor" and "you". They don't *have*
address@hidden to be separate organizations or separate people.
address@hidden We want a description which is somewhat more based on
address@hidden the technical issues of which sources go where, but
address@hidden also with enough examples of how this relates to
address@hidden relationships like customer-supplier, developer-QA,
address@hidden maintainer-contributor, or whatever, to make it
address@hidden seem concrete.
+If you modify a program to better fit your site, you
+probably want to include your modifications when the next
+release of the program arrives. @sc{cvs} can help you with
+this task.
+
address@hidden Vendor
address@hidden Vendor branch
address@hidden Branch, vendor-
+In the terminology used in @sc{cvs}, the supplier of the
+program is called a @dfn{vendor}. The unmodified
+distribution from the vendor is checked in on its own
+branch, the @dfn{vendor branch}. @sc{cvs} reserves branch
+1.1.1 for this use.
+
+When you modify the source and commit it, your revision
+will end up on the main trunk. When a new release is
+made by the vendor, you commit it on the vendor branch
+and copy the modifications onto the main trunk.
+
+Use the @code{import} command to create and update
+the vendor branch. When you import a new file,
+the vendor branch is made the `head' revision, so
+anyone that checks out a copy of the file gets that
+revision. When a local modification is committed it is
+placed on the main trunk, and made the `head'
+revision.
+
address@hidden
+* First import:: Importing for the first time
+* Update imports:: Updating with the import command
+* Reverting local changes:: Reverting to the latest vendor release
+* Binary files in imports:: Binary files require special handling
+* Keywords in imports:: Keyword substitution might be undesirable
+* Multiple vendor branches:: What if you get sources from several places?
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden First import
address@hidden Importing for the first time
address@hidden Importing modules
+
address@hidden Should mention naming conventions for vendor tags,
address@hidden release tags, and perhaps directory names.
+Use the @code{import} command to check in the sources
+for the first time. When you use the @code{import}
+command to track third-party sources, the @dfn{vendor
+tag} and @dfn{release tags} are useful. The
address@hidden tag} is a symbolic name for the branch
+(which is always 1.1.1, unless you use the @samp{-b
address@hidden flag---see @ref{Multiple vendor branches}.). The
address@hidden tags} are symbolic names for a particular
+release, such as @samp{FSF_0_04}.
+
address@hidden I'm not completely sure this belongs here. But
address@hidden we need to say it _somewhere_ reasonably obvious; it
address@hidden is a common misconception among people first learning CVS
+Note that @code{import} does @emph{not} change the
+directory in which you invoke it. In particular, it
+does not set up that directory as a @sc{cvs} working
+directory; if you want to work with the sources import
+them first and then check them out into a different
+directory (@pxref{Getting the source}).
+
address@hidden wdiff (import example)
+Suppose you have the sources to a program called
address@hidden in a directory @file{wdiff-0.04},
+and are going to make private modifications that you
+want to be able to use even when new releases are made
+in the future. You start by importing the source to
+your repository:
+
address@hidden
+$ cd wdiff-0.04
+$ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04
address@hidden example
+
+The vendor tag is named @samp{FSF_DIST} in the above
+example, and the only release tag assigned is
address@hidden
address@hidden FIXME: Need to say where fsf/wdiff comes from.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Update imports
address@hidden Updating with the import command
+
+When a new release of the source arrives, you import it into the
+repository with the same @code{import} command that you used to set up
+the repository in the first place. The only difference is that you
+specify a different release tag this time:
+
address@hidden
+$ tar xfz wdiff-0.05.tar.gz
+$ cd wdiff-0.05
+$ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05
address@hidden example
+
+For files that have not been modified locally, the newly created
+revision becomes the head revision. If you have made local
+changes, @code{import} will warn you that you must merge the changes
+into the main trunk, and tell you to use @samp{checkout -j} to do so:
+
address@hidden FIXME: why "wdiff" here and "fsf/wdiff" in the
address@hidden "import"? I think the assumption is that one has
address@hidden "wdiff fsf/wdiff" or some such in modules, but it
address@hidden would be better to not use modules in this example.
address@hidden
+$ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff
address@hidden example
+
address@hidden
+The above command will check out the latest revision of
address@hidden, merging the changes made on the vendor branch @samp{FSF_DIST}
+since yesterday into the working copy. If any conflicts arise during
+the merge they should be resolved in the normal way (@pxref{Conflicts
+example}). Then, the modified files may be committed.
+
+However, it is much better to use the two release tags rather than using
+a date on the branch as suggested above:
+
address@hidden
+$ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff
address@hidden example
+
address@hidden
+The reason this is better is that
+using a date, as suggested above, assumes that you do
+not import more than one release of a product per day.
+More importantly, using the release tags allows @sc{cvs} to detect files
+that were removed between the two vendor releases and mark them for
+removal. Since @code{import} has no way to detect removed files, you
+should do a merge like this even if @code{import} doesn't tell you to.
+
address@hidden Reverting local changes
address@hidden Reverting to the latest vendor release
+
+You can also revert local changes completely and return
+to the latest vendor release by changing the `head'
+revision back to the vendor branch on all files. For
+example, if you have a checked-out copy of the sources
+in @file{~/work.d/wdiff}, and you want to revert to the
+vendor's version for all the files in that directory,
+you would type:
+
address@hidden
+$ cd ~/work.d/wdiff
+$ cvs admin -bWDIFF .
address@hidden example
+
address@hidden
+You must specify the @samp{-bWDIFF} without any space
+after the @samp{-b}. @xref{admin options}.
+
address@hidden Binary files in imports
address@hidden How to handle binary files with cvs import
+
+Use the @samp{-k} wrapper option to tell import which
+files are binary. @xref{Wrappers}.
+
address@hidden Keywords in imports
address@hidden How to handle keyword substitution with cvs import
+
+The sources which you are importing may contain
+keywords (@pxref{Keyword substitution}). For example,
+the vendor may use @sc{cvs} or some other system
+which uses similar keyword expansion syntax. If you
+just import the files in the default fashion, then
+the keyword expansions supplied by the vendor will
+be replaced by keyword expansions supplied by your
+own copy of @sc{cvs}. It may be more convenient to
+maintain the expansions supplied by the vendor, so
+that this information can supply information about
+the sources that you imported from the vendor.
+
+To maintain the keyword expansions supplied by the
+vendor, supply the @samp{-ko} option to @code{cvs
+import} the first time you import the file.
+This will turn off keyword expansion
+for that file entirely, so if you want to be more
+selective you'll have to think about what you want
+and use the @samp{-k} option to @code{cvs update} or
address@hidden admin} as appropriate.
address@hidden Supplying -ko to import if the file already existed
address@hidden has no effect. Not clear to me whether it should
address@hidden or not.
+
address@hidden Multiple vendor branches
address@hidden Multiple vendor branches
+
+All the examples so far assume that there is only one
+vendor from which you are getting sources. In some
+situations you might get sources from a variety of
+places. For example, suppose that you are dealing with
+a project where many different people and teams are
+modifying the software. There are a variety of ways to
+handle this, but in some cases you have a bunch of
+source trees lying around and what you want to do more
+than anything else is just to all put them in @sc{cvs} so
+that you at least have them in one place.
+
+For handling situations in which there may be more than
+one vendor, you may specify the @samp{-b} option to
address@hidden import}. It takes as an argument the vendor
+branch to import to. The default is @samp{-b 1.1.1}.
+
+For example, suppose that there are two teams, the red
+team and the blue team, that are sending you sources.
+You want to import the red team's efforts to branch
+1.1.1 and use the vendor tag RED. You want to import
+the blue team's efforts to branch 1.1.3 and use the
+vendor tag BLUE. So the commands you might use are:
+
address@hidden
+$ cvs import dir RED RED_1-0
+$ cvs import -b 1.1.3 dir BLUE BLUE_1-5
address@hidden example
+
+Note that if your vendor tag does not match your
address@hidden option, @sc{cvs} will not detect this case! For
+example,
+
address@hidden
+$ cvs import -b 1.1.3 dir RED RED_1-0
address@hidden example
+
address@hidden
+Be careful; this kind of mismatch is sure to sow
+confusion or worse. I can't think of a useful purpose
+for the ability to specify a mismatch here, but if you
+discover such a use, don't. @sc{cvs} is likely to make this
+an error in some future release.
+
address@hidden Probably should say more about the semantics of
address@hidden multiple branches. What about the default branch?
address@hidden What about joining (perhaps not as useful with
address@hidden multiple branches, or perhaps it is. Either way
address@hidden should be mentioned).
+
address@hidden I'm not sure about the best location for this. In
address@hidden one sense, it might belong right after we've introduced
address@hidden CVS's basic version control model, because people need
address@hidden to figure out builds right away. The current location
address@hidden is based on the theory that it kind of akin to the
address@hidden "Revision management" section.
address@hidden Builds
address@hidden How your build system interacts with CVS
address@hidden Builds
address@hidden make
+
+As mentioned in the introduction, @sc{cvs} does not
+contain software for building your software from source
+code. This section describes how various aspects of
+your build system might interact with @sc{cvs}.
+
address@hidden Is there a way to discuss this without reference to
address@hidden tools other than CVS? I'm not sure there is; I
address@hidden wouldn't think that people who learn CVS first would
address@hidden even have this concern.
+One common question, especially from people who are
+accustomed to @sc{rcs}, is how to make their build get
+an up to date copy of the sources. The answer to this
+with @sc{cvs} is two-fold. First of all, since
address@hidden itself can recurse through directories, there
+is no need to modify your @file{Makefile} (or whatever
+configuration file your build tool uses) to make sure
+each file is up to date. Instead, just use two
+commands, first @code{cvs -q update} and then
address@hidden or whatever the command is to invoke your
+build tool. Secondly, you do not necessarily
address@hidden to get a copy of a change someone else made
+until you have finished your own work. One suggested
+approach is to first update your sources, then
+implement, build and
+test the change you were thinking of, and then commit
+your sources (updating first if necessary). By
+periodically (in between changes, using the approach
+just described) updating your entire tree, you ensure
+that your sources are sufficiently up to date.
+
address@hidden Bill of materials
+One common need is to record which versions of which
+source files went into a particular build. This kind
+of functionality is sometimes called @dfn{bill of
+materials} or something similar. The best way to do
+this with @sc{cvs} is to use the @code{tag} command to
+record which versions went into a given build
+(@pxref{Tags}).
+
+Using @sc{cvs} in the most straightforward manner
+possible, each developer will have a copy of the entire
+source tree which is used in a particular build. If
+the source tree is small, or if developers are
+geographically dispersed, this is the preferred
+solution. In fact one approach for larger projects is
+to break a project down into smaller
address@hidden I say subsystem instead of module because they may or
address@hidden may not use the modules file.
+separately-compiled subsystems, and arrange a way of
+releasing them internally so that each developer need
+check out only those subsystems which they are
+actively working on.
+
+Another approach is to set up a structure which allows
+developers to have their own copies of some files, and
+for other files to access source files from a central
+location. Many people have come up with some such a
address@hidden two such people are address@hidden (for
address@hidden a previous employer)
address@hidden and address@hidden (spicm and related tools),
address@hidden but as far as I know
address@hidden no one has nicely packaged or released such a system (or
address@hidden instructions for constructing one).
+system using features such as the symbolic link feature
+found in many operating systems, or the @code{VPATH}
+feature found in many versions of @code{make}. One build
+tool which is designed to help with this kind of thing
+is Odin (see
address@hidden://ftp.cs.colorado.edu/pub/distribs/odin}).
address@hidden Should we be saying more about Odin? Or how you use
address@hidden it with CVS? Also, the Prime Time Freeware for Unix
address@hidden disk (see http://www.ptf.com/) has Odin (with a nice
address@hidden paragraph summarizing it on the web), so that might be a
address@hidden semi-"official" place to point people.
address@hidden
address@hidden Of course, many non-CVS systems have this kind of
address@hidden functionality, for example OSF's ODE
address@hidden (http://www.osf.org/ode/) or mk
address@hidden (http://www.grin.net/~pzi/mk-3.18.4.docs/mk_toc.html
address@hidden He has changed providers in the past; a search engine search
address@hidden for "Peter Ziobrzynski" probably won't get too many
address@hidden spurious hits :-). A more stable URL might be
address@hidden ftp://ftp.uu.net/pub/cmvc/mk). But I'm not sure
address@hidden there is any point in mentioning them here unless they
address@hidden can work with CVS.
+
address@hidden
---------------------------------------------------------------------
address@hidden Special Files
address@hidden Special Files
+
address@hidden Special files
address@hidden Device nodes
address@hidden Ownership, saving in CVS
address@hidden Permissions, saving in CVS
address@hidden Hard links
address@hidden Symbolic links
+
+In normal circumstances, @sc{cvs} works only with regular
+files. Every file in a project is assumed to be
+persistent; it must be possible to open, read and close
+them; and so on. @sc{cvs} also ignores file permissions and
+ownerships, leaving such issues to be resolved by the
+developer at installation time. In other words, it is
+not possible to "check in" a device into a repository;
+if the device file cannot be opened, @sc{cvs} will refuse to
+handle it. Files also lose their ownerships and
+permissions during repository transactions.
+
+
address@hidden
---------------------------------------------------------------------
address@hidden CVS commands
address@hidden Guide to CVS commands
+
+This appendix describes the overall structure of
address@hidden commands, and describes some commands in
+detail (others are described elsewhere; for a quick
+reference to @sc{cvs} commands, @pxref{Invoking CVS}).
address@hidden The idea is that we want to move the commands which
address@hidden are described here into the main body of the manual,
address@hidden in the process reorganizing the manual to be
address@hidden organized around what the user wants to do, not
address@hidden organized around CVS commands.
address@hidden
address@hidden Note that many users do expect a manual which is
address@hidden organized by command. At least some users do.
address@hidden One good addition to the "organized by command"
address@hidden section (if any) would be "see also" links.
address@hidden The awk manual might be a good example; it has a
address@hidden reference manual which is more verbose than Invoking
address@hidden CVS but probably somewhat less verbose than CVS
address@hidden Commands.
+
address@hidden
+* Structure:: Overall structure of CVS commands
+* Exit status:: Indicating CVS's success or failure
+* ~/.cvsrc:: Default options with the ~/.csvrc file
+* Global options:: Options you give to the left of cvs_command
+* Common options:: Options you give to the right of cvs_command
+* admin:: Administration
+* checkout:: Checkout sources for editing
+* commit:: Check files into the repository
+* diff:: Show differences between revisions
+* export:: Export sources from CVS, similar to checkout
+* history:: Show status of files and users
+* import:: Import sources into CVS, using vendor branches
+* log:: Show log messages for files
+* rdiff:: 'patch' format diffs between releases
+* release:: Indicate that a directory is no longer in use
+* update:: Bring work tree in sync with repository
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Structure
address@hidden Overall structure of CVS commands
address@hidden Structure
address@hidden CVS command structure
address@hidden Command structure
address@hidden Format of CVS commands
+
+The overall format of all @sc{cvs} commands is:
+
address@hidden
+cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ]
address@hidden example
+
address@hidden @code
address@hidden cvs
+The name of the @sc{cvs} program.
+
address@hidden cvs_options
+Some options that affect all sub-commands of @sc{cvs}. These are
+described below.
+
address@hidden cvs_command
+One of several different sub-commands. Some of the commands have
+aliases that can be used instead; those aliases are noted in the
+reference manual for that command. There are only two situations
+where you may omit @samp{cvs_command}: @samp{cvs -H} elicits a
+list of available commands, and @samp{cvs -v} displays version
+information on @sc{cvs} itself.
+
address@hidden command_options
+Options that are specific for the command.
+
address@hidden command_args
+Arguments to the commands.
address@hidden table
+
+There is unfortunately some confusion between
address@hidden and @code{command_options}.
address@hidden, when given as a @code{cvs_option}, only
+affects some of the commands. When it is given as a
address@hidden is has a different meaning, and
+is accepted by more commands. In other words, do not
+take the above categorization too seriously. Look at
+the documentation instead.
+
address@hidden Exit status
address@hidden CVS's exit status
address@hidden Exit status, of CVS
+
address@hidden can indicate to the calling environment whether it
+succeeded or failed by setting its @dfn{exit status}.
+The exact way of testing the exit status will vary from
+one operating system to another. For example in a unix
+shell script the @samp{$?} variable will be 0 if the
+last command returned a successful exit status, or
+greater than 0 if the exit status indicated failure.
+
+If @sc{cvs} is successful, it returns a successful status;
+if there is an error, it prints an error message and
+returns a failure status. The one exception to this is
+the @code{cvs diff} command. It will return a
+successful status if it found no differences, or a
+failure status if there were differences or if there
+was an error. Because this behavior provides no good
+way to detect errors, in the future it is possible that
address@hidden diff} will be changed to behave like the
+other @sc{cvs} commands.
address@hidden It might seem like checking whether cvs -q diff
address@hidden produces empty or non-empty output can tell whether
address@hidden there were differences or not. But it seems like
address@hidden there are cases with output but no differences
address@hidden (testsuite basica-8b). It is not clear to me how
address@hidden useful it is for a script to be able to check
address@hidden whether there were differences.
address@hidden FIXCVS? In previous versions of CVS, cvs diff
address@hidden returned 0 for no differences, 1 for differences, or
address@hidden 2 for errors. Is this behavior worth trying to
address@hidden bring back (but what does it mean for VMS?)?
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden ~/.cvsrc
address@hidden Default options and the ~/.cvsrc file
address@hidden .cvsrc file
address@hidden Option defaults
+
+There are some @code{command_options} that are used so
+often that you might have set up an alias or some other
+means to make sure you always specify that option. One
+example (the one that drove the implementation of the
address@hidden support, actually) is that many people find the
+default output of the @samp{diff} command to be very
+hard to read, and that either context diffs or unidiffs
+are much easier to understand.
+
+The @file{~/.cvsrc} file is a way that you can add
+default options to @code{cvs_commands} within cvs,
+instead of relying on aliases or other shell scripts.
+
+The format of the @file{~/.cvsrc} file is simple. The
+file is searched for a line that begins with the same
+name as the @code{cvs_command} being executed. If a
+match is found, then the remainder of the line is split
+up (at whitespace characters) into separate options and
+added to the command arguments @emph{before} any
+options from the command line.
+
+If a command has two names (e.g., @code{checkout} and
address@hidden), the official name, not necessarily the one
+used on the command line, will be used to match against
+the file. So if this is the contents of the user's
address@hidden/.cvsrc} file:
+
address@hidden
+log -N
+diff -uN
+rdiff -u
+update -Pd
+checkout -P
+release -d
address@hidden example
+
address@hidden
+the command @samp{cvs checkout foo} would have the
address@hidden option added to the arguments, as well as
address@hidden co foo}.
+
+With the example file above, the output from @samp{cvs
+diff foobar} will be in unidiff format. @samp{cvs diff
+-c foobar} will provide context diffs, as usual.
+Getting "old" format diffs would be slightly more
+complicated, because @code{diff} doesn't have an option
+to specify use of the "old" format, so you would need
address@hidden -f diff foobar}.
+
+In place of the command name you can use @code{cvs} to
+specify global options (@pxref{Global options}). For
+example the following line in @file{.cvsrc}
+
address@hidden
+cvs -z6
address@hidden example
+
address@hidden
+causes @sc{cvs} to use compression level 6.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Global options
address@hidden Global options
address@hidden Options, global
address@hidden Global options
address@hidden Left-hand options
+
+The available @samp{cvs_options} (that are given to the
+left of @samp{cvs_command}) are:
+
address@hidden @code
address@hidden address@hidden
+Specify legal @sc{cvsroot} directory. See
address@hidden authentication server}.
+
address@hidden Authentication, stream
address@hidden Stream authentication
address@hidden -a
+Authenticate all communication between the client and
+the server. Only has an effect on the @sc{cvs} client.
+As of this writing, this is only implemented when using
+a GSSAPI connection (@pxref{GSSAPI authenticated}).
+Authentication prevents certain sorts of attacks
+involving hijacking the active @sc{tcp} connection.
+Enabling authentication does not enable encryption.
+
address@hidden RCSBIN, overriding
address@hidden Overriding RCSBIN
address@hidden -b @var{bindir}
+In @sc{cvs} 1.9.18 and older, this specified that
address@hidden programs are in the @var{bindir} directory.
+Current versions of @sc{cvs} do not run @sc{rcs}
+programs; for compatibility this option is accepted,
+but it does nothing.
+
address@hidden TMPDIR, overriding
address@hidden Overriding TMPDIR
address@hidden -T @var{tempdir}
+Use @var{tempdir} as the directory where temporary files are
+located. Overrides the setting of the @code{$TMPDIR} environment
+variable and any precompiled directory. This parameter should be
+specified as an absolute pathname.
+(When running client/server, @samp{-T} affects only the local process;
+specifying @samp{-T} for the client has no effect on the server and
+vice versa.)
+
address@hidden CVSROOT, overriding
address@hidden Overriding CVSROOT
address@hidden -d @var{cvs_root_directory}
+Use @var{cvs_root_directory} as the root directory
+pathname of the repository. Overrides the setting of
+the @code{$CVSROOT} environment variable. @xref{Repository}.
+
address@hidden EDITOR, overriding
address@hidden Overriding EDITOR
address@hidden -e @var{editor}
+Use @var{editor} to enter revision log information. Overrides the
+setting of the @code{$CVSEDITOR} and @code{$EDITOR}
+environment variables. For more information, see
address@hidden your changes}.
+
address@hidden -f
+Do not read the @file{~/.cvsrc} file. This
+option is most often used because of the
+non-orthogonality of the @sc{cvs} option set. For
+example, the @samp{cvs log} option @samp{-N} (turn off
+display of tag names) does not have a corresponding
+option to turn the display on. So if you have
address@hidden in the @file{~/.cvsrc} entry for @samp{log},
+you may need to use @samp{-f} to show the tag names.
+
address@hidden -H
address@hidden --help
+Display usage information about the specified @samp{cvs_command}
+(but do not actually execute the command). If you don't specify
+a command name, @samp{cvs -H} displays overall help for
address@hidden, including a list of other help options.
address@hidden It seems to me it is better to document it this way
address@hidden rather than trying to update this documentation
address@hidden every time that we add a --help-foo option. But
address@hidden perhaps that is confusing...
+
address@hidden -l
+Do not log the @samp{cvs_command} in the command history (but execute it
+anyway). @xref{history}, for information on command history.
+
address@hidden Read-only repository mode
address@hidden -R
+Turns on read-only repository mode. This allows one to check out from a
+read-only repository, such as within an anoncvs server, or from a CDROM
+repository.
+
+Same effect as if the @code{CVSREADONLYFS} environment
+variable is set. Using @samp{-R} can also considerably
+speed up checkout's over NFS.
+
address@hidden Read-only mode
address@hidden -n
+Do not change any files. Attempt to execute the
address@hidden, but only to issue reports; do not remove,
+update, or merge any existing files, or create any new files.
+
+Note that @sc{cvs} will not necessarily produce exactly
+the same output as without @samp{-n}. In some cases
+the output will be the same, but in other cases
address@hidden will skip some of the processing that would
+have been required to produce the exact same output.
+
address@hidden -Q
+Cause the command to be really quiet; the command will only
+generate output for serious problems.
+
address@hidden -q
+Cause the command to be somewhat quiet; informational messages,
+such as reports of recursion through subdirectories, are
+suppressed.
+
address@hidden Read-only files, and -r
address@hidden -r
+Make new working files read-only. Same effect
+as if the @code{$CVSREAD} environment variable is set
+(@pxref{Environment variables}). The default is to
+make working files writable, unless watches are on
+(@pxref{Watches}).
+
address@hidden -s @address@hidden
+Set a user variable (@pxref{Variables}).
+
address@hidden Trace
address@hidden -t
+Trace program execution; display messages showing the steps of
address@hidden activity. Particularly useful with @samp{-n} to explore the
+potential impact of an unfamiliar command.
+
address@hidden -v
address@hidden --version
+Display version and copyright information for @sc{cvs}.
+
address@hidden CVSREAD, overriding
address@hidden Overriding CVSREAD
address@hidden -w
+Make new working files read-write. Overrides the
+setting of the @code{$CVSREAD} environment variable.
+Files are created read-write by default, unless @code{$CVSREAD} is
+set or @samp{-r} is given.
address@hidden Note that -w only overrides -r and CVSREAD; it has
address@hidden no effect on files which are readonly because of
address@hidden "cvs watch on". My guess is that is the way it
address@hidden should be (or should "cvs -w get" on a watched file
address@hidden be the same as a get and a cvs edit?), but I'm not
address@hidden completely sure whether to document it this way.
+
address@hidden -x
address@hidden Encryption
+Encrypt all communication between the client and the
+server. Only has an effect on the @sc{cvs} client. As
+of this writing, this is only implemented when using a
+GSSAPI connection (@pxref{GSSAPI authenticated}) or a
+Kerberos connection (@pxref{Kerberos authenticated}).
+Enabling encryption implies that message traffic is
+also authenticated. Encryption support is not
+available by default; it must be enabled using a
+special configure option, @file{--enable-encryption},
+when you build @sc{cvs}.
+
address@hidden -z @var{gzip-level}
address@hidden Compression
address@hidden Gzip
+Set the compression level.
+Valid levels are 1 (high speed, low compression) to
+9 (low speed, high compression), or 0 to disable
+compression (the default).
+Only has an effect on the @sc{cvs} client.
+
address@hidden table
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Common options
address@hidden Common command options
address@hidden Common options
address@hidden Right-hand options
+
+This section describes the @samp{command_options} that
+are available across several @sc{cvs} commands. These
+options are always given to the right of
address@hidden Not all
+commands support all of these options; each option is
+only supported for commands where it makes sense.
+However, when a command has one of these options you
+can almost always count on the same behavior of the
+option as in other commands. (Other command options,
+which are listed with the individual commands, may have
+different behavior from one @sc{cvs} command to the other).
+
address@hidden: the @samp{history} command is an exception; it supports
+many options that conflict even with these standard options.}
+
address@hidden @code
address@hidden Dates
address@hidden Time
address@hidden Specifying dates
address@hidden -D @var{date_spec}
+Use the most recent revision no later than @var{date_spec}.
address@hidden is a single argument, a date description
+specifying a date in the past.
+
+The specification is @dfn{sticky} when you use it to make a
+private copy of a source file; that is, when you get a working
+file using @samp{-D}, @sc{cvs} records the date you specified, so that
+further updates in the same directory will use the same date
+(for more information on sticky tags/dates, @pxref{Sticky tags}).
+
address@hidden is available with the @code{annotate}, @code{checkout},
address@hidden, @code{export}, @code{history},
address@hidden, @code{rtag}, @code{tag}, and @code{update} commands.
+(The @code{history} command uses this option in a
+slightly different way; @pxref{history options}).
+
address@hidden What other formats should we accept? I don't want
address@hidden to start accepting a whole mess of non-standard
address@hidden new formats (there are a lot which are in wide use in
address@hidden one context or another), but practicality does
address@hidden dictate some level of flexibility.
address@hidden * POSIX.2 (e.g. touch, ls output, date) and other
address@hidden POSIX and/or de facto unix standards (e.g. at). The
address@hidden practice here is too inconsistent to be of any use.
address@hidden * VMS dates. This is not a formal standard, but
address@hidden there is a published specification (see SYS$ASCTIM
address@hidden and SYS$BINTIM in the _VMS System Services Reference
address@hidden Manual_), it is implemented consistently in VMS
address@hidden utilities, and VMS users will expect CVS running on
address@hidden VMS to support this format (and if we're going to do
address@hidden that, better to make CVS support it on all
address@hidden platforms. Maybe).
address@hidden
address@hidden NOTE: The tar manual has some documentation for
address@hidden getdate.y (just for our info; we don't want to
address@hidden attempt to document all the formats accepted by
address@hidden getdate.y).
address@hidden
address@hidden One more note: In output, CVS should consistently
address@hidden use one date format, and that format should be one that
address@hidden it accepts in input as well. The former isn't
address@hidden really true (see survey below), and I'm not
address@hidden sure that either of those formats is accepted in
address@hidden input.
address@hidden
address@hidden cvs log
address@hidden current 1996/01/02 13:45:31
address@hidden Internet 02 Jan 1996 13:45:31 UT
address@hidden ISO 1996-01-02 13:45:31
address@hidden cvs ann
address@hidden current 02-Jan-96
address@hidden Internet-like 02 Jan 96
address@hidden ISO 96-01-02
address@hidden cvs status
address@hidden current Tue Jun 11 02:54:53 1996
address@hidden Internet [Tue,] 11 Jun 1996 02:54:53
address@hidden ISO 1996-06-11 02:54:53
address@hidden note: date possibly should be omitted entirely for
address@hidden other reasons.
address@hidden cvs editors
address@hidden current Tue Jun 11 02:54:53 1996 GMT
address@hidden cvs history
address@hidden current 06/11 02:54 +0000
address@hidden any others?
address@hidden There is a good chance the proper solution has to
address@hidden involve at least some level of letting the user
address@hidden decide which format (with the default being the
address@hidden formats CVS has always used; changing these might be
address@hidden _very_ disruptive since scripts may very well be
address@hidden parsing them).
address@hidden
address@hidden Another random bit of prior art concerning dates is
address@hidden the strptime function which takes templates such as
address@hidden "%m/%d/%y", and apparent a variant of getdate()
address@hidden which also honors them. See
address@hidden X/Open CAE Specification, System Interfaces and
address@hidden Headers Issue 4, Version 2 (September 1994), in the
address@hidden entry for getdate() on page 231
+
address@hidden Timezone, in input
address@hidden Zone, time, in input
+A wide variety of date formats are supported by
address@hidden The most standard ones are ISO8601 (from the
+International Standards Organization) and the Internet
+e-mail standard (specified in RFC822 as amended by
+RFC1123).
+
address@hidden Probably should be doing more to spell out just what
address@hidden the rules are, rather than just giving examples.
address@hidden But I want to keep this simple too.
address@hidden So I don't know....
address@hidden A few specific issues: (1) Maybe should reassure
address@hidden people that years after 2000
address@hidden work (they are in the testsuite, so they do indeed
address@hidden work). (2) What do two digit years
address@hidden mean? Where do we accept them? (3) Local times can
address@hidden be ambiguous or nonexistent if they fall during the
address@hidden hour when daylight savings time goes into or out of
address@hidden effect. Pretty obscure, so I'm not at all sure we
address@hidden should be documenting the behavior in that case.
+ISO8601 dates have many variants but a few examples
+are:
+
address@hidden
+1972-09-24
+1972-09-24 20:05
address@hidden example
address@hidden I doubt we really accept all ISO8601 format dates
address@hidden (for example, decimal hours like 1972-09-24 20,2)
address@hidden I'm not sure we should, many of them are pretty
address@hidden bizarre and it has lots of gratuitous multiple ways
address@hidden to specify the same thing.
+
+There are a lot more ISO8601 date formats, and @sc{cvs}
+accepts many of them, but you probably don't want to
+hear the @emph{whole} long story :-).
+
address@hidden Citing a URL here is kind of problematic given how
address@hidden much they change and people who have old versions of
address@hidden this manual, but in case we want to reinstate an
address@hidden ISO8601 URL, a few are:
address@hidden http://www.saqqara.demon.co.uk/datefmt.htm
address@hidden http://www.cl.cam.ac.uk/~mgk25/iso-time.html
address@hidden Citing some other ISO8601 source is probably even
address@hidden worse :-).
+
+In addition to the dates allowed in Internet e-mail
+itself, @sc{cvs} also allows some of the fields to be
+omitted. For example:
address@hidden FIXME: Need to figure out better, and document,
address@hidden what we want to allow the user to omit.
address@hidden NOTE: "omit" does not imply "reorder".
address@hidden FIXME: Need to cite a web page describing how to get
address@hidden RFC's.
+
address@hidden
+24 Sep 1972 20:05
+24 Sep
address@hidden example
+
+The date is interpreted as being in the
+local timezone, unless a specific timezone is
+specified.
+
+These two date formats are preferred. However,
address@hidden currently accepts a wide variety of other date
+formats. They are intentionally not documented here in
+any detail, and future versions of @sc{cvs} might not
+accept all of them.
address@hidden We should document and testsuite "now" and
address@hidden "yesterday". "now" is mentioned in the FAQ and
address@hidden "yesterday" is mentioned in this document (and the
address@hidden message from "cvs import" suggesting a merge
address@hidden command). What else? Probably some/all of the "3
address@hidden weeks ago" family.
address@hidden
address@hidden Maybe at
address@hidden some point have CVS start give warnings on "unofficial"
address@hidden formats (many of which might be typos or user
address@hidden misunderstandings, and/or formats people never/rarely
address@hidden use to specify dates)?
+
+One such format is
address@hidden@var{month}/@var{day}/@var{year}}. This may
+confuse people who are accustomed to having the month
+and day in the other order; @samp{1/4/96} is January 4,
+not April 1.
+
+Remember to quote the argument to the @samp{-D}
+flag so that your shell doesn't interpret spaces as
+argument separators. A command using the @samp{-D}
+flag can look like this:
+
address@hidden
+$ cvs diff -D "1 hour ago" cvs.texinfo
address@hidden example
+
address@hidden Forcing a tag match
address@hidden -f
+When you specify a particular date or tag to @sc{cvs} commands, they
+normally ignore files that do not contain the tag (or did not
+exist prior to the date) that you specified. Use the @samp{-f} option
+if you want files retrieved even when there is no match for the
+tag or date. (The most recent revision of the file
+will be used).
+
+Note that even with @samp{-f}, a tag that you specify
+must exist (that is, in some file, not necessary in
+every file). This is so that @sc{cvs} will continue to
+give an error if you mistype a tag name.
+
address@hidden 800
address@hidden is available with these commands:
address@hidden, @code{checkout}, @code{export},
address@hidden, @code{rtag}, and @code{update}.
+
address@hidden: The @code{commit} and @code{remove}
+commands also have a
address@hidden option, but it has a different behavior for
+those commands. See @ref{commit options}, and
address@hidden files}.}
+
address@hidden -k @var{kflag}
+Override the default processing of RCS keywords other than
address@hidden @xref{Keyword substitution}, for the meaning of
address@hidden Used with the @code{checkout} and @code{update}
+commands, your @var{kflag} specification is
address@hidden; that is, when you use this option
+with a @code{checkout} or @code{update} command,
address@hidden associates your selected @var{kflag} with any files
+it operates on, and continues to use that @var{kflag} with future
+commands on the same files until you specify otherwise.
+
+The @samp{-k} option is available with the @code{add},
address@hidden, @code{diff}, @code{export}, @code{import} and
address@hidden commands.
+
address@hidden: Prior to CVS version 1.12.2, the @samp{-k} flag
+overrode the @samp{-kb} indication for a binary file. This could
+sometimes corrupt binary files. @xref{Merging and keywords}, for
+more.}
+
address@hidden -l
+Local; run only in current working directory, rather than
+recursing through subdirectories.
+
+Available with the following commands: @code{annotate}, @code{checkout},
address@hidden, @code{diff}, @code{edit}, @code{editors}, @code{export},
address@hidden, @code{rdiff}, @code{remove}, @code{rtag},
address@hidden, @code{tag}, @code{unedit}, @code{update}, @code{watch},
+and @code{watchers}.
+
address@hidden Editor, avoiding invocation of
address@hidden Avoiding editor invocation
address@hidden -m @var{message}
+Use @var{message} as log information, instead of
+invoking an editor.
+
+Available with the following commands: @code{add},
address@hidden and @code{import}.
+
address@hidden -n
+Do not run any tag program. (A program can be
+specified to run in the modules
+database (@pxref{modules}); this option bypasses it).
+
address@hidden: this is not the same as the @samp{cvs -n}
+program option, which you can specify to the left of a cvs command!}
+
+Available with the @code{checkout}, @code{commit}, @code{export},
+and @code{rtag} commands.
+
address@hidden -P
+Prune empty directories. See @ref{Removing directories}.
+
address@hidden -p
+Pipe the files retrieved from the repository to standard output,
+rather than writing them in the current directory. Available
+with the @code{checkout} and @code{update} commands.
+
address@hidden -R
+Process directories recursively. This is on by default.
+
+Available with the following commands: @code{annotate}, @code{checkout},
address@hidden, @code{diff}, @code{edit}, @code{editors}, @code{export},
address@hidden, @code{remove}, @code{rtag},
address@hidden, @code{tag}, @code{unedit}, @code{update}, @code{watch},
+and @code{watchers}.
+
address@hidden -r @var{tag}
address@hidden HEAD, special tag
address@hidden BASE, special tag
+Use the revision specified by the @var{tag} argument instead of the
+default @dfn{head} revision. As well as arbitrary tags defined
+with the @code{tag} or @code{rtag} command, two special tags are
+always available: @samp{HEAD} refers to the most recent version
+available in the repository, and @samp{BASE} refers to the
+revision you last checked out into the current working directory.
+
address@hidden FIXME: What does HEAD really mean? I believe that
address@hidden the current answer is the head of the default branch
address@hidden for all cvs commands except diff. For diff, it
address@hidden seems to be (a) the head of the trunk (or the default
address@hidden branch?) if there is no sticky tag, (b) the head of the
address@hidden branch for the sticky tag, if there is a sticky tag.
address@hidden (b) is ugly as it differs
address@hidden from what HEAD means for other commands, but people
address@hidden and/or scripts are quite possibly used to it.
address@hidden See "head" tests in sanity.sh.
address@hidden Probably the best fix is to introduce two new
address@hidden special tags, ".thead" for the head of the trunk,
address@hidden and ".bhead" for the head of the current branch.
address@hidden Then deprecate HEAD. This has the advantage of
address@hidden not surprising people with a change to HEAD, and a
address@hidden side benefit of also phasing out the poorly-named
address@hidden HEAD (see discussion of reserved tag names in node
address@hidden "Tags"). Of course, .thead and .bhead should be
address@hidden carefully implemented (with the implementation the
address@hidden same for "diff" as for everyone else), test cases
address@hidden written (similar to the ones in "head"), new tests
address@hidden cases written for things like default branches, &c.
+
+The tag specification is sticky when you use this
address@hidden option
+with @code{checkout} or @code{update} to make your own
+copy of a file: @sc{cvs} remembers the tag and continues to use it on
+future update commands, until you specify otherwise (for more information
+on sticky tags/dates, @pxref{Sticky tags}).
+
+The tag can be either a symbolic or numeric tag, as
+described in @ref{Tags}, or the name of a branch, as
+described in @ref{Branching and merging}.
+
+Specifying the @samp{-q} global option along with the
address@hidden command option is often useful, to suppress
+the warning messages when the @sc{rcs} file
+does not contain the specified tag.
+
address@hidden: this is not the same as the overall @samp{cvs -r} option,
+which you can specify to the left of a @sc{cvs} command!}
+
address@hidden is available with the @code{checkout}, @code{commit},
address@hidden, @code{history}, @code{export}, @code{rdiff},
address@hidden, and @code{update} commands.
+
address@hidden -W
+Specify file names that should be filtered. You can
+use this option repeatedly. The spec can be a file
+name pattern of the same type that you can specify in
+the @file{.cvswrappers} file.
+Available with the following commands: @code{import},
+and @code{update}.
+
address@hidden table
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden admin
address@hidden admin---Administration
address@hidden Admin (subcommand)
+
address@hidden @bullet
address@hidden
+Requires: repository, working directory.
address@hidden
+Changes: repository.
address@hidden
+Synonym: rcs
address@hidden itemize
+
+This is the @sc{cvs} interface to assorted
+administrative facilities. Some of them have
+questionable usefulness for @sc{cvs} but exist for
+historical purposes. Some of the questionable options
+are likely to disappear in the future. This command
address@hidden work recursively, so extreme care should be
+used.
+
address@hidden cvsadmin
address@hidden UserAdminOptions, in CVSROOT/config
+On unix, if there is a group named @code{cvsadmin},
+only members of that group can run @code{cvs admin}
+commands, except for those specified using the
address@hidden configuration option in the
address@hidden/config} file. Options specified using
address@hidden can be run by any user. See
address@hidden for more on @code{UserAdminOptions}.
+
+The @code{cvsadmin} group should exist on the server,
+or any system running the non-client/server @sc{cvs}.
+To disallow @code{cvs admin} for all users, create a
+group with no users in it. On NT, the @code{cvsadmin}
+feature does not exist and all users
+can run @code{cvs admin}.
+
address@hidden
+* admin options:: admin options
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden admin options
address@hidden admin options
+
+Some of these options have questionable usefulness for
address@hidden but exist for historical purposes. Some even
+make it impossible to use @sc{cvs} until you undo the
+effect!
+
address@hidden @code
address@hidden address@hidden
+Might not work together with @sc{cvs}. Append the
+access list of @var{oldfile} to the access list of the
address@hidden file.
+
address@hidden address@hidden
+Might not work together with @sc{cvs}. Append the
+login names appearing in the comma-separated list
address@hidden to the access list of the @sc{rcs} file.
+
address@hidden address@hidden
+Set the default branch to @var{rev}. In @sc{cvs}, you
+normally do not manipulate default branches; sticky
+tags (@pxref{Sticky tags}) are a better way to decide
+which branch you want to work on. There is one reason
+to run @code{cvs admin -b}: to revert to the vendor's
+version when using vendor branches (@pxref{Reverting
+local changes}).
+There can be no space between @samp{-b} and its argument.
address@hidden Hmm, we don't document the usage where rev is
address@hidden omitted. Maybe that usage can/should be deprecated
address@hidden (and replaced with -bHEAD or something?) (so we can toss
address@hidden the optional argument). Note that -bHEAD does not
address@hidden work, as of 17 Sep 1997, but probably will once "cvs
address@hidden admin" is internal to CVS.
+
address@hidden Comment leader
address@hidden address@hidden
+Sets the comment leader to @var{string}. The comment
+leader is not used by current versions of @sc{cvs} or
address@hidden 5.7. Therefore, you can almost surely not
+worry about it. @xref{Keyword substitution}.
+
address@hidden address@hidden
+Might not work together with @sc{cvs}. Erase the login
+names appearing in the comma-separated list
address@hidden from the access list of the RCS file. If
address@hidden is omitted, erase the entire access list.
+There can be no space between @samp{-e} and its argument.
+
address@hidden -I
+Run interactively, even if the standard input is not a
+terminal. This option does not work with the
+client/server @sc{cvs} and is likely to disappear in
+a future release of @sc{cvs}.
+
address@hidden -i
+Useless with @sc{cvs}. This creates and initializes a
+new @sc{rcs} file, without depositing a revision. With
address@hidden, add files with the @code{cvs add} command
+(@pxref{Adding files}).
+
address@hidden address@hidden
+Set the default keyword
+substitution to @var{subst}. @xref{Keyword
+substitution}. Giving an explicit @samp{-k} option to
address@hidden update}, @code{cvs export}, or @code{cvs
+checkout} overrides this default.
+
address@hidden address@hidden
+Lock the revision with number @var{rev}. If a branch
+is given, lock the latest revision on that branch. If
address@hidden is omitted, lock the latest revision on the
+default branch. There can be no space between
address@hidden and its argument.
+
+This can be used in conjunction with the
address@hidden script in the @file{contrib}
+directory of the @sc{cvs} source distribution to
+provide reserved checkouts (where only one user can be
+editing a given file at a time). See the comments in
+that file for details (and see the @file{README} file
+in that directory for disclaimers about the unsupported
+nature of contrib). According to comments in that
+file, locking must set to strict (which is the default).
+
address@hidden -L
+Set locking to strict. Strict locking means that the
+owner of an RCS file is not exempt from locking for
+checkin. For use with @sc{cvs}, strict locking must be
+set; see the discussion under the @samp{-l} option above.
+
address@hidden Changing a log message
address@hidden Replacing a log message
address@hidden Correcting a log message
address@hidden Fixing a log message
address@hidden Log message, correcting
address@hidden address@hidden:@var{msg}
+Replace the log message of revision @var{rev} with
address@hidden
+
address@hidden The rcs -M option, to suppress sending mail, has never been
address@hidden documented as a cvs admin option.
+
address@hidden address@hidden:address@hidden
+Act like @samp{-n}, except override any previous
+assignment of @var{name}. For use with magic branches,
+see @ref{Magic branch numbers}.
+
address@hidden address@hidden:address@hidden
+Associate the symbolic name @var{name} with the branch
+or revision @var{rev}. It is normally better to use
address@hidden tag} or @samp{cvs rtag} instead. Delete the
+symbolic name if both @samp{:} and @var{rev} are
+omitted; otherwise, print an error message if
address@hidden is already associated with another number.
+If @var{rev} is symbolic, it is expanded before
+association. A @var{rev} consisting of a branch number
+followed by a @samp{.} stands for the current latest
+revision in the branch. A @samp{:} with an empty
address@hidden stands for the current latest revision on the
+default branch, normally the trunk. For example,
address@hidden admin address@hidden:} associates @var{name} with the
+current latest revision of all the RCS files;
+this contrasts with @samp{cvs admin address@hidden:$} which
+associates @var{name} with the revision numbers
+extracted from keyword strings in the corresponding
+working files.
+
address@hidden Deleting revisions
address@hidden Outdating revisions
address@hidden Saving space
address@hidden address@hidden
+Deletes (@dfn{outdates}) the revisions given by
address@hidden
+
+Note that this command can be quite dangerous unless
+you know @emph{exactly} what you are doing (for example
+see the warnings below about how the
address@hidden:@var{rev2} syntax is confusing).
+
+If you are short on disc this option might help you.
+But think twice before using it---there is no way short
+of restoring the latest backup to undo this command!
+If you delete different revisions than you planned,
+either due to carelessness or (heaven forbid) a @sc{cvs}
+bug, there is no opportunity to correct the error
+before the revisions are deleted. It probably would be
+a good idea to experiment on a copy of the repository
+first.
+
+Specify @var{range} in one of the following ways:
+
address@hidden @code
address@hidden @var{rev1}::@var{rev2}
+Collapse all revisions between rev1 and rev2, so that
address@hidden only stores the differences associated with going
+from rev1 to rev2, not intermediate steps. For
+example, after @samp{-o 1.3::1.5} one can retrieve
+revision 1.3, revision 1.5, or the differences to get
+from 1.3 to 1.5, but not the revision 1.4, or the
+differences between 1.3 and 1.4. Other examples:
address@hidden 1.3::1.4} and @samp{-o 1.3::1.3} have no
+effect, because there are no intermediate revisions to
+remove.
+
address@hidden ::@var{rev}
+Collapse revisions between the beginning of the branch
+containing @var{rev} and @var{rev} itself. The
+branchpoint and @var{rev} are left intact. For
+example, @samp{-o ::1.3.2.6} deletes revision 1.3.2.1,
+revision 1.3.2.5, and everything in between, but leaves
+1.3 and 1.3.2.6 intact.
+
address@hidden @var{rev}::
+Collapse revisions between @var{rev} and the end of the
+branch containing @var{rev}. Revision @var{rev} is
+left intact but the head revision is deleted.
+
address@hidden @var{rev}
+Delete the revision @var{rev}. For example, @samp{-o
+1.3} is equivalent to @samp{-o 1.2::1.4}.
+
address@hidden @var{rev1}:@var{rev2}
+Delete the revisions from @var{rev1} to @var{rev2},
+inclusive, on the same branch. One will not be able to
+retrieve @var{rev1} or @var{rev2} or any of the
+revisions in between. For example, the command
address@hidden admin -oR_1_01:R_1_02 .} is rarely useful.
+It means to delete revisions up to, and including, the
+tag R_1_02. But beware! If there are files that have not
+changed between R_1_02 and R_1_03 the file will have
address@hidden same} numerical revision number assigned to
+the tags R_1_02 and R_1_03. So not only will it be
+impossible to retrieve R_1_02; R_1_03 will also have to
+be restored from the tapes! In most cases you want to
+specify @var{rev1}::@var{rev2} instead.
+
address@hidden :@var{rev}
+Delete revisions from the beginning of the
+branch containing @var{rev} up to and including
address@hidden
+
address@hidden @var{rev}:
+Delete revisions from revision @var{rev}, including
address@hidden itself, to the end of the branch containing
address@hidden
address@hidden table
+
+None of the revisions to be deleted may have
+branches or locks.
+
+If any of the revisions to be deleted have symbolic
+names, and one specifies one of the @samp{::} syntaxes,
+then @sc{cvs} will give an error and not delete any
+revisions. If you really want to delete both the
+symbolic names and the revisions, first delete the
+symbolic names with @code{cvs tag -d}, then run
address@hidden admin -o}. If one specifies the
address@hidden::} syntaxes, then @sc{cvs} will delete the
+revisions but leave the symbolic names pointing to
+nonexistent revisions. This behavior is preserved for
+compatibility with previous versions of @sc{cvs}, but
+because it isn't very useful, in the future it may
+change to be like the @samp{::} case.
+
+Due to the way @sc{cvs} handles branches @var{rev}
+cannot be specified symbolically if it is a branch.
address@hidden branch numbers}, for an explanation.
address@hidden FIXME: is this still true? I suspect not.
+
+Make sure that no-one has checked out a copy of the
+revision you outdate. Strange things will happen if he
+starts to edit it and tries to check it back in. For
+this reason, this option is not a good way to take back
+a bogus commit; commit a new revision undoing the bogus
+change instead (@pxref{Merging two revisions}).
+
address@hidden -q
+Run quietly; do not print diagnostics.
+
address@hidden address@hidden:@var{rev}]
+Useful with @sc{cvs}. Set the state attribute of the
+revision @var{rev} to @var{state}. If @var{rev} is a
+branch number, assume the latest revision on that
+branch. If @var{rev} is omitted, assume the latest
+revision on the default branch. Any identifier is
+acceptable for @var{state}. A useful set of states is
address@hidden (for experimental), @samp{Stab} (for
+stable), and @samp{Rel} (for released). By default,
+the state of a new revision is set to @samp{Exp} when
+it is created. The state is visible in the output from
address@hidden log} (@pxref{log}), and in the
address@hidden Log$} and @samp{$ State$} keywords
+(@pxref{Keyword substitution}). Note that @sc{cvs}
+uses the @code{dead} state for its own purposes; to
+take a file to or from the @code{dead} state use
+commands like @code{cvs remove} and @code{cvs add}, not
address@hidden admin -s}.
+
address@hidden address@hidden
+Useful with @sc{cvs}. Write descriptive text from the
+contents of the named @var{file} into the RCS file,
+deleting the existing text. The @var{file} pathname
+may not begin with @samp{-}. The descriptive text can be seen in the
+output from @samp{cvs log} (@pxref{log}).
+There can be no space between @samp{-t} and its argument.
+
+If @var{file} is omitted,
+obtain the text from standard input, terminated by
+end-of-file or by a line containing @samp{.} by itself.
+Prompt for the text if interaction is possible; see
address@hidden
+
address@hidden address@hidden
+Similar to @address@hidden Write descriptive text
+from the @var{string} into the @sc{rcs} file, deleting
+the existing text.
+There can be no space between @samp{-t} and its argument.
+
address@hidden The rcs -T option, do not update last-mod time for
address@hidden minor changes, has never been documented as a
address@hidden cvs admin option.
+
address@hidden -U
+Set locking to non-strict. Non-strict locking means
+that the owner of a file need not lock a revision for
+checkin. For use with @sc{cvs}, strict locking must be
+set; see the discussion under the @samp{-l} option
+above.
+
address@hidden address@hidden
+See the option @samp{-l} above, for a discussion of
+using this option with @sc{cvs}. Unlock the revision
+with number @var{rev}. If a branch is given, unlock
+the latest revision on that branch. If @var{rev} is
+omitted, remove the latest lock held by the caller.
+Normally, only the locker of a revision may unlock it;
+somebody else unlocking a revision breaks the lock.
+This causes the original locker to be sent a @code{commit}
+notification (@pxref{Getting Notified}).
+There can be no space between @samp{-u} and its argument.
+
address@hidden address@hidden
+In previous versions of @sc{cvs}, this option meant to
+write an @sc{rcs} file which would be acceptable to
address@hidden version @var{n}, but it is now obsolete and
+specifying it will produce an error.
address@hidden Note that -V without an argument has never been
address@hidden documented as a cvs admin option.
+
address@hidden address@hidden
+In previous versions of @sc{cvs}, this was documented
+as a way of specifying the names of the @sc{rcs}
+files. However, @sc{cvs} has always required that the
address@hidden files used by @sc{cvs} end in @samp{,v}, so
+this option has never done anything useful.
+
address@hidden The rcs -z option, to specify the timezone, has
address@hidden never been documented as a cvs admin option.
address@hidden table
+
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden checkout
address@hidden checkout---Check out sources for editing
address@hidden checkout (subcommand)
address@hidden co (subcommand)
+
address@hidden @bullet
address@hidden
+Synopsis: checkout [options] address@hidden
address@hidden
+Requires: repository.
address@hidden
+Changes: working directory.
address@hidden
+Synonyms: co, get
address@hidden itemize
+
+Create or update a working directory containing copies of the
+source files specified by @var{modules}. You must execute
address@hidden before using most of the other @sc{cvs}
+commands, since most of them operate on your working
+directory.
+
+The @var{modules} are either
+symbolic names for some
+collection of source directories and files, or paths to
+directories or files in the repository. The symbolic
+names are defined in the @samp{modules} file.
address@hidden
address@hidden Needs an example, particularly of the non-"modules"
address@hidden case but probably of both.
+
address@hidden FIXME: this seems like a very odd place to introduce
address@hidden people to how CVS works. The bit about unreserved
address@hidden checkouts is also misleading as it depends on how
address@hidden things are set up.
+Depending on the modules you specify, @code{checkout} may
+recursively create directories and populate them with
+the appropriate source files. You can then edit these
+source files at any time (regardless of whether other
+software developers are editing their own copies of the
+sources); update them to include new changes applied by
+others to the source repository; or commit your work as
+a permanent change to the source repository.
+
+Note that @code{checkout} is used to create
+directories. The top-level directory created is always
+added to the directory where @code{checkout} is
+invoked, and usually has the same name as the specified
+module. In the case of a module alias, the created
+sub-directory may have a different name, but you can be
+sure that it will be a sub-directory, and that
address@hidden will show the relative path leading to
+each file as it is extracted into your private work
+area (unless you specify the @samp{-Q} global option).
+
+The files created by @code{checkout} are created
+read-write, unless the @samp{-r} option to @sc{cvs}
+(@pxref{Global options}) is specified, the
address@hidden environment variable is specified
+(@pxref{Environment variables}), or a watch is in
+effect for that file (@pxref{Watches}).
+
+Note that running @code{checkout} on a directory that was already
+built by a prior @code{checkout} is also permitted.
+This is similar to specifying the @samp{-d} option
+to the @code{update} command in the sense that new
+directories that have been created in the repository
+will appear in your work area.
+However, @code{checkout} takes a module name whereas
address@hidden takes a directory name. Also
+to use @code{checkout} this way it must be run from the
+top level directory (where you originally ran
address@hidden from), so before you run
address@hidden to update an existing directory, don't
+forget to change your directory to the top level
+directory.
+
+For the output produced by the @code{checkout} command
+see @ref{update output}.
+
address@hidden
+* checkout options:: checkout options
+* checkout examples:: checkout examples
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden checkout options
address@hidden checkout options
+
+These standard options are supported by @code{checkout}
+(@pxref{Common options}, for a complete description of
+them):
+
address@hidden @code
address@hidden -D @var{date}
+Use the most recent revision no later than @var{date}.
+This option is sticky, and implies @samp{-P}. See
address@hidden tags}, for more information on sticky tags/dates.
+
address@hidden -f
+Only useful with the @samp{-D @var{date}} or @samp{-r
address@hidden flags. If no matching revision is found,
+retrieve the most recent revision (instead of ignoring
+the file).
+
address@hidden -k @var{kflag}
+Process keywords according to @var{kflag}. See
address@hidden substitution}.
+This option is sticky; future updates of
+this file in this working directory will use the same
address@hidden The @code{status} command can be viewed
+to see the sticky options. See @ref{Invoking CVS}, for
+more information on the @code{status} command.
+
address@hidden -l
+Local; run only in current working directory.
+
address@hidden -n
+Do not run any checkout program (as specified
+with the @samp{-o} option in the modules file;
address@hidden).
+
address@hidden -P
+Prune empty directories. See @ref{Moving directories}.
+
address@hidden -p
+Pipe files to the standard output.
+
address@hidden -R
+Checkout directories recursively. This option is on by default.
+
address@hidden -r @var{tag}
+Use revision @var{tag}. This option is sticky, and implies @samp{-P}.
+See @ref{Sticky tags}, for more information on sticky tags/dates.
address@hidden table
+
+In addition to those, you can use these special command
+options with @code{checkout}:
+
address@hidden @code
address@hidden -A
+Reset any sticky tags, dates, or @samp{-k} options.
+See @ref{Sticky tags}, for more information on sticky tags/dates.
+
address@hidden -c
+Copy the module file, sorted, to the standard output,
+instead of creating or modifying any files or
+directories in your working directory.
+
address@hidden -d @var{dir}
+Create a directory called @var{dir} for the working
+files, instead of using the module name. In general,
+using this flag is equivalent to using @samp{mkdir
address@hidden; cd @var{dir}} followed by the checkout
+command without the @samp{-d} flag.
+
+There is an important exception, however. It is very
+convenient when checking out a single item to have the
+output appear in a directory that doesn't contain empty
+intermediate directories. In this case @emph{only},
address@hidden tries to ``shorten'' pathnames to avoid those empty
+directories.
+
+For example, given a module @samp{foo} that contains
+the file @samp{bar.c}, the command @samp{cvs co -d dir
+foo} will create directory @samp{dir} and place
address@hidden inside. Similarly, given a module
address@hidden which has subdirectory @samp{baz} wherein
+there is a file @samp{quux.c}, the command @samp{cvs co
+-d dir bar/baz} will create directory @samp{dir} and
+place @samp{quux.c} inside.
+
+Using the @samp{-N} flag will defeat this behavior.
+Given the same module definitions above, @samp{cvs co
+-N -d dir foo} will create directories @samp{dir/foo}
+and place @samp{bar.c} inside, while @samp{cvs co -N -d
+dir bar/baz} will create directories @samp{dir/bar/baz}
+and place @samp{quux.c} inside.
+
address@hidden -j @var{tag}
+With two @samp{-j} options, merge changes from the
+revision specified with the first @samp{-j} option to
+the revision specified with the second @samp{j} option,
+into the working directory.
+
+With one @samp{-j} option, merge changes from the
+ancestor revision to the revision specified with the
address@hidden option, into the working directory. The
+ancestor revision is the common ancestor of the
+revision which the working directory is based on, and
+the revision specified in the @samp{-j} option.
+
+In addition, each -j option can contain an optional
+date specification which, when used with branches, can
+limit the chosen revision to one within a specific
+date. An optional date is specified by adding a colon
+(:) to the tag:
address@hidden@var{Symbolic_Tag}:@var{Date_Specifier}}.
+
address@hidden and merging}.
+
address@hidden -N
+Only useful together with @samp{-d @var{dir}}. With
+this option, @sc{cvs} will not ``shorten'' module paths
+in your working directory when you check out a single
+module. See the @samp{-d} flag for examples and a
+discussion.
+
address@hidden -s
+Like @samp{-c}, but include the status of all modules,
+and sort it by the status string. @xref{modules}, for
+info about the @samp{-s} option that is used inside the
+modules file to set the module status.
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden checkout examples
address@hidden checkout examples
+
+Get a copy of the module @samp{tc}:
+
address@hidden
+$ cvs checkout tc
address@hidden example
+
+Get a copy of the module @samp{tc} as it looked one day
+ago:
+
address@hidden
+$ cvs checkout -D yesterday tc
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden commit
address@hidden commit---Check files into the repository
address@hidden commit (subcommand)
+
address@hidden @bullet
address@hidden
+Synopsis: commit [-lnRf] [-m 'log_message' |
+-F file] [-r revision] address@hidden
address@hidden
+Requires: working directory, repository.
address@hidden
+Changes: repository.
address@hidden
+Synonym: ci
address@hidden itemize
+
+Use @code{commit} when you want to incorporate changes
+from your working source files into the source
+repository.
+
+If you don't specify particular files to commit, all of
+the files in your working current directory are
+examined. @code{commit} is careful to change in the
+repository only those files that you have really
+changed. By default (or if you explicitly specify the
address@hidden option), files in subdirectories are also
+examined and committed if they have changed; you can
+use the @samp{-l} option to limit @code{commit} to the
+current directory only.
+
address@hidden verifies that the selected files are up
+to date with the current revisions in the source
+repository; it will notify you, and exit without
+committing, if any of the specified files must be made
+current first with @code{update} (@pxref{update}).
address@hidden does not call the @code{update} command
+for you, but rather leaves that for you to do when the
+time is right.
+
+When all is well, an editor is invoked to allow you to
+enter a log message that will be written to one or more
+logging programs (@pxref{modules}, and @pxref{loginfo})
+and placed in the @sc{rcs} file inside the
+repository. This log message can be retrieved with the
address@hidden command; see @ref{log}. You can specify the
+log message on the command line with the @samp{-m
address@hidden option, and thus avoid the editor invocation,
+or use the @samp{-F @var{file}} option to specify
+that the argument file contains the log message.
+
address@hidden
+* commit options:: commit options
+* commit examples:: commit examples
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden commit options
address@hidden commit options
+
+These standard options are supported by @code{commit}
+(@pxref{Common options}, for a complete description of
+them):
+
address@hidden @code
address@hidden -l
+Local; run only in current working directory.
+
address@hidden -R
+Commit directories recursively. This is on by default.
+
address@hidden -r @var{revision}
+Commit to @var{revision}. @var{revision} must be
+either a branch, or a revision on the main trunk that
+is higher than any existing revision number
+(@pxref{Assigning revisions}). You
+cannot commit to a specific revision on a branch.
address@hidden FIXME: Need xref for branch case.
address@hidden table
+
address@hidden also supports these options:
+
address@hidden @code
address@hidden -F @var{file}
+Read the log message from @var{file}, instead
+of invoking an editor.
+
address@hidden -f
+Note that this is not the standard behavior of
+the @samp{-f} option as defined in @ref{Common options}.
+
+Force @sc{cvs} to commit a new revision even if you haven't
+made any changes to the file. If the current revision
+of @var{file} is 1.7, then the following two commands
+are equivalent:
+
address@hidden
+$ cvs commit -f @var{file}
+$ cvs commit -r 1.8 @var{file}
address@hidden example
+
address@hidden This is odd, but it's how CVS has worked for some
address@hidden time.
+The @samp{-f} option disables recursion (i.e., it
+implies @samp{-l}). To force @sc{cvs} to commit a new
+revision for all files in all subdirectories, you must
+use @samp{-f -R}.
+
address@hidden -m @var{message}
+Use @var{message} as the log message, instead of
+invoking an editor.
address@hidden table
+
address@hidden 2000
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden commit examples
address@hidden commit examples
+
address@hidden FIXME: this material wants to be somewhere
address@hidden in "Branching and merging".
+
address@hidden Committing to a branch
+
+You can commit to a branch revision (one that has an
+even number of dots) with the @samp{-r} option. To
+create a branch revision, use the @samp{-b} option
+of the @code{rtag} or @code{tag} commands
+(@pxref{Branching and merging}). Then, either @code{checkout} or
address@hidden can be used to base your sources on the
+newly created branch. From that point on, all
address@hidden changes made within these working sources
+will be automatically added to a branch revision,
+thereby not disturbing main-line development in any
+way. For example, if you had to create a patch to the
+1.2 version of the product, even though the 2.0 version
+is already under development, you might do:
+
address@hidden
+$ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module
+$ cvs checkout -r FCS1_2_Patch product_module
+$ cd product_module
+[[ hack away ]]
+$ cvs commit
address@hidden example
+
address@hidden
+This works automatically since the @samp{-r} option is
+sticky.
+
address@hidden Creating the branch after editing
+
+Say you have been working on some extremely
+experimental software, based on whatever revision you
+happened to checkout last week. If others in your
+group would like to work on this software with you, but
+without disturbing main-line development, you could
+commit your change to a new branch. Others can then
+checkout your experimental stuff and utilize the full
+benefit of @sc{cvs} conflict resolution. The scenario might
+look like:
+
address@hidden FIXME: Should we be recommending tagging the branchpoint?
address@hidden
+[[ hacked sources are present ]]
+$ cvs tag -b EXPR1
+$ cvs update -r EXPR1
+$ cvs commit
address@hidden example
+
+The @code{update} command will make the @samp{-r
+EXPR1} option sticky on all files. Note that your
+changes to the files will never be removed by the
address@hidden command. The @code{commit} will
+automatically commit to the correct branch, because the
address@hidden is sticky. You could also do like this:
+
address@hidden FIXME: Should we be recommending tagging the branchpoint?
address@hidden
+[[ hacked sources are present ]]
+$ cvs tag -b EXPR1
+$ cvs commit -r EXPR1
address@hidden example
+
address@hidden
+but then, only those files that were changed by you
+will have the @samp{-r EXPR1} sticky flag. If you hack
+away, and commit without specifying the @samp{-r EXPR1}
+flag, some files may accidentally end up on the main
+trunk.
+
+To work with you on the experimental change, others
+would simply do
+
address@hidden
+$ cvs checkout -r EXPR1 whatever_module
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden diff
address@hidden diff---Show differences between revisions
address@hidden diff (subcommand)
+
address@hidden @bullet
address@hidden
+Synopsis: diff [-lR] [-k kflag] [format_options] [[-r rev1 | -D date1] [-r
rev2 | -D date2]] address@hidden
address@hidden
+Requires: working directory, repository.
address@hidden
+Changes: nothing.
address@hidden itemize
+
+The @code{diff} command is used to compare different
+revisions of files. The default action is to compare
+your working files with the revisions they were based
+on, and report any differences that are found.
+
+If any file names are given, only those files are
+compared. If any directories are given, all files
+under them will be compared.
+
+The exit status for diff is different than for other
address@hidden commands; for details @ref{Exit status}.
+
address@hidden
+* diff options:: diff options
+* diff examples:: diff examples
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden diff options
address@hidden diff options
+
+These standard options are supported by @code{diff}
+(@pxref{Common options}, for a complete description of
+them):
+
address@hidden @code
address@hidden -D @var{date}
+Use the most recent revision no later than @var{date}.
+See @samp{-r} for how this affects the comparison.
+
address@hidden -k @var{kflag}
+Process keywords according to @var{kflag}. See
address@hidden substitution}.
+
address@hidden -l
+Local; run only in current working directory.
+
address@hidden -R
+Examine directories recursively. This option is on by
+default.
+
address@hidden -r @var{tag}
+Compare with revision @var{tag}. Zero, one or two
address@hidden options can be present. With no @samp{-r}
+option, the working file will be compared with the
+revision it was based on. With one @samp{-r}, that
+revision will be compared to your current working file.
+With two @samp{-r} options those two revisions will be
+compared (and your working file will not affect the
+outcome in any way).
address@hidden We should be a lot more explicit, with examples,
address@hidden about the difference between "cvs diff" and "cvs
address@hidden diff -r HEAD". This often confuses new users.
+
+One or both @samp{-r} options can be replaced by a
address@hidden @var{date}} option, described above.
address@hidden table
+
address@hidden Conceptually, this is a disaster. There are 3
address@hidden zillion diff formats that we support via the diff
address@hidden library. It is not obvious to me that we should
address@hidden document them all. Maybe just the most common ones
address@hidden like -c and -u, and think about phasing out the
address@hidden obscure ones.
address@hidden FIXCVS: also should be a way to specify an external
address@hidden diff program (which can be different for different
address@hidden file types) and pass through
address@hidden arbitrary options, so that the user can do
address@hidden "--pass=-Z --pass=foo" or something even if CVS
address@hidden doesn't know about the "-Z foo" option to diff.
address@hidden This would fit nicely with deprecating/eliminating
address@hidden the obscure options of the diff library, because it
address@hidden would let people specify an external GNU diff if
address@hidden they are into that sort of thing.
+The following options specify the format of the
+output. They have the same meaning as in GNU diff.
+Most options have two equivalent names, one of which is a single letter
+preceded by @samp{-}, and the other of which is a long name preceded by
address@hidden
+
address@hidden @samp
address@hidden address@hidden
+Show @var{lines} (an integer) lines of context. This option does not
+specify an output format by itself; it has no effect unless it is
+combined with @samp{-c} or @samp{-u}. This option is obsolete. For proper
+operation, @code{patch} typically needs at least two lines of context.
+
address@hidden -a
+Treat all files as text and compare them line-by-line, even if they
+do not seem to be text.
+
address@hidden -b
+Ignore trailing white space and consider all other sequences of one or
+more white space characters to be equivalent.
+
address@hidden -B
+Ignore changes that just insert or delete blank lines.
+
address@hidden --binary
+Read and write data in binary mode.
+
address@hidden --brief
+Report only whether the files differ, not the details of the
+differences.
+
address@hidden -c
+Use the context output format.
+
address@hidden -C @var{lines}
address@hidden address@hidden@address@hidden
+Use the context output format, showing @var{lines} (an integer) lines of
+context, or three if @var{lines} is not given.
+For proper operation, @code{patch} typically needs at least two lines of
+context.
+
address@hidden address@hidden
+Use @var{format} to output a line group containing differing lines from
+both files in if-then-else format. @xref{Line group formats}.
+
address@hidden -d
+Change the algorithm to perhaps find a smaller set of changes. This makes
address@hidden slower (sometimes much slower).
+
address@hidden -e
address@hidden --ed
+Make output that is a valid @code{ed} script.
+
address@hidden --expand-tabs
+Expand tabs to spaces in the output, to preserve the alignment of tabs
+in the input files.
+
address@hidden -f
+Make output that looks vaguely like an @code{ed} script but has changes
+in the order they appear in the file.
+
address@hidden -F @var{regexp}
+In context and unified format, for each hunk of differences, show some
+of the last preceding line that matches @var{regexp}.
+
address@hidden --forward-ed
+Make output that looks vaguely like an @code{ed} script but has changes
+in the order they appear in the file.
+
address@hidden -H
+Use heuristics to speed handling of large files that have numerous
+scattered small changes.
+
address@hidden address@hidden
+Do not discard the last @var{lines} lines of the common prefix
+and the first @var{lines} lines of the common suffix.
+
address@hidden -i
+Ignore changes in case; consider upper- and lower-case letters
+equivalent.
+
address@hidden -I @var{regexp}
+Ignore changes that just insert or delete lines that match @var{regexp}.
+
address@hidden address@hidden
+Make merged if-then-else output using @var{name}.
+
address@hidden --ignore-all-space
+Ignore white space when comparing lines.
+
address@hidden --ignore-blank-lines
+Ignore changes that just insert or delete blank lines.
+
address@hidden --ignore-case
+Ignore changes in case; consider upper- and lower-case to be the same.
+
address@hidden address@hidden
+Ignore changes that just insert or delete lines that match @var{regexp}.
+
address@hidden --ignore-space-change
+Ignore trailing white space and consider all other sequences of one or
+more white space characters to be equivalent.
+
address@hidden --initial-tab
+Output a tab rather than a space before the text of a line in normal or
+context format. This causes the alignment of tabs in the line to look
+normal.
+
address@hidden -L @var{label}
+Use @var{label} instead of the file name in the context format
+and unified format headers.
+
address@hidden address@hidden
+Use @var{label} instead of the file name in the context format
+and unified format headers.
+
address@hidden --left-column
+Print only the left column of two common lines in side by side format.
+
address@hidden address@hidden
+Use @var{format} to output all input lines in if-then-else format.
address@hidden formats}.
+
address@hidden --minimal
+Change the algorithm to perhaps find a smaller set of changes. This
+makes @code{diff} slower (sometimes much slower).
+
address@hidden -n
+Output RCS-format diffs; like @samp{-f} except that each command
+specifies the number of lines affected.
+
address@hidden -N
address@hidden --new-file
+In directory comparison, if a file is found in only one directory,
+treat it as present but empty in the other directory.
+
address@hidden address@hidden
+Use @var{format} to output a group of lines taken from just the second
+file in if-then-else format. @xref{Line group formats}.
+
address@hidden address@hidden
+Use @var{format} to output a line taken from just the second file in
+if-then-else format. @xref{Line formats}.
+
address@hidden address@hidden
+Use @var{format} to output a group of lines taken from just the first
+file in if-then-else format. @xref{Line group formats}.
+
address@hidden address@hidden
+Use @var{format} to output a line taken from just the first file in
+if-then-else format. @xref{Line formats}.
+
address@hidden -p
+Show which C function each change is in.
+
address@hidden --rcs
+Output RCS-format diffs; like @samp{-f} except that each command
+specifies the number of lines affected.
+
address@hidden --report-identical-files
address@hidden -s
+Report when two files are the same.
+
address@hidden --show-c-function
+Show which C function each change is in.
+
address@hidden address@hidden
+In context and unified format, for each hunk of differences, show some
+of the last preceding line that matches @var{regexp}.
+
address@hidden --side-by-side
+Use the side by side output format.
+
address@hidden --speed-large-files
+Use heuristics to speed handling of large files that have numerous
+scattered small changes.
+
address@hidden --suppress-common-lines
+Do not print common lines in side by side format.
+
address@hidden -t
+Expand tabs to spaces in the output, to preserve the alignment of tabs
+in the input files.
+
address@hidden -T
+Output a tab rather than a space before the text of a line in normal or
+context format. This causes the alignment of tabs in the line to look
+normal.
+
address@hidden --text
+Treat all files as text and compare them line-by-line, even if they
+do not appear to be text.
+
address@hidden -u
+Use the unified output format.
+
address@hidden address@hidden
+Use @var{format} to output a group of common lines taken from both files
+in if-then-else format. @xref{Line group formats}.
+
address@hidden address@hidden
+Use @var{format} to output a line common to both files in if-then-else
+format. @xref{Line formats}.
+
address@hidden -U @var{lines}
address@hidden address@hidden@address@hidden
+Use the unified output format, showing @var{lines} (an integer) lines of
+context, or three if @var{lines} is not given.
+For proper operation, @code{patch} typically needs at least two lines of
+context.
+
address@hidden -w
+Ignore white space when comparing lines.
+
address@hidden -W @var{columns}
address@hidden address@hidden
+Use an output width of @var{columns} in side by side format.
+
address@hidden -y
+Use the side by side output format.
address@hidden table
+
address@hidden
+* Line group formats:: Line group formats
+* Line formats:: Line formats
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden Line group formats
address@hidden Line group formats
+
+Line group formats let you specify formats suitable for many
+applications that allow if-then-else input, including programming
+languages and text formatting languages. A line group format specifies
+the output format for a contiguous group of similar lines.
+
+For example, the following command compares the TeX file @file{myfile}
+with the original version from the repository,
+and outputs a merged file in which old regions are
+surrounded by @address@hidden@address@hidden@address@hidden lines, and new
+regions are surrounded by @address@hidden@address@hidden@address@hidden lines.
+
address@hidden
+cvs diff \
+ --old-group-format='address@hidden@}
+%<address@hidden@}
+' \
+ --new-group-format='address@hidden@}
+%>address@hidden@}
+' \
+ myfile
address@hidden example
+
+The following command is equivalent to the above example, but it is a
+little more verbose, because it spells out the default line group formats.
+
address@hidden
+cvs diff \
+ --old-group-format='address@hidden@}
+%<address@hidden@}
+' \
+ --new-group-format='address@hidden@}
+%>address@hidden@}
+' \
+ --unchanged-group-format='%=' \
+ --changed-group-format='address@hidden@}
+%<address@hidden@}
address@hidden@}
+%>address@hidden@}
+' \
+ myfile
address@hidden example
+
+Here is a more advanced example, which outputs a diff listing with
+headers containing line numbers in a ``plain English'' style.
+
address@hidden
+cvs diff \
+ --unchanged-group-format='' \
+ --old-group-format='-------- %dn line%(n=1?:s) deleted at %df:
+%<' \
+ --new-group-format='-------- %dN line%(N=1?:s) added after %de:
+%>' \
+ --changed-group-format='-------- %dn line%(n=1?:s) changed at %df:
+%<-------- to:
+%>' \
+ myfile
address@hidden example
+
+To specify a line group format, use one of the options
+listed below. You can specify up to four line group formats, one for
+each kind of line group. You should quote @var{format}, because it
+typically contains shell metacharacters.
+
address@hidden @samp
address@hidden address@hidden
+These line groups are hunks containing only lines from the first file.
+The default old group format is the same as the changed group format if
+it is specified; otherwise it is a format that outputs the line group as-is.
+
address@hidden address@hidden
+These line groups are hunks containing only lines from the second
+file. The default new group format is same as the changed group
+format if it is specified; otherwise it is a format that outputs the
+line group as-is.
+
address@hidden address@hidden
+These line groups are hunks containing lines from both files. The
+default changed group format is the concatenation of the old and new
+group formats.
+
address@hidden address@hidden
+These line groups contain lines common to both files. The default
+unchanged group format is a format that outputs the line group as-is.
address@hidden table
+
+In a line group format, ordinary characters represent themselves;
+conversion specifications start with @samp{%} and have one of the
+following forms.
+
address@hidden @samp
address@hidden %<
+stands for the lines from the first file, including the trailing newline.
+Each line is formatted according to the old line format (@pxref{Line formats}).
+
address@hidden %>
+stands for the lines from the second file, including the trailing newline.
+Each line is formatted according to the new line format.
+
address@hidden %=
+stands for the lines common to both files, including the trailing newline.
+Each line is formatted according to the unchanged line format.
+
address@hidden %%
+stands for @samp{%}.
+
address@hidden %c'@var{C}'
+where @var{C} is a single character, stands for @var{C}.
address@hidden may not be a backslash or an apostrophe.
+For example, @samp{%c':'} stands for a colon, even inside
+the then-part of an if-then-else format, which a colon would
+normally terminate.
+
address@hidden %c'address@hidden'
+where @var{O} is a string of 1, 2, or 3 octal digits,
+stands for the character with octal code @var{O}.
+For example, @samp{%c'\0'} stands for a null character.
+
address@hidden @address@hidden
+where @var{F} is a @code{printf} conversion specification and @var{n} is one
+of the following letters, stands for @var{n}'s value formatted with @var{F}.
+
address@hidden @samp
address@hidden e
+The line number of the line just before the group in the old file.
+
address@hidden f
+The line number of the first line in the group in the old file;
+equals @var{e} + 1.
+
address@hidden l
+The line number of the last line in the group in the old file.
+
address@hidden m
+The line number of the line just after the group in the old file;
+equals @var{l} + 1.
+
address@hidden n
+The number of lines in the group in the old file; equals @var{l} - @var{f} + 1.
+
address@hidden E, F, L, M, N
+Likewise, for lines in the new file.
+
address@hidden table
+
+The @code{printf} conversion specification can be @samp{%d},
address@hidden, @samp{%x}, or @samp{%X}, specifying decimal, octal,
+lower case hexadecimal, or upper case hexadecimal output
+respectively. After the @samp{%} the following options can appear in
+sequence: a @samp{-} specifying left-justification; an integer
+specifying the minimum field width; and a period followed by an
+optional integer specifying the minimum number of digits.
+For example, @samp{%5dN} prints the number of new lines in the group
+in a field of width 5 characters, using the @code{printf} format @code{"%5d"}.
+
address@hidden (@address@hidden@var{T}:@var{E})
+If @var{A} equals @var{B} then @var{T} else @var{E}.
address@hidden and @var{B} are each either a decimal constant
+or a single letter interpreted as above.
+This format spec is equivalent to @var{T} if
address@hidden's value equals @var{B}'s; otherwise it is equivalent to @var{E}.
+
+For example, @samp{%(N=0?no:%dN) line%(N=1?:s)} is equivalent to
address@hidden lines} if @var{N} (the number of lines in the group in the
+new file) is 0, to @samp{1 line} if @var{N} is 1, and to @samp{%dN lines}
+otherwise.
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden Line formats
address@hidden Line formats
+
+Line formats control how each line taken from an input file is
+output as part of a line group in if-then-else format.
+
+For example, the following command outputs text with a one-column
+change indicator to the left of the text. The first column of output
+is @samp{-} for deleted lines, @samp{|} for added lines, and a space
+for unchanged lines. The formats contain newline characters where
+newlines are desired on output.
+
address@hidden
+cvs diff \
+ --old-line-format='-%l
+' \
+ --new-line-format='|%l
+' \
+ --unchanged-line-format=' %l
+' \
+ myfile
address@hidden example
+
+To specify a line format, use one of the following options. You should
+quote @var{format}, since it often contains shell metacharacters.
+
address@hidden @samp
address@hidden address@hidden
+formats lines just from the first file.
+
address@hidden address@hidden
+formats lines just from the second file.
+
address@hidden address@hidden
+formats lines common to both files.
+
address@hidden address@hidden
+formats all lines; in effect, it sets all three above options simultaneously.
address@hidden table
+
+In a line format, ordinary characters represent themselves;
+conversion specifications start with @samp{%} and have one of the
+following forms.
+
address@hidden @samp
address@hidden %l
+stands for the contents of the line, not counting its trailing
+newline (if any). This format ignores whether the line is incomplete.
+
address@hidden %L
+stands for the contents of the line, including its trailing newline
+(if any). If a line is incomplete, this format preserves its
+incompleteness.
+
address@hidden %%
+stands for @samp{%}.
+
address@hidden %c'@var{C}'
+where @var{C} is a single character, stands for @var{C}.
address@hidden may not be a backslash or an apostrophe.
+For example, @samp{%c':'} stands for a colon.
+
address@hidden %c'address@hidden'
+where @var{O} is a string of 1, 2, or 3 octal digits,
+stands for the character with octal code @var{O}.
+For example, @samp{%c'\0'} stands for a null character.
+
address@hidden @var{F}n
+where @var{F} is a @code{printf} conversion specification,
+stands for the line number formatted with @var{F}.
+For example, @samp{%.5dn} prints the line number using the
address@hidden format @code{"%.5d"}. @xref{Line group formats}, for
+more about printf conversion specifications.
+
address@hidden table
+
+The default line format is @samp{%l} followed by a newline character.
+
+If the input contains tab characters and it is important that they line
+up on output, you should ensure that @samp{%l} or @samp{%L} in a line
+format is just after a tab stop (e.g.@: by preceding @samp{%l} or
address@hidden with a tab character), or you should use the @samp{-t} or
address@hidden option.
+
+Taken together, the line and line group formats let you specify many
+different formats. For example, the following command uses a format
+similar to @code{diff}'s normal format. You can tailor this command
+to get fine control over @code{diff}'s output.
+
address@hidden
+cvs diff \
+ --old-line-format='< %l
+' \
+ --new-line-format='> %l
+' \
+ --old-group-format='%df%(f=l?:,%dl)d%dE
+%<' \
+ --new-group-format='%dea%dF%(F=L?:,%dL)
+%>' \
+ --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL)
+%<---
+%>' \
+ --unchanged-group-format='' \
+ myfile
address@hidden example
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden diff examples
address@hidden diff examples
+
+The following line produces a Unidiff (@samp{-u} flag)
+between revision 1.14 and 1.19 of
address@hidden Due to the @samp{-kk} flag no
+keywords are substituted, so differences that only depend
+on keyword substitution are ignored.
+
address@hidden
+$ cvs diff -kk -u -r 1.14 -r 1.19 backend.c
address@hidden example
+
+Suppose the experimental branch EXPR1 was based on a
+set of files tagged RELEASE_1_0. To see what has
+happened on that branch, the following can be used:
+
address@hidden
+$ cvs diff -r RELEASE_1_0 -r EXPR1
address@hidden example
+
+A command like this can be used to produce a context
+diff between two releases:
+
address@hidden
+$ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs
address@hidden example
+
+If you are maintaining ChangeLogs, a command like the following
+just before you commit your changes may help you write
+the ChangeLog entry. All local modifications that have
+not yet been committed will be printed.
+
address@hidden
+$ cvs diff -u | less
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden export
address@hidden export---Export sources from CVS, similar to checkout
address@hidden export (subcommand)
+
address@hidden @bullet
address@hidden
+Synopsis: export [-flNnR] [-r rev|-D date] [-k subst] [-d dir] address@hidden
address@hidden
+Requires: repository.
address@hidden
+Changes: current directory.
address@hidden itemize
+
+This command is a variant of @code{checkout}; use it
+when you want a copy of the source for module without
+the @sc{cvs} administrative directories. For example, you
+might use @code{export} to prepare source for shipment
+off-site. This command requires that you specify a
+date or tag (with @samp{-D} or @samp{-r}), so that you
+can count on reproducing the source you ship to others
+(and thus it always prunes empty directories).
+
+One often would like to use @samp{-kv} with @code{cvs
+export}. This causes any keywords to be
+expanded such that an import done at some other site
+will not lose the keyword revision information. But be
+aware that doesn't handle an export containing binary
+files correctly. Also be aware that after having used
address@hidden, one can no longer use the @code{ident}
+command (which is part of the @sc{rcs} suite---see
+ident(1)) which looks for keyword strings. If
+you want to be able to use @code{ident} you must not
+use @samp{-kv}.
+
address@hidden
+* export options:: export options
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden export options
address@hidden export options
+
+These standard options are supported by @code{export}
+(@pxref{Common options}, for a complete description of
+them):
+
address@hidden @code
address@hidden -D @var{date}
+Use the most recent revision no later than @var{date}.
+
address@hidden -f
+If no matching revision is found, retrieve the most
+recent revision (instead of ignoring the file).
+
address@hidden -l
+Local; run only in current working directory.
+
address@hidden -n
+Do not run any checkout program.
+
address@hidden -R
+Export directories recursively. This is on by default.
+
address@hidden -r @var{tag}
+Use revision @var{tag}.
address@hidden table
+
+In addition, these options (that are common to
address@hidden and @code{export}) are also supported:
+
address@hidden @code
address@hidden -d @var{dir}
+Create a directory called @var{dir} for the working
+files, instead of using the module name.
address@hidden options}, for complete details on how
address@hidden handles this flag.
+
address@hidden -k @var{subst}
+Set keyword expansion mode (@pxref{Substitution modes}).
+
address@hidden -N
+Only useful together with @samp{-d @var{dir}}.
address@hidden options}, for complete details on how
address@hidden handles this flag.
address@hidden table
+
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden history
address@hidden history---Show status of files and users
address@hidden history (subcommand)
+
address@hidden @bullet
address@hidden
+Synopsis: history [-report] [-flags] [-options args] address@hidden
address@hidden
+Requires: the file @file{$CVSROOT/CVSROOT/history}
address@hidden
+Changes: nothing.
address@hidden itemize
+
address@hidden can keep a history file that tracks each use of the
address@hidden, @code{commit}, @code{rtag},
address@hidden, and @code{release} commands. You can
+use @code{history} to display this information in
+various formats.
+
+Logging must be enabled by creating the file
address@hidden/CVSROOT/history}.
+
address@hidden: @code{history} uses @samp{-f}, @samp{-l},
address@hidden, and @samp{-p} in ways that conflict with the
+normal use inside @sc{cvs} (@pxref{Common options}).}
+
address@hidden
+* history options:: history options
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden history options
address@hidden history options
+
+Several options (shown above as @samp{-report}) control what
+kind of report is generated:
+
address@hidden @code
address@hidden -c
+Report on each time commit was used (i.e., each time
+the repository was modified).
+
address@hidden -e
+Everything (all record types). Equivalent to
+specifying @samp{-x} with all record types. Of course,
address@hidden will also include record types which are
+added in a future version of @sc{cvs}; if you are
+writing a script which can only handle certain record
+types, you'll want to specify @samp{-x}.
+
address@hidden -m @var{module}
+Report on a particular module. (You can meaningfully
+use @samp{-m} more than once on the command line.)
+
address@hidden -o
+Report on checked-out modules. This is the default report type.
+
address@hidden -T
+Report on all tags.
+
address@hidden -x @var{type}
+Extract a particular set of record types @var{type} from the @sc{cvs}
+history. The types are indicated by single letters,
+which you may specify in combination.
+
+Certain commands have a single record type:
+
address@hidden @code
address@hidden F
+release
address@hidden O
+checkout
address@hidden E
+export
address@hidden T
+rtag
address@hidden table
+
address@hidden
+One of four record types may result from an update:
+
address@hidden @code
address@hidden C
+A merge was necessary but collisions were
+detected (requiring manual merging).
address@hidden G
+A merge was necessary and it succeeded.
address@hidden U
+A working file was copied from the repository.
address@hidden W
+The working copy of a file was deleted during
+update (because it was gone from the repository).
address@hidden table
+
address@hidden
+One of three record types results from commit:
+
address@hidden @code
address@hidden A
+A file was added for the first time.
address@hidden M
+A file was modified.
address@hidden R
+A file was removed.
address@hidden table
address@hidden table
+
+The options shown as @samp{-flags} constrain or expand
+the report without requiring option arguments:
+
address@hidden @code
address@hidden -a
+Show data for all users (the default is to show data
+only for the user executing @code{history}).
+
address@hidden -l
+Show last modification only.
+
address@hidden -w
+Show only the records for modifications done from the
+same working directory where @code{history} is
+executing.
address@hidden table
+
+The options shown as @samp{-options @var{args}} constrain the report
+based on an argument:
+
address@hidden @code
address@hidden -b @var{str}
+Show data back to a record containing the string
address@hidden in either the module name, the file name, or
+the repository path.
+
address@hidden -D @var{date}
+Show data since @var{date}. This is slightly different
+from the normal use of @samp{-D @var{date}}, which
+selects the newest revision older than @var{date}.
+
address@hidden -f @var{file}
+Show data for a particular file
+(you can specify several @samp{-f} options on the same command line).
+This is equivalent to specifying the file on the command line.
+
address@hidden -n @var{module}
+Show data for a particular module
+(you can specify several @samp{-n} options on the same command line).
+
address@hidden -p @var{repository}
+Show data for a particular source repository (you
+can specify several @samp{-p} options on the same command
+line).
+
address@hidden -r @var{rev}
+Show records referring to revisions since the revision
+or tag named @var{rev} appears in individual @sc{rcs}
+files. Each @sc{rcs} file is searched for the revision or
+tag.
+
address@hidden -t @var{tag}
+Show records since tag @var{tag} was last added to the
+history file. This differs from the @samp{-r} flag
+above in that it reads only the history file, not the
address@hidden files, and is much faster.
+
address@hidden -u @var{name}
+Show records for user @var{name}.
+
address@hidden -z @var{timezone}
+Show times in the selected records using the specified
+time zone instead of UTC.
address@hidden table
+
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden import
address@hidden import---Import sources into CVS, using vendor branches
address@hidden import (subcommand)
+
address@hidden FIXME: This node is way too long for one which has subnodes.
+
address@hidden @bullet
address@hidden
+Synopsis: import [-options] repository vendortag address@hidden
address@hidden
+Requires: Repository, source distribution directory.
address@hidden
+Changes: repository.
address@hidden itemize
+
+Use @code{import} to incorporate an entire source
+distribution from an outside source (e.g., a source
+vendor) into your source repository directory. You can
+use this command both for initial creation of a
+repository, and for wholesale updates to the module
+from the outside source. @xref{Tracking sources}, for
+a discussion on this subject.
+
+The @var{repository} argument gives a directory name
+(or a path to a directory) under the @sc{cvs} root directory
+for repositories; if the directory did not exist,
+import creates it.
+
+When you use import for updates to source that has been
+modified in your source repository (since a prior
+import), it will notify you of any files that conflict
+in the two branches of development; use @samp{checkout
+-j} to reconcile the differences, as import instructs
+you to do.
+
+If @sc{cvs} decides a file should be ignored
+(@pxref{cvsignore}), it does not import it and prints
address@hidden } followed by the filename (@pxref{import output}, for a
+complete description of the output).
+
+If the file @file{$CVSROOT/CVSROOT/cvswrappers} exists,
+any file whose names match the specifications in that
+file will be treated as packages and the appropriate
+filtering will be performed on the file/directory
+before being imported. @xref{Wrappers}.
+
+The outside source is saved in a first-level
+branch, by default 1.1.1. Updates are leaves of this
+branch; for example, files from the first imported
+collection of source will be revision 1.1.1.1, then
+files from the first imported update will be revision
+1.1.1.2, and so on.
+
+At least three arguments are required.
address@hidden is needed to identify the collection
+of source. @var{vendortag} is a tag for the entire
+branch (e.g., for 1.1.1). You must also specify at
+least one @var{releasetag} to identify the files at
+the leaves created each time you execute @code{import}.
+
address@hidden I'm not completely sure this belongs here. But
address@hidden we need to say it _somewhere_ reasonably obvious; it
address@hidden is a common misconception among people first learning CVS
+Note that @code{import} does @emph{not} change the
+directory in which you invoke it. In particular, it
+does not set up that directory as a @sc{cvs} working
+directory; if you want to work with the sources import
+them first and then check them out into a different
+directory (@pxref{Getting the source}).
+
address@hidden
+* import options:: import options
+* import output:: import output
+* import examples:: import examples
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden import options
address@hidden import options
+
+This standard option is supported by @code{import}
+(@pxref{Common options}, for a complete description):
+
address@hidden @code
address@hidden -m @var{message}
+Use @var{message} as log information, instead of
+invoking an editor.
address@hidden table
+
+There are the following additional special options.
+
address@hidden @code
address@hidden -b @var{branch}
+See @ref{Multiple vendor branches}.
+
address@hidden -k @var{subst}
+Indicate the keyword expansion mode desired. This
+setting will apply to all files created during the
+import, but not to any files that previously existed in
+the repository. See @ref{Substitution modes}, for a
+list of valid @samp{-k} settings.
+
address@hidden -I @var{name}
+Specify file names that should be ignored during
+import. You can use this option repeatedly. To avoid
+ignoring any files at all (even those ignored by
+default), specify `-I !'.
+
address@hidden can be a file name pattern of the same type
+that you can specify in the @file{.cvsignore} file.
address@hidden
address@hidden -- Is this really true?
+
address@hidden -W @var{spec}
+Specify file names that should be filtered during
+import. You can use this option repeatedly.
+
address@hidden can be a file name pattern of the same type
+that you can specify in the @file{.cvswrappers}
+file. @xref{Wrappers}.
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden import output
address@hidden import output
+
address@hidden keeps you informed of its progress by printing a line
+for each file, preceded by one character indicating the status of the file:
+
address@hidden @code
address@hidden U @var{file}
+The file already exists in the repository and has not been locally
+modified; a new revision has been created (if necessary).
+
address@hidden N @var{file}
+The file is a new file which has been added to the repository.
+
address@hidden C @var{file}
+The file already exists in the repository but has been locally modified;
+you will have to merge the changes.
+
address@hidden I @var{file}
+The file is being ignored (@pxref{cvsignore}).
+
address@hidden Symbolic link, importing
address@hidden Link, symbolic, importing
address@hidden FIXME: also (somewhere else) probably
address@hidden should be documenting what happens if you "cvs add"
address@hidden a symbolic link. Also maybe what happens if
address@hidden you manually create symbolic links within the
address@hidden repository (? - not sure why we'd want to suggest
address@hidden doing that).
address@hidden L @var{file}
+The file is a symbolic link; @code{cvs import} ignores symbolic links.
+People periodically suggest that this behavior should
+be changed, but if there is a consensus on what it
+should be changed to, it is not apparent.
+(Various options in the @file{modules} file can be used
+to recreate symbolic links on checkout, update, etc.;
address@hidden)
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden import examples
address@hidden import examples
+
+See @ref{Tracking sources}, and @ref{From files}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden log
address@hidden log---Print out log information for files
address@hidden log (subcommand)
+
address@hidden @bullet
address@hidden
+Synopsis: log [options] address@hidden
address@hidden
+Requires: repository, working directory.
address@hidden
+Changes: nothing.
address@hidden itemize
+
+Display log information for files. @code{log} used to
+call the @sc{rcs} utility @code{rlog}. Although this
+is no longer true in the current sources, this history
+determines the format of the output and the options,
+which are not quite in the style of the other @sc{cvs}
+commands.
+
address@hidden Timezone, in output
address@hidden Zone, time, in output
address@hidden Kind of a funny place to document the timezone used
address@hidden in output from commands other than @code{log}.
address@hidden There is also more we need to say about this,
address@hidden including what happens in a client/server environment.
+The output includes the location of the @sc{rcs} file,
+the @dfn{head} revision (the latest revision on the
+trunk), all symbolic names (tags) and some other
+things. For each revision, the revision number, the
+author, the number of lines added/deleted and the log
+message are printed. All times are displayed in
+Coordinated Universal Time (UTC). (Other parts of
address@hidden print times in the local timezone).
address@hidden FIXCVS: need a better way to control the timezone
address@hidden used in output. Previous/current versions of CVS did/do
address@hidden sometimes support -z in RCSINIT, and/or an
address@hidden undocumented (except by reference to 'rlog') -z option
address@hidden to cvs log, but this has not been a consistent,
address@hidden documented feature. Perhaps a new global option,
address@hidden where LT means the client's timezone, which the
address@hidden client then communicates to the server, is the
address@hidden right solution.
+
address@hidden: @code{log} uses @samp{-R} in a way that conflicts
+with the normal use inside @sc{cvs} (@pxref{Common options}).}
+
address@hidden
+* log options:: log options
+* log examples:: log examples
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden log options
address@hidden log options
+
+By default, @code{log} prints all information that is
+available. All other options restrict the output.
+
address@hidden @code
address@hidden -b
+Print information about the revisions on the default
+branch, normally the highest branch on the trunk.
+
address@hidden -d @var{dates}
+Print information about revisions with a checkin
+date/time in the range given by the
+semicolon-separated list of dates. The date formats
+accepted are those accepted by the @samp{-D} option to
+many other @sc{cvs} commands (@pxref{Common options}).
+Dates can be combined into ranges as follows:
+
address@hidden Should we be thinking about accepting ISO8601
address@hidden ranges? For example "1972-09-10/1972-09-12".
address@hidden @code
address@hidden @var{d1}<@var{d2}
address@hidden @var{d2}>@var{d1}
+Select the revisions that were deposited between
address@hidden and @var{d2}.
+
address@hidden <@var{d}
address@hidden @var{d}>
+Select all revisions dated @var{d} or earlier.
+
address@hidden @var{d}<
address@hidden >@var{d}
+Select all revisions dated @var{d} or later.
+
address@hidden @var{d}
+Select the single, latest revision dated @var{d} or
+earlier.
address@hidden table
+
+The @samp{>} or @samp{<} characters may be followed by
address@hidden to indicate an inclusive range rather than an
+exclusive one.
+
+Note that the separator is a semicolon (;).
+
address@hidden -h
+Print only the name of the @sc{rcs} file, name
+of the file in the working directory, head,
+default branch, access list, locks, symbolic names, and
+suffix.
+
address@hidden -l
+Local; run only in current working directory. (Default
+is to run recursively).
+
address@hidden -N
+Do not print the list of tags for this file. This
+option can be very useful when your site uses a lot of
+tags, so rather than "more"'ing over 3 pages of tag
+information, the log information is presented without
+tags at all.
+
address@hidden -R
+Print only the name of the @sc{rcs} file.
+
address@hidden Note that using a bare revision (in addition to not
address@hidden being explicitly documented here) is potentially
address@hidden confusing; it shows the log message to get from the
address@hidden previous revision to that revision. "-r1.3 -r1.6"
address@hidden (equivalent to "-r1.3,1.6") is even worse; it
address@hidden prints the messages to get from 1.2 to 1.3 and 1.5
address@hidden to 1.6. By analogy with "cvs diff", users might
address@hidden expect that it is more like specifying a range.
address@hidden It is not 100% clear to me how much of this should
address@hidden be documented (for example, multiple -r options
address@hidden perhaps could/should be deprecated given the false
address@hidden analogy with "cvs diff").
address@hidden In general, this section should be rewritten to talk
address@hidden about messages to get from revision rev1 to rev2,
address@hidden rather than messages for revision rev2 (that is, the
address@hidden messages are associated with a change not a static
address@hidden revision and failing to make this distinction causes
address@hidden much confusion).
address@hidden address@hidden
+Print information about revisions given in the
+comma-separated list @var{revisions} of revisions and
+ranges. The following table explains the available
+range formats:
+
address@hidden @code
address@hidden @var{rev1}:@var{rev2}
+Revisions @var{rev1} to @var{rev2} (which must be on
+the same branch).
+
address@hidden @var{rev1}::@var{rev2}
+The same, but excluding @var{rev1}.
+
address@hidden :@var{rev}
address@hidden ::@var{rev}
+Revisions from the beginning of the branch up to
+and including @var{rev}.
+
address@hidden @var{rev}:
+Revisions starting with @var{rev} to the end of the
+branch containing @var{rev}.
+
address@hidden @var{rev}::
+Revisions starting just after @var{rev} to the end of the
+branch containing @var{rev}.
+
address@hidden @var{branch}
+An argument that is a branch means all revisions on
+that branch.
+
address@hidden @var{branch1}:@var{branch2}
address@hidden @var{branch1}::@var{branch2}
+A range of branches means all revisions
+on the branches in that range.
+
address@hidden @var{branch}.
+The latest revision in @var{branch}.
address@hidden table
+
+A bare @samp{-r} with no revisions means the latest
+revision on the default branch, normally the trunk.
+There can be no space between the @samp{-r} option and
+its argument.
+
address@hidden -S
+Suppress the header if no revisions are selected.
+
address@hidden -s @var{states}
+Print information about revisions whose state
+attributes match one of the states given in the
+comma-separated list @var{states}.
+
address@hidden -t
+Print the same as @samp{-h}, plus the descriptive text.
+
address@hidden address@hidden
+Print information about revisions checked in by users
+with login names appearing in the comma-separated list
address@hidden If @var{logins} is omitted, the user's
+login is assumed. There can be no space between the
address@hidden option and its argument.
address@hidden table
+
address@hidden prints the intersection of the revisions
+selected with the options @samp{-d}, @samp{-s}, and
address@hidden, intersected with the union of the revisions
+selected by @samp{-b} and @samp{-r}.
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden log examples
address@hidden log examples
+
+Contributed examples are gratefully accepted.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden rdiff
address@hidden rdiff---'patch' format diffs between releases
address@hidden rdiff (subcommand)
+
address@hidden @bullet
address@hidden
+rdiff [-flags] [-V vn] [-r t|-D d [-r t2|-D d2]] address@hidden
address@hidden
+Requires: repository.
address@hidden
+Changes: nothing.
address@hidden
+Synonym: patch
address@hidden itemize
+
+Builds a Larry Wall format patch(1) file between two
+releases, that can be fed directly into the @code{patch}
+program to bring an old release up-to-date with the new
+release. (This is one of the few @sc{cvs} commands that
+operates directly from the repository, and doesn't
+require a prior checkout.) The diff output is sent to
+the standard output device.
+
+You can specify (using the standard @samp{-r} and
address@hidden options) any combination of one or two
+revisions or dates. If only one revision or date is
+specified, the patch file reflects differences between
+that revision or date and the current head revisions in
+the @sc{rcs} file.
+
+Note that if the software release affected is contained
+in more than one directory, then it may be necessary to
+specify the @samp{-p} option to the @code{patch} command when
+patching the old sources, so that @code{patch} is able to find
+the files that are located in other directories.
+
address@hidden
+* rdiff options:: rdiff options
+* rdiff examples:: rdiff examples
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden rdiff options
address@hidden rdiff options
+
+These standard options are supported by @code{rdiff}
+(@pxref{Common options}, for a complete description of
+them):
+
address@hidden @code
address@hidden -D @var{date}
+Use the most recent revision no later than @var{date}.
+
address@hidden -f
+If no matching revision is found, retrieve the most
+recent revision (instead of ignoring the file).
+
address@hidden -l
+Local; don't descend subdirectories.
+
address@hidden -R
+Examine directories recursively. This option is on by default.
+
address@hidden -r @var{tag}
+Use revision @var{tag}.
address@hidden table
+
+In addition to the above, these options are available:
+
address@hidden @code
address@hidden -c
+Use the context diff format. This is the default format.
+
address@hidden -s
+Create a summary change report instead of a patch. The
+summary includes information about files that were
+changed or added between the releases. It is sent to
+the standard output device. This is useful for finding
+out, for example, which files have changed between two
+dates or revisions.
+
address@hidden -t
+A diff of the top two revisions is sent to the standard
+output device. This is most useful for seeing what the
+last change to a file was.
+
address@hidden -u
+Use the unidiff format for the context diffs.
+Remember that old versions
+of the @code{patch} program can't handle the unidiff
+format, so if you plan to post this patch to the net
+you should probably not use @samp{-u}.
+
address@hidden -V @var{vn}
+Expand keywords according to the rules current in
address@hidden version @var{vn} (the expansion format changed with
address@hidden version 5). Note that this option is no
+longer accepted. @sc{cvs} will always expand keywords the
+way that @sc{rcs} version 5 does.
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden rdiff examples
address@hidden rdiff examples
+
+Suppose you receive mail from @t{foo@@example.net} asking for an
+update from release 1.2 to 1.4 of the tc compiler. You
+have no such patches on hand, but with @sc{cvs} that can
+easily be fixed with a command such as this:
+
address@hidden
+$ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \
+$$ Mail -s 'The patches you asked for' foo@@example.net
address@hidden example
+
+Suppose you have made release 1.3, and forked a branch
+called @samp{R_1_3fix} for bugfixes. @samp{R_1_3_1}
+corresponds to release 1.3.1, which was made some time
+ago. Now, you want to see how much development has been
+done on the branch. This command can be used:
+
address@hidden
+$ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name
+cvs rdiff: Diffing module-name
+File ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6
+File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4
+File bar.h,v changed from revision 1.29.2.1 to 1.2
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden release
address@hidden release---Indicate that a Module is no longer in use
address@hidden release (subcommand)
+
address@hidden @bullet
address@hidden
+release [-d] address@hidden
address@hidden
+Requires: Working directory.
address@hidden
+Changes: Working directory, history log.
address@hidden itemize
+
+This command is meant to safely cancel the effect of
address@hidden checkout}. Since @sc{cvs} doesn't lock files, it
+isn't strictly necessary to use this command. You can
+always simply delete your working directory, if you
+like; but you risk losing changes you may have
+forgotten, and you leave no trace in the @sc{cvs} history
+file (@pxref{history file}) that you've abandoned your
+checkout.
+
+Use @samp{cvs release} to avoid these problems. This
+command checks that no uncommitted changes are
+present; that you are executing it from immediately
+above a @sc{cvs} working directory; and that the repository
+recorded for your files is the same as the repository
+defined in the module database.
+
+If all these conditions are true, @samp{cvs release}
+leaves a record of its execution (attesting to your
+intentionally abandoning your checkout) in the @sc{cvs}
+history log.
+
address@hidden
+* release options:: release options
+* release output:: release output
+* release examples:: release examples
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden release options
address@hidden release options
+
+The @code{release} command supports one command option:
+
address@hidden @code
address@hidden -d
+Delete your working copy of the file if the release
+succeeds. If this flag is not given your files will
+remain in your working directory.
+
address@hidden: The @code{release} command deletes
+all directories and files recursively. This
+has the very serious side-effect that any directory
+that you have created inside your checked-out sources,
+and not added to the repository (using the @code{add}
+command; @pxref{Adding files}) will be silently deleted---even
+if it is non-empty!}
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden release output
address@hidden release output
+
+Before @code{release} releases your sources it will
+print a one-line message for any file that is not
+up-to-date.
+
address@hidden @code
address@hidden U @var{file}
address@hidden P @var{file}
+There exists a newer revision of this file in the
+repository, and you have not modified your local copy
+of the file (@samp{U} and @samp{P} mean the same thing).
+
address@hidden A @var{file}
+The file has been added to your private copy of the
+sources, but has not yet been committed to the
+repository. If you delete your copy of the sources
+this file will be lost.
+
address@hidden R @var{file}
+The file has been removed from your private copy of the
+sources, but has not yet been removed from the
+repository, since you have not yet committed the
+removal. @xref{commit}.
+
address@hidden M @var{file}
+The file is modified in your working directory. There
+might also be a newer revision inside the repository.
+
address@hidden ? @var{file}
address@hidden is in your working directory, but does not
+correspond to anything in the source repository, and is
+not in the list of files for @sc{cvs} to ignore (see the
+description of the @samp{-I} option, and
address@hidden). If you remove your working
+sources, this file will be lost.
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden release examples
address@hidden release examples
+
+Release the @file{tc} directory, and delete your local working copy
+of the files.
+
address@hidden
+$ cd .. # @r{You must stand immediately above the}
+ # @r{sources when you issue @samp{cvs release}.}
+$ cvs release -d tc
+You have [0] altered files in this repository.
+Are you sure you want to release (and delete) directory `tc': y
+$
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden update
address@hidden update---Bring work tree in sync with repository
address@hidden update (subcommand)
+
address@hidden @bullet
address@hidden
+update [-ACdflPpR] [-I name] [-j rev [-j rev]] [-k kflag] [-r tag|-D date] [-W
spec] address@hidden
address@hidden
+Requires: repository, working directory.
address@hidden
+Changes: working directory.
address@hidden itemize
+
+After you've run checkout to create your private copy
+of source from the common repository, other developers
+will continue changing the central source. From time
+to time, when it is convenient in your development
+process, you can use the @code{update} command from
+within your working directory to reconcile your work
+with any revisions applied to the source repository
+since your last checkout or update. Without the @code{-C}
+option, @code{update} will also merge any differences
+between the local copy of files and their base revisions
+into any destination revisions specified with @code{-r},
address@hidden, or @code{-A}.
+
address@hidden
+* update options:: update options
+* update output:: update output
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden update options
address@hidden update options
+
+These standard options are available with @code{update}
+(@pxref{Common options}, for a complete description of
+them):
+
address@hidden @code
address@hidden -D date
+Use the most recent revision no later than @var{date}.
+This option is sticky, and implies @samp{-P}.
+See @ref{Sticky tags}, for more information on sticky tags/dates.
+
address@hidden -f
+Only useful with the @samp{-D @var{date}} or @samp{-r
address@hidden flags. If no matching revision is found,
+retrieve the most recent revision (instead of ignoring
+the file).
+
address@hidden -k @var{kflag}
+Process keywords according to @var{kflag}. See
address@hidden substitution}.
+This option is sticky; future updates of
+this file in this working directory will use the same
address@hidden The @code{status} command can be viewed
+to see the sticky options. See @ref{Invoking CVS}, for
+more information on the @code{status} command.
+
address@hidden -l
+Local; run only in current working directory. @xref{Recursive behavior}.
+
address@hidden -P
+Prune empty directories. See @ref{Moving directories}.
+
address@hidden -p
+Pipe files to the standard output.
+
address@hidden -R
+Update directories recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r rev
+Retrieve revision/tag @var{rev}. This option is sticky,
+and implies @samp{-P}.
+See @ref{Sticky tags}, for more information on sticky tags/dates.
address@hidden table
+
address@hidden 800
+These special options are also available with
address@hidden
+
address@hidden @code
address@hidden -A
+Reset any sticky tags, dates, or @samp{-k} options.
+See @ref{Sticky tags}, for more information on sticky tags/dates.
+
address@hidden -C
+Overwrite locally modified files with clean copies from
+the repository (the modified file is saved in
address@hidden@address@hidden, however).
+
address@hidden -d
+Create any directories that exist in the repository if
+they're missing from the working directory. Normally,
address@hidden acts only on directories and files that
+were already enrolled in your working directory.
+
+This is useful for updating directories that were
+created in the repository since the initial checkout;
+but it has an unfortunate side effect. If you
+deliberately avoided certain directories in the
+repository when you created your working directory
+(either through use of a module name or by listing
+explicitly the files and directories you wanted on the
+command line), then updating with @samp{-d} will create
+those directories, which may not be what you want.
+
address@hidden -I @var{name}
+Ignore files whose names match @var{name} (in your
+working directory) during the update. You can specify
address@hidden more than once on the command line to specify
+several files to ignore. Use @samp{-I !} to avoid
+ignoring any files at all. @xref{cvsignore}, for other
+ways to make @sc{cvs} ignore some files.
+
address@hidden address@hidden
+Specify file names that should be filtered during
+update. You can use this option repeatedly.
+
address@hidden can be a file name pattern of the same type
+that you can specify in the @file{.cvswrappers}
+file. @xref{Wrappers}.
+
address@hidden address@hidden
+With two @samp{-j} options, merge changes from the
+revision specified with the first @samp{-j} option to
+the revision specified with the second @samp{j} option,
+into the working directory.
+
+With one @samp{-j} option, merge changes from the
+ancestor revision to the revision specified with the
address@hidden option, into the working directory. The
+ancestor revision is the common ancestor of the
+revision which the working directory is based on, and
+the revision specified in the @samp{-j} option.
+
+Note that using a single @samp{-j @var{tagname}} option rather than
address@hidden @var{branchname}} to merge changes from a branch will
+often not remove files which were removed on the branch.
address@hidden adds and removals}, for more.
+
+In addition, each @samp{-j} option can contain an optional
+date specification which, when used with branches, can
+limit the chosen revision to one within a specific
+date. An optional date is specified by adding a colon
+(:) to the tag:
address@hidden@var{Symbolic_Tag}:@var{Date_Specifier}}.
+
address@hidden and merging}.
+
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden update output
address@hidden update output
+
address@hidden and @code{checkout} keep you informed of
+their progress by printing a line for each file, preceded
+by one character indicating the status of the file:
+
address@hidden @code
address@hidden U @var{file}
+The file was brought up to date with respect to the
+repository. This is done for any file that exists in
+the repository but not in your source, and for files
+that you haven't changed but are not the most recent
+versions available in the repository.
+
address@hidden P @var{file}
+Like @samp{U}, but the @sc{cvs} server sends a patch instead of an entire
+file. This accomplishes the same thing as @samp{U} using less bandwidth.
+
address@hidden A @var{file}
+The file has been added to your private copy of the
+sources, and will be added to the source repository
+when you run @code{commit} on the file. This is a
+reminder to you that the file needs to be committed.
+
address@hidden R @var{file}
+The file has been removed from your private copy of the
+sources, and will be removed from the source repository
+when you run @code{commit} on the file. This is a
+reminder to you that the file needs to be committed.
+
address@hidden M @var{file}
+The file is modified in your working directory.
+
address@hidden can indicate one of two states for a file
+you're working on: either there were no modifications
+to the same file in the repository, so that your file
+remains as you last saw it; or there were modifications
+in the repository as well as in your copy, but they
+were merged successfully, without conflict, in your
+working directory.
+
address@hidden will print some messages if it merges your work,
+and a backup copy of your working file (as it looked
+before you ran @code{update}) will be made. The exact
+name of that file is printed while @code{update} runs.
+
address@hidden C @var{file}
address@hidden .# files
address@hidden __ files (VMS)
+A conflict was detected while trying to merge your
+changes to @var{file} with changes from the source
+repository. @var{file} (the copy in your working
+directory) is now the result of attempting to merge
+the two revisions; an unmodified copy of your file
+is also in your working directory, with the name
address@hidden@address@hidden where @var{revision}
+is the revision that your modified file started
+from. Resolve the conflict as described in
address@hidden example}.
address@hidden "some systems" as in out-of-the-box OSes? Not as
address@hidden far as I know. We need to advise sysadmins as well
address@hidden as users how to set up this kind of purge, if that is
address@hidden what they want.
address@hidden We also might want to think about cleaner solutions,
address@hidden like having CVS remove the .# file once the conflict
address@hidden has been resolved or something like that.
+(Note that some systems automatically purge
+files that begin with @file{.#} if they have not been
+accessed for a few days. If you intend to keep a copy
+of your original file, it is a very good idea to rename
+it.) Under @sc{vms}, the file name starts with
address@hidden rather than @file{.#}.
+
address@hidden ? @var{file}
address@hidden is in your working directory, but does not
+correspond to anything in the source repository, and is
+not in the list of files for @sc{cvs} to ignore (see the
+description of the @samp{-I} option, and
address@hidden).
address@hidden table
+
address@hidden Invoking CVS
address@hidden Quick reference to CVS commands
address@hidden Command reference
address@hidden Reference, commands
address@hidden Invoking CVS
+
+This appendix describes how to invoke @sc{cvs}, with
+references to where each command or feature is
+described in detail. For other references run the
address@hidden --help} command, or see @ref{Index}.
+
+A @sc{cvs} command looks like:
+
address@hidden
+cvs [ @var{global_options} ] @var{command} [ @var{command_options} ] [
@var{command_args} ]
address@hidden example
+
+Global options:
+
address@hidden @code
address@hidden address@hidden
+Specify legal @sc{cvsroot} directory (server only) (not
+in @sc{cvs} 1.9 and older). See @ref{Password
+authentication server}.
+
address@hidden -a
+Authenticate all communication (client only) (not in @sc{cvs}
+1.9 and older). See @ref{Global options}.
+
address@hidden -b
+Specify RCS location (@sc{cvs} 1.9 and older). See
address@hidden options}.
+
address@hidden -d @var{root}
+Specify the @sc{cvsroot}. See @ref{Repository}.
+
address@hidden -e @var{editor}
+Edit messages with @var{editor}. See @ref{Committing
+your changes}.
+
address@hidden -f
+Do not read the @file{~/.cvsrc} file. See @ref{Global
+options}.
+
address@hidden -H
address@hidden --help
+Print a help message. See @ref{Global options}.
+
address@hidden -l
+Do not log in @file{$CVSROOT/CVSROOT/history} file. See @ref{Global
+options}.
+
address@hidden -n
+Do not change any files. See @ref{Global options}.
+
address@hidden -Q
+Be really quiet. See @ref{Global options}.
+
address@hidden -q
+Be somewhat quiet. See @ref{Global options}.
+
address@hidden -r
+Make new working files read-only. See @ref{Global options}.
+
address@hidden -s @address@hidden
+Set a user variable. See @ref{Variables}.
+
address@hidden -T @var{tempdir}
+Put temporary files in @var{tempdir}. See @ref{Global
+options}.
+
address@hidden -t
+Trace @sc{cvs} execution. See @ref{Global options}.
+
address@hidden -v
address@hidden --version
+Display version and copyright information for @sc{cvs}.
+
address@hidden -w
+Make new working files read-write. See @ref{Global
+options}.
+
address@hidden -x
+Encrypt all communication (client only).
+See @ref{Global options}.
+
address@hidden -z @var{gzip-level}
address@hidden Compression
address@hidden Gzip
+Set the compression level (client only).
+See @ref{Global options}.
address@hidden table
+
+Keyword expansion modes (@pxref{Substitution modes}):
+
address@hidden
+-kkv $ Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp $
+-kkvl $ Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
+-kk $ Id$
+-kv file1,v 1.1 1993/12/09 03:21:13 joe Exp
+-ko @i{no expansion}
+-kb @i{no expansion, file is binary}
address@hidden example
+
+Keywords (@pxref{Keyword list}):
+
address@hidden
+$ Author: joe $
+$ Date: 1993/12/09 03:21:13 $
+$ CVSHeader: files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
+$ Header: /home/files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
+$ Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
+$ Locker: harry $
+$ Name: snapshot_1_14 $
+$ RCSfile: file1,v $
+$ Revision: 1.1 $
+$ Source: /home/files/file1,v $
+$ State: Exp $
+$ Log: file1,v $
+Revision 1.1 1993/12/09 03:30:17 joe
+Initial revision
+
address@hidden example
+
address@hidden The idea behind this table is that we want each item
address@hidden to be a sentence or two at most. Preferably a
address@hidden single line.
address@hidden
address@hidden In some cases refs to "foo options" are just to get
address@hidden this thing written quickly, not because the "foo
address@hidden options" node is really the best place to point.
+Commands, command options, and command arguments:
+
address@hidden @code
address@hidden ------------------------------------------------------------
address@hidden add address@hidden address@hidden@dots{}]
+Add a new file/directory. See @ref{Adding files}.
+
address@hidden @code
address@hidden -k @var{kflag}
+Set keyword expansion.
+
address@hidden -m @var{msg}
+Set file description.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden admin address@hidden address@hidden@dots{}]
+Administration of history files in the repository. See
address@hidden
address@hidden This list omits those options which are not
address@hidden documented as being useful with CVS. That might be
address@hidden a mistake...
+
address@hidden @code
address@hidden address@hidden
+Set default branch. See @ref{Reverting local changes}.
+
address@hidden address@hidden
+Set comment leader.
+
address@hidden address@hidden
+Set keyword substitution. See @ref{Keyword
+substitution}.
+
address@hidden address@hidden
+Lock revision @var{rev}, or latest revision.
+
address@hidden address@hidden:@var{msg}
+Replace the log message of revision @var{rev} with
address@hidden
+
address@hidden address@hidden
+Delete revisions from the repository. See
address@hidden options}.
+
address@hidden -q
+Run quietly; do not print diagnostics.
+
address@hidden address@hidden:@var{rev}]
+Set the state.
+
address@hidden Does not work for client/server CVS
address@hidden -t
+Set file description from standard input.
+
address@hidden address@hidden
+Set file description from @var{file}.
+
address@hidden address@hidden
+Set file description to @var{string}.
+
address@hidden address@hidden
+Unlock revision @var{rev}, or latest revision.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden annotate address@hidden address@hidden@dots{}]
+Show last revision where each line was modified. See
address@hidden
+
address@hidden @code
address@hidden -D @var{date}
+Annotate the most recent revision no later than
address@hidden See @ref{Common options}.
+
address@hidden -F
+Force annotation of binary files. (Without this option,
+binary files are skipped with a message.)
+
address@hidden -f
+Use head revision if tag/date not found. See
address@hidden options}.
+
address@hidden -l
+Local; run only in current working directory. @xref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{tag}
+Annotate revision @var{tag}. See @ref{Common options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden checkout address@hidden @address@hidden
+Get a copy of the sources. See @ref{checkout}.
+
address@hidden @code
address@hidden -A
+Reset any sticky tags/date/options. See @ref{Sticky
+tags} and @ref{Keyword substitution}.
+
address@hidden -c
+Output the module database. See @ref{checkout options}.
+
address@hidden -D @var{date}
+Check out revisions as of @var{date} (is sticky). See
address@hidden options}.
+
address@hidden -d @var{dir}
+Check out into @var{dir}. See @ref{checkout options}.
+
address@hidden -f
+Use head revision if tag/date not found. See
address@hidden options}.
+
address@hidden Probably want to use rev1/rev2 style like for diff
address@hidden -r. Here and in on-line help.
address@hidden -j @var{rev}
+Merge in changes. See @ref{checkout options}.
+
address@hidden -k @var{kflag}
+Use @var{kflag} keyword expansion. See
address@hidden modes}.
+
address@hidden -l
+Local; run only in current working directory. @xref{Recursive behavior}.
+
address@hidden -N
+Don't ``shorten'' module paths if -d specified. See
address@hidden options}.
+
address@hidden -n
+Do not run module program (if any). See @ref{checkout options}.
+
address@hidden -P
+Prune empty directories. See @ref{Moving directories}.
+
address@hidden -p
+Check out files to standard output (avoids
+stickiness). See @ref{checkout options}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{tag}
+Checkout revision @var{tag} (is sticky). See @ref{Common options}.
+
address@hidden -s
+Like -c, but include module status. See @ref{checkout options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden commit address@hidden address@hidden@dots{}]
+Check changes into the repository. See @ref{commit}.
+
address@hidden @code
address@hidden -F @var{file}
+Read log message from @var{file}. See @ref{commit options}.
+
address@hidden -f
address@hidden What is this "disables recursion"? It is from the
address@hidden on-line help; is it documented in this manual?
+Force the file to be committed; disables recursion.
+See @ref{commit options}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -m @var{msg}
+Use @var{msg} as log message. See @ref{commit options}.
+
address@hidden -n
+Do not run module program (if any). See @ref{commit options}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{rev}
+Commit to @var{rev}. See @ref{commit options}.
address@hidden FIXME: should be dragging over text from
address@hidden commit options, especially if it can be cleaned up
address@hidden and made concise enough.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden diff address@hidden address@hidden@dots{}]
+Show differences between revisions. See @ref{diff}.
+In addition to the options shown below, accepts a wide
+variety of options to control output style, for example
address@hidden for context diffs.
+
address@hidden @code
address@hidden -D @var{date1}
+Diff revision for date against working file. See
address@hidden options}.
+
address@hidden -D @var{date2}
+Diff @var{rev1}/@var{date1} against @var{date2}. See
address@hidden options}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -N
+Include diffs for added and removed files. See
address@hidden options}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{rev1}
+Diff revision for @var{rev1} against working file. See
address@hidden options}.
+
address@hidden -r @var{rev2}
+Diff @var{rev1}/@var{date1} against @var{rev2}. See @ref{diff options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden edit address@hidden address@hidden@dots{}]
+Get ready to edit a watched file. See @ref{Editing files}.
+
address@hidden @code
address@hidden -a @var{actions}
+Specify actions for temporary watch, where
address@hidden is @code{edit}, @code{unedit},
address@hidden, @code{all}, or @code{none}. See
address@hidden files}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden editors address@hidden address@hidden@dots{}]
+See who is editing a watched file. See @ref{Watch information}.
+
address@hidden @code
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden export address@hidden @address@hidden
+Export files from @sc{cvs}. See @ref{export}.
+
address@hidden @code
address@hidden -D @var{date}
+Check out revisions as of @var{date}. See
address@hidden options}.
+
address@hidden -d @var{dir}
+Check out into @var{dir}. See @ref{export options}.
+
address@hidden -f
+Use head revision if tag/date not found. See
address@hidden options}.
+
address@hidden -k @var{kflag}
+Use @var{kflag} keyword expansion. See
address@hidden modes}.
+
address@hidden -l
+Local; run only in current working directory. @xref{Recursive behavior}.
+
address@hidden -N
+Don't ``shorten'' module paths if -d specified. See
address@hidden options}.
+
address@hidden -n
+Do not run module program (if any). See @ref{export options}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{tag}
+Checkout revision @var{tag}. See @ref{Common options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden history address@hidden address@hidden@dots{}]
+Show repository access history. See @ref{history}.
+
address@hidden @code
address@hidden -a
+All users (default is self). See @ref{history options}.
+
address@hidden -b @var{str}
+Back to record with @var{str} in module/file/repos
+field. See @ref{history options}.
+
address@hidden -c
+Report on committed (modified) files. See @ref{history options}.
+
address@hidden -D @var{date}
+Since @var{date}. See @ref{history options}.
+
address@hidden -e
+Report on all record types. See @ref{history options}.
+
address@hidden -l
+Last modified (committed or modified report). See @ref{history options}.
+
address@hidden -m @var{module}
+Report on @var{module} (repeatable). See @ref{history options}.
+
address@hidden -n @var{module}
+In @var{module}. See @ref{history options}.
+
address@hidden -o
+Report on checked out modules. See @ref{history options}.
+
address@hidden -p @var{repository}
+In @var{repository}. See @ref{history options}.
+
address@hidden -r @var{rev}
+Since revision @var{rev}. See @ref{history options}.
+
address@hidden -T
address@hidden What the @address@hidden is a TAG? Same as a tag? This
address@hidden wording is also in the online-line help.
+Produce report on all TAGs. See @ref{history options}.
+
address@hidden -t @var{tag}
+Since tag record placed in history file (by anyone).
+See @ref{history options}.
+
address@hidden -u @var{user}
+For user @var{user} (repeatable). See @ref{history options}.
+
address@hidden -w
+Working directory must match. See @ref{history options}.
+
address@hidden -x @var{types}
+Report on @var{types}, one or more of
address@hidden See @ref{history options}.
+
address@hidden -z @var{zone}
+Output for time zone @var{zone}. See @ref{history options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden import address@hidden @var{repository} @var{vendor-tag}
@address@hidden
+Import files into @sc{cvs}, using vendor branches. See
address@hidden
+
address@hidden @code
address@hidden -b @var{bra}
+Import to vendor branch @var{bra}. See
address@hidden vendor branches}.
+
address@hidden -d
+Use the file's modification time as the time of
+import. See @ref{import options}.
+
address@hidden -k @var{kflag}
+Set default keyword substitution mode. See
address@hidden options}.
+
address@hidden -m @var{msg}
+Use @var{msg} for log message. See
address@hidden options}.
+
address@hidden -I @var{ign}
+More files to ignore (! to reset). See
address@hidden options}.
+
address@hidden -W @var{spec}
+More wrappers. See @ref{import options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden init
+Create a @sc{cvs} repository if it doesn't exist. See
address@hidden a repository}.
+
address@hidden ------------------------------------------------------------
address@hidden kserver
+Kerberos authenticated server.
+See @ref{Kerberos authenticated}.
+
address@hidden ------------------------------------------------------------
address@hidden log address@hidden address@hidden@dots{}]
+Print out history information for files. See @ref{log}.
+
address@hidden @code
address@hidden -b
+Only list revisions on the default branch. See @ref{log options}.
+
address@hidden -d @var{dates}
+Specify dates (@var{d1}<@var{d2} for range, @var{d} for
+latest before). See @ref{log options}.
+
address@hidden -h
+Only print header. See @ref{log options}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -N
+Do not list tags. See @ref{log options}.
+
address@hidden -R
+Only print name of RCS file. See @ref{log options}.
+
address@hidden address@hidden
+Only list revisions @var{revs}. See @ref{log options}.
+
address@hidden -s @var{states}
+Only list revisions with specified states. See @ref{log options}.
+
address@hidden -t
+Only print header and descriptive text. See @ref{log
+options}.
+
address@hidden address@hidden
+Only list revisions checked in by specified logins. See @ref{log options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden login
+Prompt for password for authenticating server. See
address@hidden authentication client}.
+
address@hidden ------------------------------------------------------------
address@hidden logout
+Remove stored password for authenticating server. See
address@hidden authentication client}.
+
address@hidden ------------------------------------------------------------
address@hidden pserver
+Password authenticated server.
+See @ref{Password authentication server}.
+
address@hidden ------------------------------------------------------------
address@hidden rannotate address@hidden address@hidden@dots{}]
+Show last revision where each line was modified. See
address@hidden
+
address@hidden @code
address@hidden -D @var{date}
+Annotate the most recent revision no later than
address@hidden See @ref{Common options}.
+
address@hidden -F
+Force annotation of binary files. (Without this option,
+binary files are skipped with a message.)
+
address@hidden -f
+Use head revision if tag/date not found. See
address@hidden options}.
+
address@hidden -l
+Local; run only in current working directory. @xref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive behavior}.
+
address@hidden -r @var{tag}
+Annotate revision @var{tag}. See @ref{Common options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden rdiff address@hidden @address@hidden
+Show differences between releases. See @ref{rdiff}.
+
address@hidden @code
address@hidden -c
+Context diff output format (default). See @ref{rdiff options}.
+
address@hidden -D @var{date}
+Select revisions based on @var{date}. See @ref{Common options}.
+
address@hidden -f
+Use head revision if tag/date not found. See
address@hidden options}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{rev}
+Select revisions based on @var{rev}. See @ref{Common options}.
+
address@hidden -s
+Short patch - one liner per file. See @ref{rdiff options}.
+
address@hidden -t
+Top two diffs - last change made to the file. See
address@hidden options}.
+
address@hidden -u
+Unidiff output format. See @ref{rdiff options}.
+
address@hidden -V @var{vers}
+Use RCS Version @var{vers} for keyword expansion (obsolete). See
address@hidden options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden release address@hidden @var{directory}
+Indicate that a directory is no longer in use. See
address@hidden
+
address@hidden @code
address@hidden -d
+Delete the given directory. See @ref{release options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden remove address@hidden address@hidden@dots{}]
+Remove an entry from the repository. See @ref{Removing files}.
+
address@hidden @code
address@hidden -f
+Delete the file before removing it. See @ref{Removing files}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden rlog address@hidden address@hidden@dots{}]
+Print out history information for modules. See @ref{log}.
+
address@hidden @code
address@hidden -b
+Only list revisions on the default branch. See @ref{log options}.
+
address@hidden -d @var{dates}
+Specify dates (@var{d1}<@var{d2} for range, @var{d} for
+latest before). See @ref{log options}.
+
address@hidden -h
+Only print header. See @ref{log options}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -N
+Do not list tags. See @ref{log options}.
+
address@hidden -R
+Only print name of RCS file. See @ref{log options}.
+
address@hidden address@hidden
+Only list revisions @var{revs}. See @ref{log options}.
+
address@hidden -s @var{states}
+Only list revisions with specified states. See @ref{log options}.
+
address@hidden -t
+Only print header and descriptive text. See @ref{log options}.
+
address@hidden address@hidden
+Only list revisions checked in by specified logins. See @ref{log options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden rtag address@hidden @var{tag} @address@hidden
+Add a symbolic tag to a module.
+See @ref{Revisions} and @ref{Branching and merging}.
+
address@hidden @code
address@hidden -a
+Clear tag from removed files that would not otherwise
+be tagged. See @ref{Tagging add/remove}.
+
address@hidden -b
+Create a branch named @var{tag}. See @ref{Branching and merging}.
+
address@hidden -B
+Used in conjunction with -F or -d, enables movement and deletion of
+branch tags. Use with extreme caution.
+
address@hidden -D @var{date}
+Tag revisions as of @var{date}. See @ref{Tagging by date/tag}.
+
address@hidden -d
+Delete @var{tag}. See @ref{Modifying tags}.
+
address@hidden -F
+Move @var{tag} if it already exists. See @ref{Modifying tags}.
+
address@hidden -f
+Force a head revision match if tag/date not found.
+See @ref{Tagging by date/tag}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -n
+No execution of tag program. See @ref{Common options}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{rev}
+Tag existing tag @var{rev}. See @ref{Tagging by date/tag}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden server
+Rsh server. See @ref{Connecting via rsh}.
+
address@hidden ------------------------------------------------------------
address@hidden status address@hidden @address@hidden
+Display status information in a working directory. See
address@hidden status}.
+
address@hidden @code
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -v
+Include tag information for file. See @ref{Tags}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden tag address@hidden @var{tag} address@hidden@dots{}]
+Add a symbolic tag to checked out version of files.
+See @ref{Revisions} and @ref{Branching and merging}.
+
address@hidden @code
address@hidden -b
+Create a branch named @var{tag}. See @ref{Branching and merging}.
+
address@hidden -c
+Check that working files are unmodified. See
address@hidden the working directory}.
+
address@hidden -D @var{date}
+Tag revisions as of @var{date}. See @ref{Tagging by date/tag}.
+
address@hidden -d
+Delete @var{tag}. See @ref{Modifying tags}.
+
address@hidden -F
+Move @var{tag} if it already exists. See @ref{Modifying tags}.
+
address@hidden -f
+Force a head revision match if tag/date not found.
+See @ref{Tagging by date/tag}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{rev}
+Tag existing tag @var{rev}. See @ref{Tagging by date/tag}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden unedit address@hidden address@hidden@dots{}]
+Undo an edit command. See @ref{Editing files}.
+
address@hidden @code
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive behavior}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden update address@hidden address@hidden@dots{}]
+Bring work tree in sync with repository. See
address@hidden
+
address@hidden @code
address@hidden -A
+Reset any sticky tags/date/options. See @ref{Sticky
+tags} and @ref{Keyword substitution}.
+
address@hidden -C
+Overwrite locally modified files with clean copies from
+the repository (the modified file is saved in
address@hidden@address@hidden, however).
+
address@hidden -D @var{date}
+Check out revisions as of @var{date} (is sticky). See
address@hidden options}.
+
address@hidden -d
+Create directories. See @ref{update options}.
+
address@hidden -f
+Use head revision if tag/date not found. See
address@hidden options}.
+
address@hidden -I @var{ign}
+More files to ignore (! to reset). See
address@hidden options}.
+
address@hidden Probably want to use rev1/rev2 style like for diff
address@hidden -r. Here and in on-line help.
address@hidden -j @var{rev}
+Merge in changes. See @ref{update options}.
+
address@hidden -k @var{kflag}
+Use @var{kflag} keyword expansion. See
address@hidden modes}.
+
address@hidden -l
+Local; run only in current working directory. @xref{Recursive behavior}.
+
address@hidden -P
+Prune empty directories. See @ref{Moving directories}.
+
address@hidden -p
+Check out files to standard output (avoids
+stickiness). See @ref{update options}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{tag}
+Checkout revision @var{tag} (is sticky). See @ref{Common options}.
+
address@hidden -W @var{spec}
+More wrappers. See @ref{import options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden version
address@hidden version (subcommand)
+
+Display the version of @sc{cvs} being used. If the repository
+is remote, display both the client and server versions.
+
address@hidden ------------------------------------------------------------
address@hidden watch [on|off|add|remove] address@hidden address@hidden@dots{}]
+
+on/off: turn on/off read-only checkouts of files. See
address@hidden a watch}.
+
+add/remove: add or remove notification on actions. See
address@hidden Notified}.
+
address@hidden @code
address@hidden -a @var{actions}
+Specify actions for temporary watch, where
address@hidden is @code{edit}, @code{unedit},
address@hidden, @code{all}, or @code{none}. See
address@hidden files}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden watchers address@hidden address@hidden@dots{}]
+See who is watching a file. See @ref{Watch information}.
+
address@hidden @code
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
address@hidden table
+
address@hidden table
+
address@hidden
---------------------------------------------------------------------
address@hidden Administrative files
address@hidden Reference manual for Administrative files
address@hidden Administrative files (reference)
address@hidden Files, reference manual
address@hidden Reference manual (files)
address@hidden CVSROOT (file)
+
address@hidden FIXME? Somewhere there needs to be a more "how-to"
address@hidden guide to writing these. I think the triggers
address@hidden (commitinfo, loginfo, taginfo, &c) are perhaps a
address@hidden different case than files like modules. One
address@hidden particular issue that people sometimes are
address@hidden (unnecessarily?) worried about is performance, and
address@hidden the impact of writing in perl or sh or ____.
+Inside the repository, in the directory
address@hidden/CVSROOT}, there are a number of
+supportive files for @sc{cvs}. You can use @sc{cvs} in a limited
+fashion without any of them, but if they are set up
+properly they can help make life easier. For a
+discussion of how to edit them, see @ref{Intro
+administrative files}.
+
+The most important of these files is the @file{modules}
+file, which defines the modules inside the repository.
+
address@hidden
+* modules:: Defining modules
+* Wrappers:: Specify binary-ness based on file name
+* commit files:: The commit support files (commitinfo,
+ verifymsg, editinfo, loginfo)
+* rcsinfo:: Templates for the log messages
+* cvsignore:: Ignoring files via cvsignore
+* checkoutlist:: Adding your own administrative files
+* history file:: History information
+* Variables:: Various variables are expanded
+* config:: Miscellaneous CVS configuration
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden modules
address@hidden The modules file
address@hidden Modules (admin file)
address@hidden Defining modules (reference manual)
+
+The @file{modules} file records your definitions of
+names for collections of source code. @sc{cvs} will
+use these definitions if you use @sc{cvs} to update the
+modules file (use normal commands like @code{add},
address@hidden, etc).
+
+The @file{modules} file may contain blank lines and
+comments (lines beginning with @samp{#}) as well as
+module definitions. Long lines can be continued on the
+next line by specifying a backslash (@samp{\}) as the
+last character on the line.
+
+There are three basic types of modules: alias modules,
+regular modules, and ampersand modules. The difference
+between them is the way that they map files in the
+repository to files in the working directory. In all
+of the following examples, the top-level repository
+contains a directory called @file{first-dir}, which
+contains two files, @file{file1} and @file{file2}, and a
+directory @file{sdir}. @file{first-dir/sdir} contains
+a file @file{sfile}.
+
address@hidden FIXME: should test all the examples in this section.
+
address@hidden
+* Alias modules:: The simplest kind of module
+* Regular modules::
+* Ampersand modules::
+* Excluding directories:: Excluding directories from a module
+* Module options:: Regular and ampersand modules can take options
+* Module program options:: How the modules ``program options'' programs
+ are run.
address@hidden menu
+
address@hidden Alias modules
address@hidden Alias modules
address@hidden Alias modules
address@hidden -a, in modules file
+
+Alias modules are the simplest kind of module:
+
address@hidden @code
address@hidden @var{mname} -a @address@hidden
+This represents the simplest way of defining a module
address@hidden The @samp{-a} flags the definition as a
+simple alias: @sc{cvs} will treat any use of @var{mname} (as
+a command argument) as if the list of names
address@hidden had been specified instead.
address@hidden may contain either other module names or
+paths. When you use paths in aliases, @code{checkout}
+creates all intermediate directories in the working
+directory, just as if the path had been specified
+explicitly in the @sc{cvs} arguments.
address@hidden table
+
+For example, if the modules file contains:
+
address@hidden
+amodule -a first-dir
address@hidden example
+
address@hidden
+then the following two commands are equivalent:
+
address@hidden
+$ cvs co amodule
+$ cvs co first-dir
address@hidden example
+
address@hidden
+and they each would provide output such as:
+
address@hidden
+cvs checkout: Updating first-dir
+U first-dir/file1
+U first-dir/file2
+cvs checkout: Updating first-dir/sdir
+U first-dir/sdir/sfile
address@hidden example
+
address@hidden Regular modules
address@hidden Regular modules
address@hidden Regular modules
+
address@hidden @code
address@hidden @var{mname} [ options ] @var{dir} [ @address@hidden ]
+In the simplest case, this form of module definition
+reduces to @address@hidden @var{dir}}. This defines
+all the files in directory @var{dir} as module mname.
address@hidden is a relative path (from @code{$CVSROOT}) to a
+directory of source in the source repository. In this
+case, on checkout, a single directory called
address@hidden is created as a working directory; no
+intermediate directory levels are used by default, even
+if @var{dir} was a path involving several directory
+levels.
address@hidden table
+
+For example, if a module is defined by:
+
address@hidden
+regmodule first-dir
address@hidden example
+
address@hidden
+then regmodule will contain the files from first-dir:
+
address@hidden
+$ cvs co regmodule
+cvs checkout: Updating regmodule
+U regmodule/file1
+U regmodule/file2
+cvs checkout: Updating regmodule/sdir
+U regmodule/sdir/sfile
+$
address@hidden example
+
+By explicitly specifying files in the module definition
+after @var{dir}, you can select particular files from
+directory @var{dir}. Here is
+an example:
+
address@hidden
+regfiles first-dir/sdir sfile
address@hidden example
+
address@hidden
+With this definition, getting the regfiles module
+will create a single working directory
address@hidden containing the file listed, which
+comes from a directory deeper
+in the @sc{cvs} source repository:
+
address@hidden
+$ cvs co regfiles
+U regfiles/sfile
+$
address@hidden example
+
address@hidden Ampersand modules
address@hidden Ampersand modules
address@hidden Ampersand modules
address@hidden &, in modules file
+
+A module definition can refer to other modules by
+including @samp{&@var{module}} in its definition.
address@hidden
address@hidden [ options ] @var{&address@hidden
address@hidden example
+
+Then getting the module creates a subdirectory for each such
+module, in the directory containing the module. For
+example, if modules contains
+
address@hidden
+ampermod &first-dir
address@hidden example
+
address@hidden
+then a checkout will create an @code{ampermod} directory
+which contains a directory called @code{first-dir},
+which in turns contains all the directories and files
+which live there. For example, the command
+
address@hidden
+$ cvs co ampermod
address@hidden example
+
address@hidden
+will create the following files:
+
address@hidden
+ampermod/first-dir/file1
+ampermod/first-dir/file2
+ampermod/first-dir/sdir/sfile
address@hidden example
+
+There is one quirk/bug: the messages that @sc{cvs}
+prints omit the @file{ampermod}, and thus do not
+correctly display the location to which it is checking
+out the files:
+
address@hidden
+$ cvs co ampermod
+cvs checkout: Updating first-dir
+U first-dir/file1
+U first-dir/file2
+cvs checkout: Updating first-dir/sdir
+U first-dir/sdir/sfile
+$
address@hidden example
+
+Do not rely on this buggy behavior; it may get fixed in
+a future release of @sc{cvs}.
+
address@hidden FIXCVS: What happens if regular and & modules are
address@hidden combined, as in "ampermodule first-dir &second-dir"?
address@hidden When I tried it, it seemed to just ignore the
address@hidden "first-dir". I think perhaps it should be an error
address@hidden (but this needs further investigation).
address@hidden In addition to discussing what each one does, we
address@hidden should put in a few words about why you would use one or
address@hidden the other in various situations.
+
address@hidden Excluding directories
address@hidden Excluding directories
address@hidden Excluding directories, in modules file
address@hidden !, in modules file
+
+An alias module may exclude particular directories from
+other modules by using an exclamation mark (@samp{!})
+before the name of each directory to be excluded.
+
+For example, if the modules file contains:
+
address@hidden
+exmodule -a !first-dir/sdir first-dir
address@hidden example
+
address@hidden
+then checking out the module @samp{exmodule} will check
+out everything in @samp{first-dir} except any files in
+the subdirectory @samp{first-dir/sdir}.
address@hidden Note that the "!first-dir/sdir" sometimes must be listed
address@hidden before "first-dir". That seems like a probable bug, in which
address@hidden case perhaps it should be fixed (to allow either
address@hidden order) rather than documented. See modules4 in testsuite.
+
address@hidden Module options
address@hidden Module options
address@hidden Options, in modules file
+
+Either regular modules or ampersand modules can contain
+options, which supply additional information concerning
+the module.
+
address@hidden @code
address@hidden -d, in modules file
address@hidden -d @var{name}
+Name the working directory something other than the
+module name.
address@hidden FIXME: Needs a bunch of examples, analogous to the
address@hidden examples for alias, regular, and ampersand modules
address@hidden which show where the files go without -d.
+
address@hidden Export program
address@hidden -e, in modules file
address@hidden -e @var{prog}
+Specify a program @var{prog} to run whenever files in a
+module are exported. @var{prog} runs with a single
+argument, the module name.
address@hidden FIXME: Is it run on server? client?
+
address@hidden Checkout program
address@hidden -o, in modules file
address@hidden -o @var{prog}
+Specify a program @var{prog} to run whenever files in a
+module are checked out. @var{prog} runs with a single
+argument, the module name. See @ref{Module program options} for
+information on how @var{prog} is called.
address@hidden FIXME: Is it run on server? client?
+
address@hidden Status of a module
address@hidden Module status
address@hidden -s, in modules file
address@hidden -s @var{status}
+Assign a status to the module. When the module file is
+printed with @samp{cvs checkout -s} the modules are
+sorted according to primarily module status, and
+secondarily according to the module name. This option
+has no other meaning. You can use this option for
+several things besides status: for instance, list the
+person that is responsible for this module.
+
address@hidden Tag program
address@hidden -t, in modules file
address@hidden -t @var{prog}
+Specify a program @var{prog} to run whenever files in a
+module are tagged with @code{rtag}. @var{prog} runs
+with two arguments: the module name and the symbolic
+tag specified to @code{rtag}. It is not run
+when @code{tag} is executed. Generally you will find
+that taginfo is a better solution (@pxref{user-defined logging}).
address@hidden FIXME: Is it run on server? client?
address@hidden Problems with -t include:
address@hidden * It is run after the tag not before
address@hidden * It doesn't get passed all the information that
address@hidden taginfo does ("mov", &c).
address@hidden * It only is run for rtag, not tag.
address@hidden table
+
+You should also see @pxref{Module program options} about how the
+``program options'' programs are run.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
+
address@hidden Module program options
address@hidden How the modules file ``program options'' programs are run
address@hidden Modules file program options
address@hidden -t, in modules file
address@hidden -o, in modules file
address@hidden -e, in modules file
+
address@hidden
+For checkout, rtag, and export, the program is server-based, and as such the
+following applies:-
+
+If using remote access methods (pserver, ext, etc.),
address@hidden will execute this program on the server from a temporary
+directory. The path is searched for this program.
+
+If using ``local access'' (on a local or remote NFS file system, i.e.
+repository set just to a path),
+the program will be executed from the newly checked-out tree, if
+found there, or alternatively searched for in the path if not.
+
+The programs are all run after the operation has effectively
+completed.
+
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Wrappers
address@hidden The cvswrappers file
address@hidden cvswrappers (admin file)
address@hidden CVSWRAPPERS, environment variable
address@hidden Wrappers
+
address@hidden FIXME: need some better way of separating this out
address@hidden by functionality. -m is
address@hidden one feature, and -k is a another. And this discussion
address@hidden should be better motivated (e.g. start with the
address@hidden problems, then explain how the feature solves it).
+
+Wrappers refers to a @sc{cvs} feature which lets you
+control certain settings based on the name of the file
+which is being operated on. The settings are @samp{-k}
+for binary files, and @samp{-m} for nonmergeable text
+files.
+
+The @samp{-m} option
+specifies the merge methodology that should be used when
+a non-binary file is updated. @code{MERGE} means the usual
address@hidden behavior: try to merge the files. @code{COPY}
+means that @code{cvs update} will refuse to merge
+files, as it also does for files specified as binary
+with @samp{-kb} (but if the file is specified as
+binary, there is no need to specify @samp{-m 'COPY'}).
address@hidden will provide the user with the
+two versions of the files, and require the user using
+mechanisms outside @sc{cvs}, to insert any necessary
+changes.
+
address@hidden: do not use @code{COPY} with
address@hidden 1.9 or earlier - such versions of @sc{cvs} will
+copy one version of your file over the other, wiping
+out the previous contents.}
address@hidden Ordinarily we don't document the behavior of old
address@hidden versions. But this one is so dangerous, I think we
address@hidden must. I almost renamed it to -m 'NOMERGE' so we
address@hidden could say "never use -m 'COPY'".
+The @samp{-m} wrapper option only affects behavior when
+merging is done on update; it does not affect how files
+are stored. See @ref{Binary files}, for more on
+binary files.
+
+The basic format of the file @file{cvswrappers} is:
+
address@hidden FIXME: @example is all wrong for this. Use @deffn or
address@hidden something more sensible.
address@hidden
+wildcard [option value][option value]...
+
+where option is one of
+-m update methodology value: MERGE or COPY
+-k keyword expansion value: expansion mode
+
+and value is a single-quote delimited value.
address@hidden example
+
+
address@hidden FIXME: We don't document -W or point to where it is
address@hidden documented. Or .cvswrappers.
+For example, the following command imports a
+directory, treating files whose name ends in
address@hidden as binary:
+
address@hidden
+cvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag
address@hidden example
+
address@hidden Another good example, would be storing files
address@hidden (e.g. binary files) compressed in the repository.
address@hidden ::::::::::::::::::
address@hidden cvswrappers
address@hidden ::::::::::::::::::
address@hidden *.t12 -m 'COPY'
address@hidden *.t[0-9][0-9] -f 'gunzipcp %s' -t 'gzipcp %s %s' -m 'COPY'
address@hidden
address@hidden ::::::::::::::::::
address@hidden gunzipcp
address@hidden ::::::::::::::::::
address@hidden :
address@hidden [ -f $1 ] || exit 1
address@hidden zcat $1 > /tmp/.#$1.$$
address@hidden mv /tmp/.#$1.$$ $1
address@hidden
address@hidden ::::::::::::::::::
address@hidden gzipcp
address@hidden ::::::::::::::::::
address@hidden :
address@hidden DIRNAME=`echo $1 | sed -e "s|/.*/||g"`
address@hidden if [ ! -d $DIRNAME ] ; then
address@hidden DIRNAME=`echo $1 | sed -e "s|.*/||g"`
address@hidden fi
address@hidden gzip -c $DIRNAME > $2
address@hidden One catch--"cvs diff" will not invoke the wrappers
address@hidden (probably a CVS bug, although I haven't thought it out).
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden commit files
address@hidden The commit support files
address@hidden Committing, administrative support files
+
+The @samp{-i} flag in the @file{modules} file can be
+used to run a certain program whenever files are
+committed (@pxref{modules}). The files described in
+this section provide other, more flexible, ways to run
+programs whenever something is committed.
+
+There are three kind of programs that can be run on
+commit. They are specified in files in the repository,
+as described below. The following table summarizes the
+file names and the purpose of the corresponding
+programs.
+
address@hidden @file
address@hidden commitinfo
+The program is responsible for checking that the commit
+is allowed. If it exits with a non-zero exit status
+the commit will be aborted.
+
address@hidden verifymsg
+The specified program is used to evaluate the log message,
+and possibly verify that it contains all required
+fields. This is most useful in combination with the
address@hidden file, which can hold a log message
+template (@pxref{rcsinfo}).
+
address@hidden editinfo
+The specified program is used to edit the log message,
+and possibly verify that it contains all required
+fields. This is most useful in combination with the
address@hidden file, which can hold a log message
+template (@pxref{rcsinfo}). (obsolete)
+
address@hidden loginfo
+The specified program is called when the commit is
+complete. It receives the log message and some
+additional information and can store the log message in
+a file, or mail it to appropriate persons, or maybe
+post it to a local newsgroup, address@hidden Your
+imagination is the limit!
address@hidden table
+
address@hidden
+* syntax:: The common syntax
+* commitinfo:: Pre-commit checking
+* verifymsg:: How are log messages evaluated?
+* editinfo:: Specifying how log messages are created
+ (obsolete)
+* loginfo:: Where should log messages be sent?
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden syntax
address@hidden The common syntax
address@hidden Info files (syntax)
address@hidden Syntax of info files
address@hidden Common syntax of info files
+
address@hidden FIXME: having this so totally separate from the
address@hidden Variables node is rather bogus.
+
+The administrative files such as @file{commitinfo},
address@hidden, @file{rcsinfo}, @file{verifymsg}, etc.,
+all have a common format. The purpose of the files are
+described later on. The common syntax is described
+here.
+
address@hidden Regular expression syntax
+Each line contains the following:
address@hidden @bullet
address@hidden
address@hidden Say anything about DEFAULT and ALL? Right now we
address@hidden leave that to the description of each file (and in fact
address@hidden the practice is inconsistent which is really annoying).
+A regular expression. This is a basic regular
+expression in the syntax used by GNU emacs.
address@hidden FIXME: What we probably should be saying is "POSIX Basic
address@hidden Regular Expression with the following extensions (`\('
address@hidden `\|' '+' etc)"
address@hidden rather than define it with reference to emacs.
address@hidden The reference to emacs is not strictly speaking
address@hidden true, as we don't support \=, \s, or \S. Also it isn't
address@hidden clear we should document and/or promise to continue to
address@hidden support all the obscure emacs extensions like \<.
address@hidden Also need to better cite (or include) full
address@hidden documentation for the syntax.
address@hidden Also see comment in configure.in about what happens to the
address@hidden syntax if we pick up a system-supplied regexp matcher.
+
address@hidden
+A whitespace separator---one or more spaces and/or tabs.
+
address@hidden
+A file name or command-line template.
address@hidden itemize
+
address@hidden
+Blank lines are ignored. Lines that start with the
+character @samp{#} are treated as comments. Long lines
+unfortunately can @emph{not} be broken in two parts in
+any way.
+
+The first regular expression that matches the current
+directory name in the repository is used. The rest of the line
+is used as a file name or command-line as appropriate.
+
address@hidden FIXME: need an example. In particular, show what
address@hidden the regular expression is matched against (one
address@hidden ordinarily clueful person got confused about whether it
address@hidden includes the filename--"directory name" above should be
address@hidden unambiguous but there is nothing like an example to
address@hidden confirm people's understanding of this sort of thing).
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden commitinfo
address@hidden Commitinfo
address@hidden @file{commitinfo}
address@hidden Commits, precommit verification of
address@hidden Precommit checking
+
+The @file{commitinfo} file defines programs to execute
+whenever @samp{cvs commit} is about to execute. These
+programs are used for pre-commit checking to verify
+that the modified, added and removed files are really
+ready to be committed. This could be used, for
+instance, to verify that the changed files conform to
+to your site's standards for coding practice.
+
+As mentioned earlier, each line in the
address@hidden file consists of a regular expression
+and a command-line template. The template can include
+a program name and any number of arguments you wish to
+supply to it. The full path to the current source
+repository is appended to the template, followed by the
+file names of any files involved in the commit (added,
+removed, and modified files).
+
address@hidden Exit status, of commitinfo
+The first line with a regular expression matching the
+directory within the repository will be used. If the
+command returns a non-zero exit status the commit will
+be aborted.
address@hidden FIXME: need example(s) of what "directory within the
address@hidden repository" means.
+
address@hidden DEFAULT in commitinfo
+If the repository name does not match any of the
+regular expressions in this file, the @samp{DEFAULT}
+line is used, if it is specified.
+
address@hidden ALL in commitinfo
+All occurrences of the name @samp{ALL} appearing as a
+regular expression are used in addition to the first
+matching regular expression or the name @samp{DEFAULT}.
+
address@hidden @file{commitinfo}, working directory
address@hidden @file{commitinfo}, command environment
+The command will be run in the root of the workspace
+containing the new versions of any files the user would like
+to modify (commit), @emph{or in a copy of the workspace on
+the server (@pxref{Remote repositories})}. If a file is
+being removed, there will be no copy of the file under the
+current directory. If a file is being added, there will be
+no corresponding archive file in the repository unless the
+file is being resurrected.
+
+Note that both the repository directory and the corresponding
+Attic (@pxref{Attic}) directory may need to be checked to
+locate the archive file corresponding to any given file being
+committed. Much of the information about the specific commit
+request being made, including the destination branch, commit
+message, and command line options specified, is not available
+to the command.
+
address@hidden FIXME: should discuss using commitinfo to control
address@hidden who has checkin access to what (e.g. Joe can check into
address@hidden directories a, b, and c, and Mary can check into
address@hidden directories b, c, and d--note this case cannot be
address@hidden conveniently handled with unix groups). Of course,
address@hidden adding a new set of features to CVS might be a more
address@hidden natural way to fix this problem than telling people to
address@hidden use commitinfo.
address@hidden FIXME: Should make some reference, especially in
address@hidden the context of controlling who has access, to the fact
address@hidden that commitinfo can be circumvented. Perhaps
address@hidden mention SETXID (but has it been carefully examined
address@hidden for holes?). This fits in with the discussion of
address@hidden general CVS security in "Password authentication
address@hidden security" (the bit which is not pserver-specific).
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden verifymsg
address@hidden Verifying log messages
address@hidden @file{verifymsg} (admin file)
address@hidden Log message, verifying
+
+Once you have entered a log message, you can evaluate
+that message to check for specific content, such as
+a bug ID. Use the @file{verifymsg} file to
+specify a program that is used to verify the log message.
+This program could be a simple script that checks
+that the entered message contains the required fields.
+
+The @file{verifymsg} file is often most useful together
+with the @file{rcsinfo} file, which can be used to
+specify a log message template.
+
+Each line in the @file{verifymsg} file consists of a
+regular expression and a command-line template. The
+template must include a program name, and can include
+any number of arguments. The full path to the current
+log message template file is appended to the template.
+
+One thing that should be noted is that the @samp{ALL}
+keyword is not supported. If more than one matching
+line is found, the first one is used. This can be
+useful for specifying a default verification script in a
+directory, and then overriding it in a subdirectory.
+
address@hidden DEFAULT in @file{verifymsg}
+If the repository name does not match any of the
+regular expressions in this file, the @samp{DEFAULT}
+line is used, if it is specified.
+
address@hidden Exit status, of @file{verifymsg}
+If the verification script exits with a non-zero exit status,
+the commit is aborted.
+
address@hidden @file{verifymsg}, changing the log message
+In the default configuration, CVS allows the
+verification script to change the log message. This is
+controlled via the RereadLogAfterVerify CVSROOT/config
+option.
+
+When @samp{RereadLogAfterVerify=always} or
address@hidden, the log message will
+either always be reread after the verification script
+is run or reread only if the log message file status
+has changed.
+
address@hidden, for more on CVSROOT/config options.
+
+It is NOT a good idea for a @file{verifymsg} script to
+interact directly with the user in the various
+client/server methods. For the @code{pserver} method,
+there is no protocol support for communicating between
address@hidden and the client on the remote end. For the
address@hidden and @code{server} methods, it is possible
+for CVS to become confused by the characters going
+along the same channel as the CVS protocol
+messages. See @ref{Remote repositories}, for more
+information on client/server setups. In addition, at the time
+the @file{verifymsg} script runs, the CVS
+server has locks in place in the repository. If control is
+returned to the user here then other users may be stuck waiting
+for access to the repository.
+
+This option can be useful if you find yourself using an
+rcstemplate that needs to be modified to remove empty
+elements or to fill in default values. It can also be
+useful if the rcstemplate has changed in the repository
+and the CVS/Template was not updated, but is able to be
+adapted to the new format by the verification script
+that is run by @file{verifymsg}.
+
+An example of an update might be to change all
+occurrences of 'BugId:' to be 'DefectId:' (which can be
+useful if the rcstemplate has recently been changed and
+there are still checked-out user trees with cached
+copies in the CVS/Template file of the older version).
+
+Another example of an update might be to delete a line
+that contains 'BugID: none' from the log message after
+validation of that value as being allowed is made.
+
+The following is a little silly example of a
address@hidden file, together with the corresponding
address@hidden file, the log message template and an
+verification script. We begin with the log message template.
+We want to always record a bug-id number on the first
+line of the log message. The rest of log message is
+free text. The following template is found in the file
address@hidden/usr/cvssupport/tc.template}.
+
address@hidden
+BugId:
address@hidden example
+
+The script @file{/usr/cvssupport/bugid.verify} is used to
+evaluate the log message.
+
address@hidden
+#!/bin/sh
+#
+# bugid.verify filename
+#
+# Verify that the log message contains a valid bugid
+# on the first line.
+#
+if head -1 < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then
+ exit 0
+elif head -1 < $1 | grep '^BugId:[ ]*none$' > /dev/null; then
+ # It is okay to allow commits with 'BugId: none',
+ # but do not put that text into the real log message.
+ grep -v '^BugId:[ ]*none$' > $1.rewrite
+ mv $1.rewrite $1
+ exit 0
+else
+ echo "No BugId found."
+ exit 1
+fi
address@hidden example
+
+The @file{verifymsg} file contains this line:
+
address@hidden
+^tc /usr/cvssupport/bugid.verify
address@hidden example
+
+The @file{rcsinfo} file contains this line:
+
address@hidden
+^tc /usr/cvssupport/tc.template
address@hidden example
+
+The @file{config} file contains this line:
+
address@hidden
+RereadLogAfterVerify=always
address@hidden example
+
+
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden editinfo
address@hidden Editinfo
address@hidden editinfo (admin file)
address@hidden Editor, specifying per module
address@hidden Per-module editor
address@hidden Log messages, editing
+
address@hidden: The @file{editinfo} feature has been
+rendered obsolete. To set a default editor for log
+messages use the @code{CVSEDITOR}, @code{EDITOR} environment variables
+(@pxref{Environment variables}) or the @samp{-e} global
+option (@pxref{Global options}). See @ref{verifymsg},
+for information on the use of the @file{verifymsg}
+feature for evaluating log messages.}
+
+If you want to make sure that all log messages look the
+same way, you can use the @file{editinfo} file to
+specify a program that is used to edit the log message.
+This program could be a custom-made editor that always
+enforces a certain style of the log message, or maybe a
+simple shell script that calls an editor, and checks
+that the entered message contains the required fields.
+
+If no matching line is found in the @file{editinfo}
+file, the editor specified in the environment variable
address@hidden is used instead. If that variable is
+not set, then the environment variable @code{$EDITOR}
+is used instead. If that variable is not
+set a default will be used. See @ref{Committing your changes}.
+
+The @file{editinfo} file is often most useful together
+with the @file{rcsinfo} file, which can be used to
+specify a log message template.
+
+Each line in the @file{editinfo} file consists of a
+regular expression and a command-line template. The
+template must include a program name, and can include
+any number of arguments. The full path to the current
+log message template file is appended to the template.
+
+One thing that should be noted is that the @samp{ALL}
+keyword is not supported. If more than one matching
+line is found, the first one is used. This can be
+useful for specifying a default edit script in a
+module, and then overriding it in a subdirectory.
+
address@hidden DEFAULT in editinfo
+If the repository name does not match any of the
+regular expressions in this file, the @samp{DEFAULT}
+line is used, if it is specified.
+
+If the edit script exits with a non-zero exit status,
+the commit is aborted.
+
+Note: when @sc{cvs} is accessing a remote repository,
+or when the @samp{-m} or @samp{-F} options to @code{cvs
+commit} are used, @file{editinfo} will not be consulted.
+There is no good workaround for this; use
address@hidden instead.
+
address@hidden
+* editinfo example:: Editinfo example
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden editinfo example
address@hidden Editinfo example
+
+The following is a little silly example of a
address@hidden file, together with the corresponding
address@hidden file, the log message template and an
+editor script. We begin with the log message template.
+We want to always record a bug-id number on the first
+line of the log message. The rest of log message is
+free text. The following template is found in the file
address@hidden/usr/cvssupport/tc.template}.
+
address@hidden
+BugId:
address@hidden example
+
+The script @file{/usr/cvssupport/bugid.edit} is used to
+edit the log message.
+
address@hidden
+#!/bin/sh
+#
+# bugid.edit filename
+#
+# Call $EDITOR on FILENAME, and verify that the
+# resulting file contains a valid bugid on the first
+# line.
+if [ "x$EDITOR" = "x" ]; then EDITOR=vi; fi
+if [ "x$CVSEDITOR" = "x" ]; then CVSEDITOR=$EDITOR; fi
+$CVSEDITOR $1
+until head -1|grep '^BugId:[ ]*[0-9][0-9]*$' < $1
+do echo -n "No BugId found. Edit again? ([y]/n)"
+ read ans
+ case address@hidden@} in
+ n*) exit 1;;
+ esac
+ $CVSEDITOR $1
+done
address@hidden example
+
+The @file{editinfo} file contains this line:
+
address@hidden
+^tc /usr/cvssupport/bugid.edit
address@hidden example
+
+The @file{rcsinfo} file contains this line:
+
address@hidden
+^tc /usr/cvssupport/tc.template
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden loginfo
address@hidden Loginfo
address@hidden loginfo (admin file)
address@hidden Storing log messages
address@hidden Mailing log messages
address@hidden Distributing log messages
address@hidden Log messages
+
address@hidden "cvs commit" is not quite right. What we
address@hidden mean is "when the repository gets changed" which
address@hidden also includes "cvs import" and "cvs add" on a directory.
+The @file{loginfo} file is used to control where
address@hidden commit} log information is sent. The first
+entry on a line is a regular expression which is tested
+against the directory that the change is being made to,
+relative to the @code{$CVSROOT}. If a match is found, then
+the remainder of the line is a filter program that
+should expect log information on its standard input.
+
+If the repository name does not match any of the
+regular expressions in this file, the @samp{DEFAULT}
+line is used, if it is specified.
+
+All occurrences of the name @samp{ALL} appearing as a
+regular expression are used in addition to the first
+matching regular expression or @samp{DEFAULT}.
+
+The first matching regular expression is used.
+
address@hidden files}, for a description of the syntax of
+the @file{loginfo} file.
+
+The user may specify a format string as
+part of the filter. The string is composed of a
address@hidden followed by a space, or followed by a single
+format character, or followed by a set of format
+characters surrounded by @address@hidden and @address@hidden as
+separators. The format characters are:
+
address@hidden @t
address@hidden s
+file name
address@hidden V
+old version number (pre-checkin)
address@hidden v
+new version number (post-checkin)
address@hidden table
+
+All other characters that appear in a format string
+expand to an empty field (commas separating fields are
+still provided).
+
+For example, some valid format strings are @samp{%},
address@hidden, @address@hidden@}}, and @address@hidden@}}.
+
+The output will be a space separated string of tokens enclosed in
+quotation marks (@t{"}).
+Any embedded dollar signs (@t{$}), backticks (@t{`}),
+backslashes (@t{\}), or quotation marks will be preceded
+by a backslash (this allows the shell to correctly parse it
+as a single string, regardless of the characters it contains).
+For backwards compatibility, the first
+token will be the repository subdirectory. The rest of the
+tokens will be comma-delimited lists of the information
+requested in the format string. For example, if
address@hidden/u/src/master/yoyodyne/tc} is the repository, @address@hidden@}}
+is the format string, and three files (@t{ChangeLog},
address@hidden, @t{foo.c}) were modified, the output
+might be:
+
address@hidden
+"yoyodyne/tc ChangeLog,1.1,1.2 Makefile,1.3,1.4 foo.c,1.12,1.13"
address@hidden example
+
+As another example, @address@hidden@}} means that only the
+name of the repository will be generated.
+
+Note: when @sc{cvs} is accessing a remote repository,
address@hidden will be run on the @emph{remote}
+(i.e., server) side, not the client side (@pxref{Remote
+repositories}).
+
address@hidden
+* loginfo example:: Loginfo example
+* Keeping a checked out copy:: Updating a tree on every checkin
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden loginfo example
address@hidden Loginfo example
+
+The following @file{loginfo} file, together with the
+tiny shell-script below, appends all log messages
+to the file @file{$CVSROOT/CVSROOT/commitlog},
+and any commits to the administrative files (inside
+the @file{CVSROOT} directory) are also logged in
address@hidden/usr/adm/cvsroot-log}.
+Commits to the @file{prog1} directory are mailed to @t{ceder}.
+
address@hidden FIXME: is it a CVS feature or bug that only the
address@hidden first matching line is used? It is documented
address@hidden above, but is it useful? For example, if we wanted
address@hidden to run both "cvs-log" and "Mail" for the CVSROOT
address@hidden directory, it is kind of awkward if
address@hidden only the first matching line is used.
address@hidden
+ALL /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog $USER
+^CVSROOT /usr/local/bin/cvs-log /usr/adm/cvsroot-log
+^prog1 Mail -s %s ceder
address@hidden example
+
+The shell-script @file{/usr/local/bin/cvs-log} looks
+like this:
+
address@hidden
+#!/bin/sh
+(echo "------------------------------------------------------";
+ echo -n $2" ";
+ date;
+ echo;
+ cat) >> $1
address@hidden example
+
address@hidden Keeping a checked out copy
address@hidden Keeping a checked out copy
+
address@hidden What other index entries? It seems like
address@hidden people might want to use a lot of different
address@hidden words for this functionality.
address@hidden Keeping a checked out copy
address@hidden Checked out copy, keeping
address@hidden Web pages, maintaining with CVS
+
+It is often useful to maintain a directory tree which
+contains files which correspond to the latest version
+in the repository. For example, other developers might
+want to refer to the latest sources without having to
+check them out, or you might be maintaining a web site
+with @sc{cvs} and want every checkin to cause the files
+used by the web server to be updated.
address@hidden Can we offer more details on the web example? Or
address@hidden point the user at how to figure it out? This text
address@hidden strikes me as sufficient for someone who already has
address@hidden some idea of what we mean but not enough for the naive
address@hidden user/sysadmin to understand it and set it up.
+
+The way to do this is by having loginfo invoke
address@hidden update}. Doing so in the naive way will
+cause a problem with locks, so the @code{cvs update}
+must be run in the background.
address@hidden Should we try to describe the problem with locks?
address@hidden It seems like a digression for someone who just
address@hidden wants to know how to make it work.
address@hidden Another choice which might work for a single file
address@hidden is to use "cvs -n update -p" which doesn't take
address@hidden out locks (I think) but I don't see many advantages
address@hidden of that and we might as well document something which
address@hidden works for multiple files.
+Here is an example for unix (this should all be on one line):
+
address@hidden
+^cyclic-pages (date; cat; (sleep 2; cd /u/www/local-docs;
+ cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1
address@hidden example
+
+This will cause checkins to repository directories
+starting with @code{cyclic-pages} to update the checked
+out tree in @file{/u/www/local-docs}.
address@hidden More info on some of the details? The "sleep 2" is
address@hidden so if we are lucky the lock will be gone by the time
address@hidden we start and we can wait 2 seconds instead of 30.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden rcsinfo
address@hidden Rcsinfo
address@hidden rcsinfo (admin file)
address@hidden Form for log message
address@hidden Log message template
address@hidden Template for log message
+
+The @file{rcsinfo} file can be used to specify a form to
+edit when filling out the commit log. The
address@hidden file has a syntax similar to the
address@hidden, @file{commitinfo} and @file{loginfo}
+files. @xref{syntax}. Unlike the other files the second
+part is @emph{not} a command-line template. Instead,
+the part after the regular expression should be a full pathname to
+a file containing the log message template.
+
+If the repository name does not match any of the
+regular expressions in this file, the @samp{DEFAULT}
+line is used, if it is specified.
+
+All occurrences of the name @samp{ALL} appearing as a
+regular expression are used in addition to the first
+matching regular expression or @samp{DEFAULT}.
+
address@hidden FIXME: should be offering advice, somewhere around
address@hidden here, about where to put the template file. The
address@hidden verifymsg example uses /usr/cvssupport but doesn't
address@hidden say anything about what that directory is for or
address@hidden whether it is hardwired into CVS or who creates
address@hidden it or anything. In particular we should say
address@hidden how to version control the template file. A
address@hidden probably better answer than the /usr/cvssupport
address@hidden stuff is to use checkoutlist (with xref to the
address@hidden checkoutlist doc).
address@hidden Also I am starting to see a connection between
address@hidden this and the Keeping a checked out copy node.
address@hidden Probably want to say something about that.
+The log message template will be used as a default log
+message. If you specify a log message with @samp{cvs
+commit -m @var{message}} or @samp{cvs commit -f
address@hidden that log message will override the
+template.
+
address@hidden, for an example @file{rcsinfo}
+file.
+
+When @sc{cvs} is accessing a remote repository,
+the contents of @file{rcsinfo} at the time a directory
+is first checked out will specify a template. This
+template will be updated on all @samp{cvs update}
+commands. It will also be added to new directories
+added with a @samp{cvs add new-directry} command.
+In versions of @sc{cvs} prior to version 1.12, the
address@hidden/Template} file was not updated. If the
address@hidden server is at version 1.12 or higher an older
+client may be used and the @file{CVS/Template} will
+be updated from the server.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden cvsignore
address@hidden Ignoring files via cvsignore
address@hidden cvsignore (admin file), global
address@hidden Global cvsignore
address@hidden Ignoring files
address@hidden -- This chapter should maybe be moved to the
address@hidden tutorial part of the manual?
+
+There are certain file names that frequently occur
+inside your working copy, but that you don't want to
+put under @sc{cvs} control. Examples are all the object
+files that you get while you compile your sources.
+Normally, when you run @samp{cvs update}, it prints a
+line for each file it encounters that it doesn't know
+about (@pxref{update output}).
+
address@hidden has a list of files (or sh(1) file name patterns)
+that it should ignore while running @code{update},
address@hidden and @code{release}.
address@hidden -- Are those the only three commands affected?
+This list is constructed in the following way.
+
address@hidden @bullet
address@hidden
+The list is initialized to include certain file name
+patterns: names associated with @sc{cvs}
+administration, or with other common source control
+systems; common names for patch files, object files,
+archive files, and editor backup files; and other names
+that are usually artifacts of assorted utilities.
+Currently, the default list of ignored file name
+patterns is:
+
address@hidden Ignored files
address@hidden Automatically ignored files
address@hidden
+ RCS SCCS CVS CVS.adm
+ RCSLOG cvslog.*
+ tags TAGS
+ .make.state .nse_depinfo
+ *~ #* .#* ,* _$* *$
+ *.old *.bak *.BAK *.orig *.rej .del-*
+ *.a *.olb *.o *.obj *.so *.exe
+ *.Z *.elc *.ln
+ core
address@hidden example
+
address@hidden
+The per-repository list in
address@hidden/CVSROOT/cvsignore} is appended to
+the list, if that file exists.
+
address@hidden
+The per-user list in @file{.cvsignore} in your home
+directory is appended to the list, if it exists.
+
address@hidden
+Any entries in the environment variable
address@hidden is appended to the list.
+
address@hidden
+Any @samp{-I} options given to @sc{cvs} is appended.
+
address@hidden
+As @sc{cvs} traverses through your directories, the contents
+of any @file{.cvsignore} will be appended to the list.
+The patterns found in @file{.cvsignore} are only valid
+for the directory that contains them, not for
+any sub-directories.
address@hidden itemize
+
+In any of the 5 places listed above, a single
+exclamation mark (@samp{!}) clears the ignore list.
+This can be used if you want to store any file which
+normally is ignored by @sc{cvs}.
+
+Specifying @samp{-I !} to @code{cvs import} will import
+everything, which is generally what you want to do if
+you are importing files from a pristine distribution or
+any other source which is known to not contain any
+extraneous files. However, looking at the rules above
+you will see there is a fly in the ointment; if the
+distribution contains any @file{.cvsignore} files, then
+the patterns from those files will be processed even if
address@hidden !} is specified. The only workaround is to
+remove the @file{.cvsignore} files in order to do the
+import. Because this is awkward, in the future
address@hidden !} might be modified to override
address@hidden files in each directory.
+
+Note that the syntax of the ignore files consists of a
+series of lines, each of which contains a space
+separated list of filenames. This offers no clean way
+to specify filenames which contain spaces, but you can
+use a workaround like @file{foo?bar} to match a file
+named @file{foo bar} (it also matches @file{fooxbar}
+and the like). Also note that there is currently no
+way to specify comments.
address@hidden FIXCVS? I don't _like_ this syntax at all, but
address@hidden changing it raises all the usual compatibility
address@hidden issues and I'm also not sure what to change it to.
+
address@hidden checkoutlist
address@hidden The checkoutlist file
address@hidden checkoutlist
+
+It may be helpful to use @sc{cvs} to maintain your own
+files in the @file{CVSROOT} directory. For example,
+suppose that you have a script @file{logcommit.pl}
+which you run by including the following line in the
address@hidden administrative file:
+
address@hidden
+ALL $CVSROOT/CVSROOT/logcommit.pl
address@hidden example
+
+To maintain @file{logcommit.pl} with @sc{cvs} you would
+add the following line to the @file{checkoutlist}
+administrative file:
+
address@hidden
+logcommit.pl
address@hidden example
+
+The format of @file{checkoutlist} is one line for each
+file that you want to maintain using @sc{cvs}, giving
+the name of the file.
+
+After setting up @file{checkoutlist} in this fashion,
+the files listed there will function just like
address@hidden's built-in administrative files. For example,
+when checking in one of the files you should get a
+message such as:
+
address@hidden
+cvs commit: Rebuilding administrative file database
address@hidden example
+
address@hidden
+and the checked out copy in the @file{CVSROOT}
+directory should be updated.
+
+Note that listing @file{passwd} (@pxref{Password
+authentication server}) in @file{checkoutlist} is not
+recommended for security reasons.
+
+For information about keeping a checkout out copy in a
+more general context than the one provided by
address@hidden, see @ref{Keeping a checked out
+copy}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden history file
address@hidden The history file
address@hidden History file
address@hidden Log information, saving
+
+The file @file{$CVSROOT/CVSROOT/history} is used
+to log information for the @code{history} command
+(@pxref{history}). This file must be created to turn
+on logging. This is done automatically if the
address@hidden init} command is used to set up the
+repository (@pxref{Creating a repository}).
+
+The file format of the @file{history} file is
+documented only in comments in the @sc{cvs} source
+code, but generally programs should use the @code{cvs
+history} command to access it anyway, in case the
+format changes with future releases of @sc{cvs}.
+
address@hidden Variables
address@hidden Expansions in administrative files
address@hidden Internal variables
address@hidden Variables
+
+Sometimes in writing an administrative file, you might
+want the file to be able to know various things based
+on environment @sc{cvs} is running in. There are
+several mechanisms to do that.
+
+To find the home directory of the user running @sc{cvs}
+(from the @code{HOME} environment variable), use
address@hidden followed by @samp{/} or the end of the line.
+Likewise for the home directory of @var{user}, use
address@hidden@var{user}}. These variables are expanded on
+the server machine, and don't get any reasonable
+expansion if pserver (@pxref{Password authenticated})
+is in use; therefore user variables (see below) may be
+a better choice to customize behavior based on the user
+running @sc{cvs}.
address@hidden Based on these limitations, should we deprecate ~?
address@hidden What is it good for? Are people using it?
+
+One may want to know about various pieces of
+information internal to @sc{cvs}. A @sc{cvs} internal
+variable has the syntax @address@hidden@address@hidden,
+where @var{variable} starts with a letter and consists
+of alphanumeric characters and @samp{_}. If the
+character following @var{variable} is a
+non-alphanumeric character other than @samp{_}, the
address@hidden@{} and @address@hidden can be omitted. The @sc{cvs}
+internal variables are:
+
address@hidden @code
address@hidden CVSROOT
address@hidden CVSROOT, internal variable
+This is the absolute path to the current @sc{cvs} root directory.
address@hidden, for a description of the various
+ways to specify this, but note that the internal
+variable contains just the directory and not any
+of the access method information.
+
address@hidden RCSBIN
address@hidden RCSBIN, internal variable
+In @sc{cvs} 1.9.18 and older, this specified the
+directory where @sc{cvs} was looking for @sc{rcs}
+programs. Because @sc{cvs} no longer runs @sc{rcs}
+programs, specifying this internal variable is now an
+error.
+
address@hidden CVSEDITOR
address@hidden CVSEDITOR, internal variable
address@hidden EDITOR
address@hidden EDITOR, internal variable
address@hidden VISUAL
address@hidden VISUAL, internal variable
+These all expand to the same value, which is the editor
+that @sc{cvs} is using. @xref{Global options}, for how
+to specify this.
+
address@hidden USER
address@hidden USER, internal variable
+Username of the user running @sc{cvs} (on the @sc{cvs}
+server machine).
+When using pserver, this is the user specified in the repository
+specification which need not be the same as the username the
+server is running as (@pxref{Password authentication server}).
+Do not confuse this with the environment variable of the same name.
address@hidden table
+
+If you want to pass a value to the administrative files
+which the user who is running @sc{cvs} can specify,
+use a user variable.
address@hidden User variables
+To expand a user variable, the
+administrative file contains
address@hidden@address@hidden@}}. To set a user variable,
+specify the global option @samp{-s} to @sc{cvs}, with
+argument @address@hidden@var{value}}. It may be
+particularly useful to specify this option via
address@hidden (@pxref{~/.cvsrc}).
+
+For example, if you want the administrative file to
+refer to a test directory you might create a user
+variable @code{TESTDIR}. Then if @sc{cvs} is invoked
+as
+
address@hidden
+cvs -s TESTDIR=/work/local/tests
address@hidden example
+
address@hidden
+and the
+administrative file contains @code{sh
address@hidden@}/runtests}, then that string is expanded
+to @code{sh /work/local/tests/runtests}.
+
+All other strings containing @samp{$} are reserved;
+there is no way to quote a @samp{$} character so that
address@hidden represents itself.
+
+Environment variables passed to administrative files are:
+
address@hidden @code
address@hidden environment variables, passed to administrative files
+
address@hidden CVS_USER
address@hidden CVS_USER, environment variable
+The @sc{cvs}-specific username provided by the user, if it
+can be provided (currently just for the pserver access
+method), and to the empty string otherwise. (@code{CVS_USER}
+and @code{USER} may differ when @file{$CVSROOT/CVSROOT/passwd}
+is used to map @sc{cvs} usernames to system usernames.)
+
address@hidden LOGNAME
address@hidden LOGNAME, environment variable
+The username of the system user.
+
address@hidden USER
address@hidden USER, environment variable
+Same as @code{LOGNAME}.
+Do not confuse this with the internal variable of the same name.
address@hidden table
+
address@hidden config
address@hidden The CVSROOT/config configuration file
+
address@hidden config, in CVSROOT
address@hidden CVSROOT/config
+
+The administrative file @file{config} contains various
+miscellaneous settings which affect the behavior of
address@hidden The syntax is slightly different from the
+other administrative files. Variables are not
+expanded. Lines which start with @samp{#} are
+considered comments.
address@hidden FIXME: where do we define comments for the other
address@hidden administrative files.
+Other lines consist of a keyword, @samp{=}, and a
+value. Note that this syntax is very strict.
+Extraneous spaces or tabs are not permitted.
address@hidden See comments in parseinfo.c:parse_config for more
address@hidden discussion of this strictness.
+
+Currently defined keywords are:
+
address@hidden @code
address@hidden RCSBIN, in CVSROOT/config
address@hidden address@hidden
+For @sc{cvs} 1.9.12 through 1.9.18, this setting told
address@hidden to look for @sc{rcs} programs in the
address@hidden directory. Current versions of @sc{cvs}
+do not run @sc{rcs} programs; for compatibility this
+setting is accepted, but it does nothing.
+
address@hidden SystemAuth, in CVSROOT/config
address@hidden address@hidden
+If @var{value} is @samp{yes}, then pserver should check
+for users in the system's user database if not found in
address@hidden/passwd}. If it is @samp{no}, then all
+pserver users must exist in @file{CVSROOT/passwd}.
+The default is @samp{yes}. For more on pserver, see
address@hidden authenticated}.
+
+
address@hidden TopLevelAdmin, in CVSROOT/config
address@hidden address@hidden
+Modify the @samp{checkout} command to create a
address@hidden directory at the top level of the new
+working directory, in addition to @samp{CVS}
+directories created within checked-out directories.
+The default value is @samp{no}.
+
+This option is useful if you find yourself performing
+many commands at the top level of your working
+directory, rather than in one of the checked out
+subdirectories. The @file{CVS} directory created there
+will mean you don't have to specify @code{CVSROOT} for
+each command. It also provides a place for the
address@hidden/Template} file (@pxref{Working directory
+storage}).
+
address@hidden LockDir, in CVSROOT/config
address@hidden address@hidden
+Put @sc{cvs} lock files in @var{directory} rather than
+directly in the repository. This is useful if you want
+to let users read from the repository while giving them
+write access only to @var{directory}, not to the
+repository.
+It can also be used to put the locks on a very fast
+in-memory file system to speed up locking and unlocking
+the repository.
+You need to create @var{directory}, but
address@hidden will create subdirectories of @var{directory} as it
+needs them. For information on @sc{cvs} locks, see
address@hidden
+
address@hidden Mention this in Compatibility section?
+Before enabling the LockDir option, make sure that you
+have tracked down and removed any copies of @sc{cvs} 1.9 or
+older. Such versions neither support LockDir, nor will
+give an error indicating that they don't support it.
+The result, if this is allowed to happen, is that some
address@hidden users will put the locks one place, and others will
+put them another place, and therefore the repository
+could become corrupted. @sc{cvs} 1.10 does not support
+LockDir but it will print a warning if run on a
+repository with LockDir enabled.
+
address@hidden LogHistory, in CVSROOT/config
address@hidden address@hidden
+Control what is logged to the @file{CVSROOT/history} file (@pxref{history}).
+Default of @samp{TOEFWUCGMAR} (or simply @samp{all}) will log
+all transactions. Any subset of the default is
+legal. (For example, to only log transactions that modify the
address@hidden,v} files, use @samp{LogHistory=TMAR}.)
+
address@hidden RereadLogAfterVerify, in CVSROOT/config
address@hidden @file{verifymsg}, changing the log message
address@hidden address@hidden
+Modify the @samp{commit} command such that CVS will reread the
+log message after running the program specified by @file{verifymsg}.
address@hidden may be one of @samp{yes} or @samp{always}, indicating that
+the log message should always be reread; @samp{no}
+or @samp{never}, indicating that it should never be
+reread; or @var{value} may be @samp{stat}, indicating
+that the file should be checked with the filesystem
address@hidden()} function to see if it has changed (see warning below)
+before rereading. The default value is @samp{always}.
+
address@hidden: the `stat' mode can cause CVS to pause for up to
+one extra second per directory committed. This can be less IO and
+CPU intensive but is not recommended for use with large repositories}
+
address@hidden, for more information on how verifymsg
+may be used.
+
address@hidden UserAdminOptions, in CVSROOT/config
address@hidden address@hidden
+Control what options will be allowed with the @code{cvs admin}
+command (@pxref{admin}) for users not in the @code{cvsadmin} group.
+The @var{value} string is a list of single character options
+which should be allowed. If a user who is not a member of the
address@hidden group tries to execute any @code{cvs admin}
+option which is not listed they will will receive an error message
+reporting that the option is restricted.
+
+If no @code{cvsadmin} group exists on the server, @sc{cvs} will
+ignore the @code{UserAdminOptions} keyword (@pxref{admin}).
+
+When not specified, @code{UserAdminOptions} defaults to
address@hidden In other words, it defaults to allowing
+users outside of the @code{cvsadmin} group to use the
address@hidden admin} command only to change the default keyword
+expansion mode for files.
+
+As an example, to restrict users not in the @code{cvsadmin}
+group to using @code{cvs admin} to change the default keyword
+substitution mode, lock revisions, unlock revisions, and
+replace the log message, use @samp{UserAdminOptions=klum}.
address@hidden table
+
address@hidden
---------------------------------------------------------------------
address@hidden Environment variables
address@hidden All environment variables which affect CVS
address@hidden Environment variables
address@hidden Reference manual for variables
+
+This is a complete list of all environment variables
+that affect @sc{cvs}.
+
address@hidden @code
address@hidden CVSIGNORE, environment variable
address@hidden $CVSIGNORE
+A whitespace-separated list of file name patterns that
address@hidden should ignore. @xref{cvsignore}.
+
address@hidden CVSWRAPPERS, environment variable
address@hidden $CVSWRAPPERS
+A whitespace-separated list of file name patterns that
address@hidden should treat as wrappers. @xref{Wrappers}.
+
address@hidden CVSREAD, environment variable
address@hidden Read-only files, and CVSREAD
address@hidden $CVSREAD
+If this is set, @code{checkout} and @code{update} will
+try hard to make the files in your working directory
+read-only. When this is not set, the default behavior
+is to permit modification of your working files.
+
address@hidden CVSREADONLYFS, environment variable
address@hidden $CVSREADONLYFS
+Turns on read-only repository mode. This allows one to
+check out from a read-only repository, such as within
+an anoncvs server, or from a CDROM repository.
+
+It has the same effect as if the @samp{-R} command-line
+option is used. This can also allow the use of
+read-only NFS repositories.
+
address@hidden $CVSUMASK
+Controls permissions of files in the repository. See
address@hidden permissions}.
+
address@hidden $CVSROOT
+Should contain the full pathname to the root of the @sc{cvs}
+source repository (where the @sc{rcs} files are
+kept). This information must be available to @sc{cvs} for
+most commands to execute; if @code{$CVSROOT} is not set,
+or if you wish to override it for one invocation, you
+can supply it on the command line: @samp{cvs -d cvsroot
address@hidden Once you have checked out a working
+directory, @sc{cvs} stores the appropriate root (in
+the file @file{CVS/Root}), so normally you only need to
+worry about this when initially checking out a working
+directory.
+
address@hidden $CVSEDITOR
address@hidden CVSEDITOR, environment variable
address@hidden $EDITOR
address@hidden EDITOR, environment variable
address@hidden $VISUAL
address@hidden VISUAL, environment variable
+Specifies the program to use for recording log messages
+during commit. @code{$CVSEDITOR} overrides
address@hidden, which overrides @code{$VISUAL}.
+See @ref{Committing your changes} for more or
address@hidden options} for alternative ways of specifying a
+log editor.
+
address@hidden PATH, environment variable
address@hidden $PATH
+If @code{$RCSBIN} is not set, and no path is compiled
+into @sc{cvs}, it will use @code{$PATH} to try to find all
+programs it uses.
+
address@hidden HOME, environment variable
address@hidden $HOME
address@hidden HOMEPATH, environment variable
address@hidden $HOMEPATH
address@hidden HOMEDRIVE, environment variable
address@hidden $HOMEDRIVE
+Used to locate the directory where the @file{.cvsrc}
+file, and other such files, are searched. On Unix, @sc{cvs}
+just checks for @code{HOME}. On Windows NT, the system will
+set @code{HOMEDRIVE}, for example to @samp{d:} and @code{HOMEPATH},
+for example to @file{\joe}. On Windows 95, you'll
+probably need to set @code{HOMEDRIVE} and @code{HOMEPATH} yourself.
address@hidden We are being vague about whether HOME works on
address@hidden Windows; see long comment in windows-NT/filesubr.c.
+
address@hidden CVS_RSH, environment variable
address@hidden $CVS_RSH
+Specifies the external program which @sc{cvs} connects with,
+when @code{:ext:} access method is specified.
address@hidden via rsh}.
+
address@hidden $CVS_SERVER
+Used in client-server mode when accessing a remote
+repository using @sc{rsh}. It specifies the name of
+the program to start on the server side (and any
+necessary arguments) when accessing a remote repository
+using the @code{:ext:}, @code{:fork:}, or @code{:server:} access methods.
+The default value for @code{:ext:} and @code{:server:} is @code{cvs};
+the default value for @code{:fork:} is the name used to run the client.
address@hidden via rsh}
+
address@hidden $CVS_PASSFILE
+Used in client-server mode when accessing the @code{cvs
+login server}. Default value is @file{$HOME/.cvspass}.
address@hidden authentication client}
+
address@hidden $CVS_CLIENT_PORT
+Used in client-server mode to set the port to use when accessing the server
+via Kerberos, GSSAPI, or @sc{cvs}'s password authentication protocol
+if the port is not specified in the CVSROOT.
address@hidden repositories}
+
address@hidden CVS_RCMD_PORT, environment variable
address@hidden $CVS_RCMD_PORT
+Used in client-server mode. If set, specifies the port
+number to be used when accessing the @sc{rcmd} demon on
+the server side. (Currently not used for Unix clients).
+
address@hidden CVS_CLIENT_LOG, environment variable
address@hidden $CVS_CLIENT_LOG
+Used for debugging only in client-server
+mode. If set, everything sent to the server is logged
+into @address@hidden and everything
+sent from the server is logged into
address@hidden@code{$CVS_CLIENT_LOG}.out}.
+
address@hidden CVS_SERVER_SLEEP, environment variable
address@hidden $CVS_SERVER_SLEEP
+Used only for debugging the server side in
+client-server mode. If set, delays the start of the
+server child process the specified amount of
+seconds so that you can attach to it with a debugger.
+
address@hidden CVS_IGNORE_REMOTE_ROOT, environment variable
address@hidden $CVS_IGNORE_REMOTE_ROOT
+For @sc{cvs} 1.10 and older, setting this variable
+prevents @sc{cvs} from overwriting the @file{CVS/Root}
+file when the @samp{-d} global option is specified.
+Later versions of @sc{cvs} do not rewrite
address@hidden/Root}, so @code{CVS_IGNORE_REMOTE_ROOT} has no
+effect.
+
address@hidden CVS_LOCAL_BRANCH_NUM, environment variable
address@hidden $CVS_LOCAL_BRANCH_NUM
+Setting this variable allows some control over the
+branch number that is assigned. This is specifically to
+support the local commit feature of CVSup. If one sets
address@hidden to (say) 1000 then branches
+the local repository, the revision numbers will look
+like 1.66.1000.xx. There is almost a dead-set certainty
+that there will be no conflicts with version numbers.
+
address@hidden COMSPEC, environment variable
address@hidden $COMSPEC
+Used under OS/2 only. It specifies the name of the
+command interpreter and defaults to @sc{cmd.exe}.
+
address@hidden TMPDIR, environment variable
address@hidden $TMPDIR
address@hidden TMP, environment variable
address@hidden $TMP
address@hidden TEMP, environment variable
address@hidden $TEMP
address@hidden Temporary files, location of
address@hidden This is quite nuts. We don't talk about tempnam
address@hidden or mkstemp which we sometimes use. The discussion
address@hidden of "Global options" is semi-incoherent.
address@hidden I'm not even sure those are the only inaccuracies.
address@hidden Furthermore, the conventions are
address@hidden pretty crazy and they should be simplified.
+Directory in which temporary files are located.
+The @sc{cvs} server uses
address@hidden @xref{Global options}, for a
+description of how to specify this.
+Some parts of @sc{cvs} will always use @file{/tmp} (via
+the @code{tmpnam} function provided by the system).
+
+On Windows NT, @code{TMP} is used (via the @code{_tempnam}
+function provided by the system).
+
+The @code{patch} program which is used by the @sc{cvs}
+client uses @code{TMPDIR}, and if it is not set, uses
address@hidden/tmp} (at least with GNU patch 2.1). Note that
+if your server and client are both running @sc{cvs}
+1.9.10 or later, @sc{cvs} will not invoke an external
address@hidden program.
+
address@hidden CVS_PID, environment variable
address@hidden $CVS_PID
+This is the process identification (aka pid) number of
+the @sc{cvs} process. It is often useful in the
+programs and/or scripts specified by the
address@hidden, @file{verifymsg}, @file{loginfo}
+files.
address@hidden table
+
address@hidden Compatibility
address@hidden Compatibility between CVS Versions
+
address@hidden CVS, versions of
address@hidden Versions, of CVS
address@hidden Compatibility, between CVS versions
address@hidden We don't mention versions older than CVS 1.3
address@hidden on the theory that it would clutter it up for the vast
address@hidden majority of people, who don't have anything that old.
address@hidden
+The repository format is compatible going back to
address@hidden 1.3. But see @ref{Watches Compatibility}, if
+you have copies of @sc{cvs} 1.6 or older and you want
+to use the optional developer communication features.
address@hidden If you "cvs rm" and commit using 1.3, then you'll
address@hidden want to run "rcs -sdead <file,v>" on each of the
address@hidden files in the Attic if you then want 1.5 and
address@hidden later to recognize those files as dead (I think the
address@hidden symptom if this is not done is that files reappear
address@hidden in joins). (Wait: the above will work but really to
address@hidden be strictly correct we should suggest checking
address@hidden in a new revision rather than just changing the
address@hidden state of the head revision, shouldn't we?).
address@hidden The old convert.sh script was for this, but it never
address@hidden did get updated to reflect use of the RCS "dead"
address@hidden state.
address@hidden Note: this is tricky to document without confusing
address@hidden people--need to carefully say what CVS version we
address@hidden are talking about and keep in mind the distinction
address@hidden between a
address@hidden repository created with 1.3 and on which one now
address@hidden uses 1.5+, and a repository on which one wants to
address@hidden use both versions side by side (e.g. during a
address@hidden transition period).
address@hidden Wait, can't CVS just detect the case in which a file
address@hidden is in the Attic but the head revision is not dead?
address@hidden Not sure whether this should produce a warning or
address@hidden something, and probably needs further thought, but
address@hidden it would appear that the situation can be detected.
address@hidden
address@hidden We might want to separate out the 1.3 compatibility
address@hidden section (for repository & working directory) from the
address@hidden rest--that might help avoid confusing people who
address@hidden are upgrading (for example) from 1.6 to 1.8.
address@hidden
address@hidden A minor incompatibility is if a current version of CVS
address@hidden puts "Nfoo" into CVS/Tag, then CVS 1.9 or older will
address@hidden see this as if there is no tag. Seems to me this is
address@hidden too obscure to mention.
+
+The working directory format is compatible going back
+to @sc{cvs} 1.5. It did change between @sc{cvs} 1.3
+and @sc{cvs} 1.5. If you run @sc{cvs} 1.5 or newer on
+a working directory checked out with @sc{cvs} 1.3,
address@hidden will convert it, but to go back to @sc{cvs}
+1.3 you need to check out a new working directory with
address@hidden 1.3.
+
+The remote protocol is interoperable going back to @sc{cvs} 1.5, but no
+further (1.5 was the first official release with the remote protocol,
+but some older versions might still be floating around). In many
+cases you need to upgrade both the client and the server to take
+advantage of new features and bugfixes, however.
+
address@hidden Perhaps should be saying something here about the
address@hidden "D" lines in Entries (written by CVS 1.9; 1.8 and
address@hidden older don't use them). These are supposed to be
address@hidden compatible in both directions, but I'm not sure
address@hidden they quite are 100%. One common gripe is if you
address@hidden "rm -r" a directory and 1.9 gets confused, as it
address@hidden still sees it in Entries. That one is fixed in
address@hidden (say) 1.9.6. Someone else reported problems with
address@hidden starting with a directory which was checked out with
address@hidden an old version, and then using a new version, and
address@hidden some "D" lines appeared, but not for every
address@hidden directory, causing some directories to be skipped.
address@hidden They weren't sure how to reproduce this, though.
+
address@hidden
---------------------------------------------------------------------
address@hidden Troubleshooting
address@hidden Troubleshooting
+
+If you are having trouble with @sc{cvs}, this appendix
+may help. If there is a particular error message which
+you are seeing, then you can look up the message
+alphabetically. If not, you can look through the
+section on other problems to see if your problem is
+mentioned there.
+
address@hidden
+* Error messages:: Partial list of CVS errors
+* Connection:: Trouble making a connection to a CVS server
+* Other problems:: Problems not readily listed by error message
address@hidden menu
+
+
address@hidden Error messages
address@hidden Partial list of error messages
+
+Here is a partial list of error messages that you may
+see from @sc{cvs}. It is not a complete address@hidden
+is capable of printing many, many error messages, often
+with parts of them supplied by the operating system,
+but the intention is to list the common and/or
+potentially confusing error messages.
+
+The messages are alphabetical, but introductory text
+such as @samp{cvs update: } is not considered in
+ordering them.
+
+In some cases the list includes messages printed by old
+versions of @sc{cvs} (partly because users may not be
+sure which version of @sc{cvs} they are using at any
+particular moment).
address@hidden If we want to start retiring messages, perhaps we
address@hidden should pick a cutoff version (for example, no more
address@hidden messages which are specific to versions before 1.9)
address@hidden and then move the old messages to an "old messages"
address@hidden node rather than deleting them completely.
+
address@hidden @code
address@hidden FIXME: What is the correct way to format a multiline
address@hidden error message here? Maybe @table is the wrong
address@hidden choice? Texinfo gurus?
address@hidden @var{file}:@var{line}: Assertion '@var{text}' failed
+The exact format of this message may vary depending on
+your system. It indicates a bug in @sc{cvs}, which can
+be handled as described in @ref{BUGS}.
+
address@hidden cvs @var{command}: authorization failed: server @var{host}
rejected access
+This is a generic response when trying to connect to a
+pserver server which chooses not to provide a
+specific reason for denying authorization. Check that
+the username and password specified are correct and
+that the @code{CVSROOT} specified is allowed by @samp{--allow-root}
+in @file{inetd.conf}. See @ref{Password authenticated}.
+
address@hidden cvs @var{command}: conflict: removed @var{file} was modified by
second party
+This message indicates that you removed a file, and
+someone else modified it. To resolve the conflict,
+first run @samp{cvs add @var{file}}. If desired, look
+at the other party's modification to decide whether you
+still want to remove it. If you don't want to remove
+it, stop here. If you do want to remove it, proceed
+with @samp{cvs remove @var{file}} and commit your
+removal.
address@hidden Tests conflicts2-142b* in sanity.sh test for this.
+
address@hidden cannot change permissions on temporary directory
address@hidden
+Operation not permitted
address@hidden example
+This message has been happening in a non-reproducible,
+occasional way when we run the client/server testsuite,
+both on Red Hat Linux 3.0.3 and 4.1. We haven't been
+able to figure out what causes it, nor is it known
+whether it is specific to linux (or even to this
+particular machine!). If the problem does occur on
+other unices, @samp{Operation not permitted} would be
+likely to read @samp{Not owner} or whatever the system
+in question uses for the unix @code{EPERM} error. If
+you have any information to add, please let us know as
+described in @ref{BUGS}. If you experience this error
+while using @sc{cvs}, retrying the operation which
+produced it should work fine.
address@hidden This has been seen in a variety of tests, including
address@hidden multibranch-2, multibranch-5, and basic1-24-rm-rm,
address@hidden so it doesn't seem particularly specific to any one
address@hidden test.
+
address@hidden cvs [server aborted]: Cannot check out files into the repository
itself
+The obvious cause for this message (especially for
+non-client/server @sc{cvs}) is that the @sc{cvs} root
+is, for example, @file{/usr/local/cvsroot} and you try
+to check out files when you are in a subdirectory, such
+as @file{/usr/local/cvsroot/test}. However, there is a
+more subtle cause, which is that the temporary
+directory on the server is set to a subdirectory of the
+root (which is also not allowed). If this is the
+problem, set the temporary directory to somewhere else,
+for example @file{/var/tmp}; see @code{TMPDIR} in
address@hidden variables}, for how to set the
+temporary directory.
+
address@hidden cannot commit files as 'root'
+See @samp{'root' is not allowed to commit files}.
+
address@hidden For one example see basica-1a10 in the testsuite
address@hidden For another example, "cvs co ." on NT; see comment
address@hidden at windows-NT/filesubr.c (expand_wild).
address@hidden For another example, "cvs co foo/bar" where foo exists.
address@hidden cannot open CVS/Entries for reading: No such file or directory
+This generally indicates a @sc{cvs} internal error, and
+can be handled as with other @sc{cvs} bugs
+(@pxref{BUGS}). Usually there is a workaround---the
+exact nature of which would depend on the situation but
+which hopefully could be figured out.
+
address@hidden This is more obscure than it might sound; it only
address@hidden happens if you run "cvs init" from a directory which
address@hidden contains a CVS/Root file at the start.
address@hidden cvs [init aborted]: cannot open CVS/Root: No such file or
directory
+This message is harmless. Provided it is not
+accompanied by other errors, the operation has
+completed successfully. This message should not occur
+with current versions of @sc{cvs}, but it is documented
+here for the benefit of @sc{cvs} 1.9 and older.
+
address@hidden cvs server: cannot open /root/.cvsignore: Permission denied
address@hidden cvs [server aborted]: can't chdir(/root): Permission denied
+See @ref{Connection}.
+
address@hidden cvs [checkout aborted]: cannot rename file @var{file} to
CVS/,,@var{file}: Invalid argument
+This message has been reported as intermittently
+happening with @sc{cvs} 1.9 on Solaris 2.5. The cause is
+unknown; if you know more about what causes it, let us
+know as described in @ref{BUGS}.
+
address@hidden cvs address@hidden aborted]: cannot start server via rcmd
+This, unfortunately, is a rather nonspecific error
+message which @sc{cvs} 1.9 will print if you are
+running the @sc{cvs} client and it is having trouble
+connecting to the server. Current versions of @sc{cvs}
+should print a much more specific error message. If
+you get this message when you didn't mean to run the
+client at all, you probably forgot to specify
address@hidden:local:}, as described in @ref{Repository}.
+
address@hidden ci: @var{file},v: bad diff output line: Binary files - and
/tmp/T2a22651 differ
address@hidden 1.9 and older will print this message
+when trying to check in a binary file if
address@hidden is not correctly installed. Re-read the
+instructions that came with your @sc{rcs} distribution
+and the @sc{install} file in the @sc{cvs}
+distribution. Alternately, upgrade to a current
+version of @sc{cvs}, which checks in files itself
+rather than via @sc{rcs}.
+
address@hidden cvs checkout: could not check out @var{file}
+With @sc{cvs} 1.9, this can mean that the @code{co} program
+(part of @sc{rcs}) returned a failure. It should be
+preceded by another error message, however it has been
+observed without another error message and the cause is
+not well-understood. With the current version of @sc{cvs},
+which does not run @code{co}, if this message occurs
+without another error message, it is definitely a @sc{cvs}
+bug (@pxref{BUGS}).
address@hidden My current suspicion is that the RCS in the rcs (not
address@hidden cvs/winnt/rcs57nt.zip) directory on the _Practical_
address@hidden CD is bad (remains to be confirmed).
address@hidden There is also a report of something which looks
address@hidden very similar on SGI, Irix 5.2, so I dunno.
+
address@hidden cvs [login aborted]: could not find out home directory
+This means that you need to set the environment
+variables that @sc{cvs} uses to locate your home directory.
+See the discussion of @code{HOME}, @code{HOMEDRIVE}, and @code{HOMEPATH} in
address@hidden variables}.
+
address@hidden cvs update: could not merge revision @var{rev} of @var{file}: No
such file or directory
address@hidden 1.9 and older will print this message if there was
+a problem finding the @code{rcsmerge} program. Make
+sure that it is in your @code{PATH}, or upgrade to a
+current version of @sc{cvs}, which does not require
+an external @code{rcsmerge} program.
+
address@hidden cvs [update aborted]: could not patch @var{file}: No such file
or directory
+This means that there was a problem finding the
address@hidden program. Make sure that it is in your
address@hidden Note that despite appearances the message
+is @emph{not} referring to whether it can find @var{file}.
+If both the client and the server are running a current
+version of @sc{cvs}, then there is no need for an
+external patch program and you should not see this
+message. But if either client or server is running
address@hidden 1.9, then you need @code{patch}.
+
address@hidden cvs update: could not patch @var{file}; will refetch
+This means that for whatever reason the client was
+unable to apply a patch that the server sent. The
+message is nothing to be concerned about, because
+inability to apply the patch only slows things down and
+has no effect on what @sc{cvs} does.
address@hidden xref to update output. Or File status?
address@hidden Or some place else that
address@hidden explains this whole "patch"/P/Needs Patch thing?
+
address@hidden dying gasps from @var{server} unexpected
+There is a known bug in the server for @sc{cvs} 1.9.18
+and older which can cause this. For me, this was
+reproducible if I used the @samp{-t} global option. It
+was fixed by Andy Piper's 14 Nov 1997 change to
+src/filesubr.c, if anyone is curious.
+If you see the message,
+you probably can just retry the operation which failed,
+or if you have discovered information concerning its
+cause, please let us know as described in @ref{BUGS}.
+
address@hidden end of file from server (consult above messages if any)
+The most common cause for this message is if you are
+using an external @code{rsh} program and it exited with
+an error. In this case the @code{rsh} program should
+have printed a message, which will appear before the
+above message. For more information on setting up a
address@hidden client and server, see @ref{Remote repositories}.
+
address@hidden cvs [update aborted]: EOF in key in RCS file @var{file},v
address@hidden cvs [checkout aborted]: EOF while looking for end of string in
RCS file @var{file},v
+This means that there is a syntax error in the given
address@hidden file. Note that this might be true even if @sc{rcs} can
+read the file OK; @sc{cvs} does more error checking of
+errors in the RCS file. That is why you may see this
+message when upgrading from @sc{cvs} 1.9 to @sc{cvs}
+1.10. The likely cause for the original corruption is
+hardware, the operating system, or the like. Of
+course, if you find a case in which @sc{cvs} seems to
+corrupting the file, by all means report it,
+(@pxref{BUGS}).
+There are quite a few variations of this error message,
+depending on exactly where in the @sc{rcs} file @sc{cvs}
+finds the syntax error.
+
address@hidden mkmodules
address@hidden cvs commit: Executing 'mkmodules'
+This means that your repository is set up for a version
+of @sc{cvs} prior to @sc{cvs} 1.8. When using @sc{cvs}
+1.8 or later, the above message will be preceded by
+
address@hidden
+cvs commit: Rebuilding administrative file database
address@hidden example
+
+If you see both messages, the database is being rebuilt
+twice, which is unnecessary but harmless. If you wish
+to avoid the duplication, and you have no versions of
address@hidden 1.7 or earlier in use, remove @code{-i mkmodules}
+every place it appears in your @code{modules}
+file. For more information on the @code{modules} file,
+see @ref{modules}.
+
address@hidden This message comes from "co", and I believe is
address@hidden possible only with older versions of CVS which call
address@hidden co. The problem with being able to create the bogus
address@hidden RCS file still exists, though (and I think maybe
address@hidden there is a different symptom(s) now).
address@hidden FIXME: Would be nice to have a more exact wording
address@hidden for this message.
address@hidden missing author
+Typically this can happen if you created an RCS file
+with your username set to empty. @sc{cvs} will, bogusly,
+create an illegal RCS file with no value for the author
+field. The solution is to make sure your username is
+set to a non-empty value and re-create the RCS file.
address@hidden "make sure your username is set" is complicated in
address@hidden and of itself, as there are the environment
address@hidden variables the system login name, &c, and it depends
address@hidden on the version of CVS.
+
address@hidden cvs [checkout aborted]: no such tag @var{tag}
+This message means that @sc{cvs} isn't familiar with
+the tag @var{tag}. Usually this means that you have
+mistyped a tag name; however there are (relatively
+obscure) cases in which @sc{cvs} will require you to
address@hidden Search sanity.sh for "no such tag" to see some of
address@hidden the relatively obscure cases.
+try a few other @sc{cvs} commands involving that tag,
+before you find one which will cause @sc{cvs} to update
+the @file{val-tags} file; see discussion of val-tags in
address@hidden permissions}. You only need to worry about
+this once for a given tag; when a tag is listed in
address@hidden, it stays there. Note that using
address@hidden to not require tag matches does not override
+this check; see @ref{Common options}.
+
address@hidden *PANIC* administration files missing
+This typically means that there is a directory named
address@hidden but it does not contain the administrative files
+which @sc{cvs} puts in a CVS directory. If the problem is
+that you created a CVS directory via some mechanism
+other than @sc{cvs}, then the answer is simple, use a name
+other than @sc{cvs}. If not, it indicates a @sc{cvs} bug
+(@pxref{BUGS}).
+
address@hidden rcs error: Unknown option: -x,v/
+This message will be followed by a usage message for
address@hidden It means that you have an old version of
address@hidden (probably supplied with your operating
+system), as well as an old version of @sc{cvs}.
address@hidden 1.9.18 and earlier only work with @sc{rcs} version 5 and
+later; current versions of @sc{cvs} do not run @sc{rcs} programs.
address@hidden For more information on installing @sc{cvs}, see
address@hidden (FIXME: where? it depends on whether you are
address@hidden getting binaries or sources or what).
address@hidden The message can also say "ci error" or something
address@hidden instead of "rcs error", I suspect.
+
address@hidden cvs [server aborted]: received broken pipe signal
+This message seems to be caused by a hard-to-track-down
+bug in @sc{cvs} or the systems it runs on (we don't
+know---we haven't tracked it down yet!). It seems to
+happen only after a @sc{cvs} command has completed, and
+you should be able to just ignore the message.
+However, if you have discovered information concerning its
+cause, please let us know as described in @ref{BUGS}.
+
address@hidden 'root' is not allowed to commit files
+When committing a permanent change, @sc{cvs} makes a log entry of
+who committed the change. If you are committing the change logged
+in as "root" (not under "su" or other root-priv giving program),
address@hidden cannot determine who is actually making the change.
+As such, by default, @sc{cvs} disallows changes to be committed by users
+logged in as "root". (You can disable this option by passing the
address@hidden option to @file{configure} and recompiling @sc{cvs}.
+On some systems this means editing the appropriate @file{config.h} file
+before building @sc{cvs}.)
+
address@hidden Too many arguments!
+This message is typically printed by the @file{log.pl}
+script which is in the @file{contrib} directory in the
address@hidden source distribution. In some versions of
address@hidden, @file{log.pl} has been part of the default
address@hidden installation. The @file{log.pl} script gets
+called from the @file{loginfo} administrative file.
+Check that the arguments passed in @file{loginfo} match
+what your version of @file{log.pl} expects. In
+particular, the @file{log.pl} from @sc{cvs} 1.3 and
+older expects the logfile as an argument whereas the
address@hidden from @sc{cvs} 1.5 and newer expects the
+logfile to be specified with a @samp{-f} option. Of
+course, if you don't need @file{log.pl} you can just
+comment it out of @file{loginfo}.
+
address@hidden cvs [update aborted]: unexpected EOF reading @var{file},v
+See @samp{EOF in key in RCS file}.
+
address@hidden cvs [login aborted]: unrecognized auth response from @var{server}
+This message typically means that the server is not set
+up properly. For example, if @file{inetd.conf} points
+to a nonexistent cvs executable. To debug it further,
+find the log file which inetd writes
+(@file{/var/log/messages} or whatever inetd uses on
+your system). For details, see @ref{Connection}, and
address@hidden authentication server}.
+
address@hidden cvs commit: Up-to-date check failed for address@hidden'
+This means that someone else has committed a change to
+that file since the last time that you did a @code{cvs
+update}. So before proceeding with your @code{cvs
+commit} you need to @code{cvs update}. @sc{cvs} will merge
+the changes that you made and the changes that the
+other person made. If it does not detect any conflicts
+it will report @samp{M @var{file}} and you are ready
+to @code{cvs commit}. If it detects conflicts it will
+print a message saying so, will report @samp{C @var{file}},
+and you need to manually resolve the
+conflict. For more details on this process see
address@hidden example}.
+
address@hidden Usage: diff3 [-exEX3 [-i | -m] [-L label1 -L label3]] file1
file2 file3
address@hidden
+Only one of [exEX3] allowed
address@hidden example
+This indicates a problem with the installation of
address@hidden and @code{rcsmerge}. Specifically
address@hidden was compiled to look for GNU diff3, but
+it is finding unix diff3 instead. The exact text of
+the message will vary depending on the system. The
+simplest solution is to upgrade to a current version of
address@hidden, which does not rely on external
address@hidden or @code{diff3} programs.
+
address@hidden warning: unrecognized response address@hidden' from cvs server
+If @var{text} contains a valid response (such as
address@hidden) followed by an extra carriage return
+character (on many systems this will cause the second
+part of the message to overwrite the first part), then
+it probably means that you are using the @samp{:ext:}
+access method with a version of rsh, such as most
+non-unix rsh versions, which does not by default
+provide a transparent data stream. In such cases you
+probably want to try @samp{:server:} instead of
address@hidden:ext:}. If @var{text} is something else, this
+may signify a problem with your @sc{cvs} server.
+Double-check your installation against the instructions
+for setting up the @sc{cvs} server.
address@hidden FIXCVS: should be printing CR as \r or \015 or some
address@hidden such, probably.
+
address@hidden cvs commit: address@hidden waiting for @var{user}'s lock in
@var{directory}
+This is a normal message, not an error. See
address@hidden, for more details.
+
address@hidden cvs commit: warning: editor session failed
address@hidden Exit status, of editor
+This means that the editor which @sc{cvs} is using exits with a nonzero
+exit status. Some versions of vi will do this even when there was not
+a problem editing the file. If so, point the
address@hidden environment variable to a small script
+such as:
+
address@hidden
+#!/bin/sh
+vi $*
+exit 0
address@hidden example
+
address@hidden "warning: foo was lost" and "no longer pertinent" (both normal).
address@hidden Would be nice to write these up--they are
address@hidden potentially confusing for the new user.
address@hidden table
+
address@hidden Connection
address@hidden Trouble making a connection to a CVS server
+
+This section concerns what to do if you are having
+trouble making a connection to a @sc{cvs} server. If
+you are running the @sc{cvs} command line client
+running on Windows, first upgrade the client to
address@hidden 1.9.12 or later. The error reporting in
+earlier versions provided much less information about
+what the problem was. If the client is non-Windows,
address@hidden 1.9 should be fine.
+
+If the error messages are not sufficient to track down
+the problem, the next steps depend largely on which
+access method you are using.
+
address@hidden @code
address@hidden :ext:, troubleshooting
address@hidden :ext:
+Try running the rsh program from the command line. For
+example: "rsh servername cvs -v" should print @sc{cvs}
+version information. If this doesn't work, you need to
+fix it before you can worry about @sc{cvs} problems.
+
address@hidden :server:, troubleshooting
address@hidden :server:
+You don't need a command line rsh program to use this
+access method, but if you have an rsh program around,
+it may be useful as a debugging tool. Follow the
+directions given for :ext:.
+
address@hidden :pserver:, troubleshooting
address@hidden :pserver:
+Errors along the lines of "connection refused" typically indicate
+that inetd isn't even listening for connections on port 2401
+whereas errors like "connection reset by peer",
+"received broken pipe signal", "recv() from server: EOF",
+or "end of file from server"
+typically indicate that inetd is listening for
+connections but is unable to start @sc{cvs} (this is frequently
+caused by having an incorrect path in @file{inetd.conf}
+or by firewall software rejecting the connection).
+"unrecognized auth response" errors are caused by a bad command
+line in @file{inetd.conf}, typically an invalid option or forgetting
+to put the @samp{pserver} command at the end of the line.
+Another less common problem is invisible control characters that
+your editor "helpfully" added without you noticing.
+
+One good debugging tool is to "telnet servername
+2401". After connecting, send any text (for example
+"foo" followed by return). If @sc{cvs} is working
+correctly, it will respond with
+
address@hidden
+cvs [pserver aborted]: bad auth protocol start: foo
address@hidden example
+
+If instead you get:
+
address@hidden
+Usage: cvs [cvs-options] command [command-options-and-arguments]
+...
address@hidden example
+
address@hidden
+then you're missing the @samp{pserver} command at the end of the
+line in @file{inetd.conf}; check to make sure that the entire command
+is on one line and that it's complete.
+
+Likewise, if you get something like:
+
address@hidden
+Unknown command: `pserved'
+
+CVS commands are:
+ add Add a new file/directory to the repository
+...
address@hidden example
+
address@hidden
+then you've misspelled @samp{pserver} in some way. If it isn't
+obvious, check for invisible control characters (particularly
+carriage returns) in @file{inetd.conf}.
+
+If it fails to work at all, then make sure inetd is working
+right. Change the invocation in @file{inetd.conf} to run the
+echo program instead of cvs. For example:
+
address@hidden
+2401 stream tcp nowait root /bin/echo echo hello
address@hidden example
+
+After making that change and instructing inetd to
+re-read its configuration file, "telnet servername
+2401" should show you the text hello and then the
+server should close the connection. If this doesn't
+work, you need to fix it before you can worry about
address@hidden problems.
+
+On AIX systems, the system will often have its own
+program trying to use port 2401. This is AIX's problem
+in the sense that port 2401 is registered for use with
address@hidden I hear that there is an AIX patch available
+to address this problem.
+
+Another good debugging tool is the @samp{-d}
+(debugging) option to inetd. Consult your system
+documentation for more information.
+
+If you seem to be connecting but get errors like:
+
address@hidden
+cvs server: cannot open /root/.cvsignore: Permission denied
+cvs [server aborted]: can't chdir(/root): Permission denied
address@hidden example
+
address@hidden
+then you probably haven't specified @samp{-f} in @file{inetd.conf}.
+(In releases prior to @sc{cvs} 1.11.1, this problem can be caused by
+your system setting the @code{$HOME} environment variable
+for programs being run by inetd. In this case, you can either
+have inetd run a shell script that unsets @code{$HOME} and then runs
address@hidden, or you can use @code{env} to run @sc{cvs} with a pristine
+environment.)
+
+If you can connect successfully for a while but then can't,
+you've probably hit inetd's rate limit.
+(If inetd receives too many requests for the same service
+in a short period of time, it assumes that something is wrong
+and temporarily disables the service.)
+Check your inetd documentation to find out how to adjust the
+rate limit (some versions of inetd have a single rate limit,
+others allow you to set the limit for each service separately.)
address@hidden table
+
address@hidden Other problems
address@hidden Other common problems
+
+Here is a list of problems which do not fit into the
+above categories. They are in no particular order.
+
address@hidden @bullet
address@hidden
+On Windows, if there is a 30 second or so delay when
+you run a @sc{cvs} command, it may mean that you have
+your home directory set to @file{C:/}, for example (see
address@hidden and @code{HOMEPATH} in
address@hidden variables}). @sc{cvs} expects the home
+directory to not end in a slash, for example @file{C:}
+or @file{C:\cvs}.
address@hidden FIXCVS: CVS should at least detect this and print an
address@hidden error, presumably.
+
address@hidden
+If you are running @sc{cvs} 1.9.18 or older, and
address@hidden update} finds a conflict and tries to
+merge, as described in @ref{Conflicts example}, but
+doesn't tell you there were conflicts, then you may
+have an old version of @sc{rcs}. The easiest solution
+probably is to upgrade to a current version of
address@hidden, which does not rely on external @sc{rcs}
+programs.
address@hidden itemize
+
address@hidden
---------------------------------------------------------------------
address@hidden Credits
address@hidden Credits
+
address@hidden Contributors (manual)
address@hidden Credits (manual)
+Roland Pesch, then of Cygnus Support <@t{roland@@wrs.com}>
+wrote the manual pages which were distributed with
address@hidden 1.3. Much of their text was copied into this
+manual. He also read an early draft
+of this manual and contributed many ideas and
+corrections.
+
+The mailing-list @code{info-cvs} is sometimes
+informative. I have included information from postings
+made by the following persons:
+David G. Grubbs <@t{dgg@@think.com}>.
+
+Some text has been extracted from the man pages for
address@hidden
+
+The @sc{cvs} @sc{faq} by David G. Grubbs has provided
+useful material. The @sc{faq} is no longer maintained,
+however, and this manual is about the closest thing there
+is to a successor (with respect to documenting how to
+use @sc{cvs}, at least).
+
+In addition, the following persons have helped by
+telling me about mistakes I've made:
+
address@hidden
+Roxanne Brunskill <@t{rbrunski@@datap.ca}>,
+Kathy Dyer <@t{dyer@@phoenix.ocf.llnl.gov}>,
+Karl Pingle <@t{pingle@@acuson.com}>,
+Thomas A Peterson <@t{tap@@src.honeywell.com}>,
+Inge Wallin <@t{ingwa@@signum.se}>,
+Dirk Koschuetzki <@t{koschuet@@fmi.uni-passau.de}>
+and Michael Brown <@t{brown@@wi.extrel.com}>.
address@hidden display
+
+The list of contributors here is not comprehensive; for a more
+complete list of who has contributed to this manual see
+the file @file{doc/ChangeLog} in the @sc{cvs} source
+distribution.
+
address@hidden
---------------------------------------------------------------------
address@hidden BUGS
address@hidden Dealing with bugs in CVS or this manual
+
address@hidden Bugs in this manual or CVS
+Neither @sc{cvs} nor this manual is perfect, and they
+probably never will be. If you are having trouble
+using @sc{cvs}, or think you have found a bug, there
+are a number of things you can do about it. Note that
+if the manual is unclear, that can be considered a bug
+in the manual, so these problems are often worth doing
+something about as well as problems with @sc{cvs} itself.
+
address@hidden Reporting bugs
address@hidden Bugs, reporting
address@hidden Errors, reporting
address@hidden @bullet
address@hidden
+If you want someone to help you and fix bugs that you
+report, there are companies which will do that for a
+fee. One such company is:
+
address@hidden Ximbiot
address@hidden Support, getting CVS support
address@hidden
+Ximbiot
+319 S. River St.
+Harrisburg, PA 17104-1657
+USA
+Email: info@@ximbiot.com
+Phone: (717) 579-6168
+Fax: (717) 234-3125
+http://ximbiot.com/
+
address@hidden example
+
address@hidden
+If you got @sc{cvs} through a distributor, such as an
+operating system vendor or a vendor of freeware
address@hidden, you may wish to see whether the
+distributor provides support. Often, they will provide
+no support or minimal support, but this may vary from
+distributor to distributor.
+
address@hidden
+If you have the skills and time to do so, you may wish
+to fix the bug yourself. If you wish to submit your
+fix for inclusion in future releases of @sc{cvs}, see
+the file @sc{hacking} in the @sc{cvs} source
+distribution. It contains much more information on the
+process of submitting fixes.
+
address@hidden
+There may be resources on the net which can help. Two
+good places to start are:
+
address@hidden
+http://www.cvshome.org
+http://www.loria.fr/~molli/cvs-index.html
address@hidden example
+
+If you are so inspired, increasing the information
+available on the net is likely to be appreciated. For
+example, before the standard @sc{cvs} distribution
+worked on Windows 95, there was a web page with some
+explanation and patches for running @sc{cvs} on Windows
+95, and various people helped out by mentioning this
+page on mailing lists or newsgroups when the subject
+came up.
+
address@hidden
+It is also possible to report bugs to @code{bug-cvs}.
+Note that someone may or may not want to do anything
+with your bug report---if you need a solution consider
+one of the options mentioned above. People probably do
+want to hear about bugs which are particularly severe
+in consequences and/or easy to fix, however. You can
+also increase your odds by being as clear as possible
+about the exact nature of the bug and any other
+relevant information. The way to report bugs is to
+send email to @code{bug-cvs@@gnu.org}. Note
+that submissions to @code{bug-cvs} may be distributed
+under the terms of the @sc{gnu} Public License, so if
+you don't like this, don't submit them. There is
+usually no justification for sending mail directly to
+one of the @sc{cvs} maintainers rather than to
address@hidden; those maintainers who want to hear
+about such bug reports read @code{bug-cvs}. Also note
+that sending a bug report to other mailing lists or
+newsgroups is @emph{not} a substitute for sending it to
address@hidden It is fine to discuss @sc{cvs} bugs on
+whatever forum you prefer, but there are not
+necessarily any maintainers reading bug reports sent
+anywhere except @code{bug-cvs}.
address@hidden itemize
+
address@hidden Known bugs in this manual or CVS
+People often ask if there is a list of known bugs or
+whether a particular bug is a known one. The file
address@hidden in the @sc{cvs} source distribution is one
+list of known bugs, but it doesn't necessarily try to
+be comprehensive. Perhaps there will never be a
+comprehensive, detailed list of known bugs.
+
address@hidden
---------------------------------------------------------------------
address@hidden Index
address@hidden Index
address@hidden Index
+
address@hidden cp
+
address@hidden
+
address@hidden
+
address@hidden
Index: res_all/texi_hello/hello.texi.first
===================================================================
RCS file: res_all/texi_hello/hello.texi.first
diff -N res_all/texi_hello/hello.texi.first
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ res_all/texi_hello/hello.texi.first 2 Aug 2009 13:11:02 -0000 1.1
@@ -0,0 +1,789 @@
+\input texinfo @c -*-texinfo-*-
address@hidden %**start of header
address@hidden hello.info
address@hidden UPDATED 28 March 2002
address@hidden UPDATED-MONTH March 2002
address@hidden EDITION 4.2
address@hidden VERSION 4.2
address@hidden GNU Hello 4.2
address@hidden %**end of header
+
address@hidden If your manual is published on paper by the FSF, it should
include
address@hidden the standard FSF Front-Cover and Back-Cover Texts, as given in
address@hidden maintain.texi.
+
address@hidden Define a new index for options.
address@hidden op
address@hidden Combine everything into one index (arbitrarily chosen to be the
address@hidden concept index).
address@hidden op cp
+
address@hidden Basics
address@hidden
+* Hello: (hello). Hello, GNU world.
address@hidden direntry
+
+
address@hidden
+
+
address@hidden Top
address@hidden GNU Hello
+
+This manual is for GNU Hello (version 4.2, 28 March 2002).
+
address@hidden
+* Overview:: General purpose and information.
+* Sample output:: Sample output from @command{hello}.
+* Invoking hello:: How to run @command{hello}.
+* Reporting bugs:: Sending bug reports and feature suggestions.
+* GNU Free Documentation License:: Copying and sharing this documentation.
+* Concept index:: Index of concepts.
address@hidden menu
+
+
address@hidden Overview
address@hidden Overview
+
address@hidden greetings
address@hidden overview
+
+The GNU @command{hello} program
+(@url{http://www.gnu.org/software/hello/}) produces a familiar,
+friendly greeting. It allows nonprogrammers to use a classic computer
+science tool which would otherwise be unavailable to them. Because it
+is protected by the GNU General Public License, users are free (in
+perpetuity) to share and change it.
+
address@hidden joke, not
+Not to spoil the joke, but of course the practical purpose of GNU
+Hello is to serve as a minimal example of a GNU package. So, although
+most manuals don't need to discuss the implementation of the programs
+they document, that is part of the goal here.
+
address@hidden GNU coding standards
address@hidden GNU maintainer standards
address@hidden standards, GNU coding
address@hidden standards, GNU maintainer
+First, GNU Hello follows the GNU coding standards
+(@pxref{Top,,Preface,standards, GNU Coding Standards}) and GNU
+maintainer standards (@pxref{Top,,Preface,maintain, Information for
+GNU Maintainers}). These are the basic documents which all GNU
+packages should adhere to.
+
+The Hello package also implements recommended development practices
+not embodied in the standards, using other GNU packages and features:
+
address@hidden @bullet
+
address@hidden
address@hidden Automake
address@hidden Autoconf
+It uses Automake (@pxref{Top,,Introduction,Automake,GNU Automake}) and
+hence also Autoconf (@pxref{Top,,Introduction,Autoconf,GNU Autoconf})
+for configuration.
+
address@hidden
address@hidden Gnulib
+It uses Gnulib (@pxref{Top,,Gnulib,gnulib,GNU Gnulib}) to enhance
+portability and avoid duplication of common sources.
+
address@hidden
address@hidden Gettext
+GNU Gettext (@pxref{Top,,Introduction,gettext,GNU Gettext}) is used
+for internationalization support. Hello's greeting has been translated
+into many languages.
+
address@hidden
address@hidden --help
+Internally, Hello uses the GNU @code{getopt_long} function
+(@pxref{Getopt Long Options,,,libc,GNU C Library}) to parse options,
+thus supporting GNU-style long options such as @option{--help}.
+
address@hidden
address@hidden Help2man
+Man pages are generated with GNU @code{help2man}
+(@pxref{Top,,Overview,help2man,GNU @code{help2man}}) from the
address@hidden output. This relieves the maintainers of the burden
+of maintaining man documentation separately, yet provides a reasonable
+overview for man devotees.
+
address@hidden
address@hidden Texinfo
+Finally, Texinfo (@pxref{Top,,Introduction,texinfo,Texinfo}) is the
+documentation format for this manual. It supports output in Info,
+HTML, PDF, DVI, plain text, XML, and other formats.
+
address@hidden itemize
+
+GNU Hello is implemented in C. GNU Gettext contains ``hello world''
+examples in a variety of other programming languages; see the Gettext
+home page at @url{http://www.gnu.org/software/gettext/}.
+
address@hidden authors
address@hidden Haertel, Mike
address@hidden MacKenzie, David
address@hidden Brittenson, Jan
address@hidden Hannum, Charles
address@hidden McGrath, Roland
address@hidden Friedman, Noah
address@hidden Eichwalder, Karl
address@hidden King, The
address@hidden Berry, Karl
+GNU Hello was written by Mike Haertel, David MacKenzie, Jan
+Brittenson, Charles Hannum, Roland McGrath, Noah Friedman, Karl
+Eichwalder, Karl Berry, and @w{The King}.
+
+
address@hidden Sample output
address@hidden Sample output
+
address@hidden sample output
address@hidden examples
+
+Here are some realistic examples of running GNU Hello.
+
+This is the output of the command @samp{hello}:
+
address@hidden
+Hello, world!
address@hidden example
+
+This is the output of the command @samp{hello --traditional}:
+
address@hidden
+hello, world
address@hidden example
+
+This is the output of the command @samp{hello --greeting=hi}:
+
address@hidden
+hi
address@hidden example
+
+
address@hidden Invoking hello
address@hidden Invoking @command{hello}
+
address@hidden invoking
address@hidden options
address@hidden usage
address@hidden help
+
+The format for running the @command{hello} program is:
+
address@hidden
+hello @var{option} @dots{}
address@hidden example
+
+With no options, @command{hello} prints the greeting @samp{Hello,
+world!}.
+
address@hidden supports the following options:
+
address@hidden @option
address@hidden address@hidden
address@hidden -g @var{text}
address@hidden --greeting
address@hidden -g
+Output @var{text} instead of the default greeting.
+
address@hidden --help
address@hidden -h
address@hidden --help
address@hidden -h
+Print an informative help message on standard output and exit
+successfully.
+
address@hidden environment variables, help for
+For the @option{--help} output of GNU programs, it's strongly
+encouraged to include a brief (one or two sentences) description of
+what the program does, as well as the synopsis of how to run the
+program. Any environment variables which affect execution should also
+be mentioned (Hello doesn't have any).
+
address@hidden --next-generation
address@hidden -n
address@hidden --next-generation
address@hidden -n
+Output @samp{Hello, world!}, but possibly including box-drawing
+characters or other fancy stuff, especially in translated locales.
+(If you would like to volunteer to translate messages for GNU packages,
+please see @url{http://translationproject.org}.)
+
address@hidden --traditional
address@hidden -t
address@hidden --traditional
address@hidden -t
address@hidden traditional
address@hidden modern
+Output the traditional greeting message @samp{hello, world}.
+
address@hidden --version
address@hidden -v
address@hidden --version
address@hidden -v
+Print the version number and licensing information of Hello on
+standard output and then exit successfully.
+
address@hidden table
+
+If more than one of the greeting options (@option{-g}, @option{-n},
address@hidden, and their long-named equivalents) is specified, whichever
+comes last takes precedence.
+
+
address@hidden Reporting bugs
address@hidden Reporting bugs
+
address@hidden bug reporting
address@hidden problems
address@hidden reporting bugs
+
+To report bugs or suggest enhancements for GNU Hello, please
+send electronic mail to @email{bug-hello@@gnu.org}.
+
address@hidden checklist for bug reports
+For bug reports, please include enough information for the maintainers
+to reproduce the problem. Generally speaking, that means:
+
address@hidden @bullet
address@hidden The version numbers of Hello (which you can find by running
+ @address@hidden --version}}) and any other program(s) or
+ manual(s) involved.
address@hidden Hardware and operating system names and versions.
address@hidden The contents of any input files necessary to reproduce the bug.
address@hidden The expected behavior and/or output.
address@hidden A description of the problem and samples of any erroneous output.
address@hidden Options you gave to @command{configure} other than specifying
+ installation directories.
address@hidden Anything else that you think would be helpful.
address@hidden 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.
+
address@hidden patches, contributing
+Patches are welcome; if possible, please make them with @address@hidden
+-c}} (@pxref{Top,, Overview, diff, Comparing and Merging Files}) and
+include @file{ChangeLog} entries (@pxref{Change Log,,, emacs, The GNU
+Emacs Manual}). Please follow the existing coding style.
+
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
+
address@hidden The GNU Free Documentation License.
address@hidden Version 1.3, 3 November 2008
+
address@hidden This file is intended to be included within another document,
address@hidden hence no sectioning command or @node.
+
address@hidden
+Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation,
Inc.
address@hidden://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
address@hidden display
+
address@hidden 0
address@hidden
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{free} in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
address@hidden
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The ``Document'', below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as ``you''. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section
+of the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall
+subject (or to related matters) and contains nothing that could fall
+directly within that overall subject. (Thus, if the Document is in
+part a textbook of mathematics, a Secondary Section may not explain
+any mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
address@hidden without markup, Texinfo input format, address@hidden input
+format, @acronym{SGML} or @acronym{XML} using a publicly available
address@hidden, and standard-conforming simple @acronym{HTML},
+PostScript or @acronym{PDF} designed for human modification. Examples
+of transparent image formats include @acronym{PNG}, @acronym{XCF} and
address@hidden Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, @acronym{SGML} or
address@hidden for which the @acronym{DTD} and/or processing tools are
+not generally available, and the machine-generated @acronym{HTML},
+PostScript or @acronym{PDF} produced by some word processors for
+output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+The ``publisher'' means any person or entity that distributes copies
+of the Document to the public.
+
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements'',
+``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
address@hidden
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
address@hidden
+COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
address@hidden
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
address@hidden A
address@hidden
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
address@hidden
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
+
address@hidden
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
address@hidden
+Preserve all the copyright notices of the Document.
+
address@hidden
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
address@hidden
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
address@hidden
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
address@hidden
+Include an unaltered copy of this License.
+
address@hidden
+Preserve the section Entitled ``History'', Preserve its Title, and add
+to it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section Entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
address@hidden
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
address@hidden
+For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
+the Title of the section, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements and/or
+dedications given therein.
+
address@hidden
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
address@hidden
+Delete any section Entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
address@hidden
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
address@hidden
+Preserve any Warranty Disclaimers.
address@hidden enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
address@hidden
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements'',
+and any sections Entitled ``Dedications''. You must delete all
+sections Entitled ``Endorsements.''
+
address@hidden
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
address@hidden
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
address@hidden
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
address@hidden
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document
+except as expressly provided under this License. Any attempt
+otherwise to copy, modify, sublicense, or distribute it is void, and
+will automatically terminate your rights under this License.
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License. If your rights have been terminated and not permanently
+reinstated, receipt of a copy of some or all of the same material does
+not give you any rights to use it.
+
address@hidden
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
address@hidden://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation. If the Document
+specifies that a proxy can decide which future versions of this
+License can be used, that proxy's public statement of acceptance of a
+version permanently authorizes you to choose that version for the
+Document.
+
address@hidden
+RELICENSING
+
+``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
+World Wide Web server that publishes copyrightable works and also
+provides prominent facilities for anybody to edit those works. A
+public wiki that anybody can edit is an example of such a server. A
+``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
+site means any set of copyrightable works thus published on the MMC
+site.
+
+``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
+license published by Creative Commons Corporation, a not-for-profit
+corporation with a principal place of business in San Francisco,
+California, as well as future copyleft versions of that license
+published by that same organization.
+
+``Incorporate'' means to publish or republish a Document, in whole or
+in part, as part of another Document.
+
+An MMC is ``eligible for relicensing'' if it is licensed under this
+License, and if all works that were first published under this License
+somewhere other than this MMC, and subsequently incorporated in whole
+or in part into the MMC, (1) had no cover texts or invariant sections,
+and (2) were thus incorporated prior to November 1, 2008.
+
+The operator of an MMC Site may republish an MMC contained in the site
+under CC-BY-SA on the same site at any time before August 1, 2009,
+provided the MMC is eligible for relicensing.
+
address@hidden enumerate
+
address@hidden
address@hidden ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
address@hidden
address@hidden
+ Copyright (C) @var{year} @var{your name}.
+ 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, no Front-Cover Texts, and no Back-Cover
+ Texts. A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
address@hidden group
address@hidden smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the address@hidden'' line with this:
+
address@hidden
address@hidden
+ with the Invariant Sections being @var{list their titles}, with
+ the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
+ being @var{list}.
address@hidden group
address@hidden smallexample
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
address@hidden Local Variables:
address@hidden ispell-local-pdict: "ispell-dict"
address@hidden End:
+
+
+
address@hidden Concept index
address@hidden Concept index
+
address@hidden cp
+
address@hidden
Index: res_all/texi_info-stnd/info-stnd.texi.first
===================================================================
RCS file: res_all/texi_info-stnd/info-stnd.texi.first
diff -N res_all/texi_info-stnd/info-stnd.texi.first
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ res_all/texi_info-stnd/info-stnd.texi.first 2 Aug 2009 13:11:02 -0000
1.1
@@ -0,0 +1,2521 @@
+\input texinfo @c -*-texinfo-*-
address@hidden Id: info-stnd.texi,v 1.1 2003/02/03 16:10:29 pertusus Exp $
address@hidden %**start of header
address@hidden info-stnd.info
address@hidden UPDATED 23 March 2002
address@hidden UPDATED-MONTH March 2002
address@hidden EDITION 4.2
address@hidden VERSION 4.2
address@hidden GNU Info 4.2
address@hidden vr cp
address@hidden fn cp
address@hidden ky cp
address@hidden %**end of header
+
+
address@hidden Texinfo documentation system
address@hidden
+* info standalone: (info-stnd). Read Info documents without Emacs.
+* infokey: (info-stnd)Invoking infokey. Compile Info customizations.
address@hidden direntry
+
+
address@hidden
+
address@hidden Top
address@hidden GNU Info
+
address@hidden
+
+This documentation is different from the documentation for the Info
+reader that is part of GNU Emacs. If you do not know how to use Info,
+but have a working Info reader, you should read the Emacs documentation
+first, as it includes more background information and a thorough tutorial.
+
address@hidden
+* What is Info:: What is Info?
+* Invoking Info:: Options you can pass on the command line.
+* Cursor Commands:: Commands which move the cursor within a node.
+* Scrolling Commands:: Commands for reading the text within a node.
+* Node Commands:: Commands for selecting a new node.
+* Searching Commands:: Commands for searching an Info file.
+* Xref Commands:: Commands for selecting cross references.
+* Window Commands:: Commands which manipulate multiple windows.
+* Printing Nodes:: How to print out the contents of a node.
+* Miscellaneous Commands:: A few commands that defy categories.
+* Variables:: How to change the default behavior of Info.
+* Custom Key Bindings:: How to define your own key-to-command
+ bindings.
+* Copying This Manual:: The GNU Free Documentation License.
+* Index:: Global index containing keystrokes,
+ command names, variable names,
+ and general concepts.
address@hidden menu
+
+
address@hidden What is Info
address@hidden What is Info?
+
address@hidden is a program which is used to view Info files on an ASCII
+terminal. @dfn{Info files} are the result of processing Texinfo files
+with the program @code{makeinfo} or with one of the Emacs commands, such
+as @code{M-x texinfo-format-buffer}. Texinfo itself is a documentation
+system that uses a single source file to produce both on-line
+information and printed output. You can typeset and print the files
+that you read in Info.
+
+
address@hidden Invoking Info
address@hidden Invoking Info
+
address@hidden Info, invoking
address@hidden invoking Info
address@hidden command line options
address@hidden options, command line
address@hidden arguments, command line
+
+GNU Info accepts several options to control the initial node being
+viewed, and to specify which directories to search for Info files. Here
+is a template showing an invocation of GNU Info from the shell:
+
address@hidden
+info address@hidden@dots{} address@hidden@dots{}]
address@hidden example
+
+The program accepts the following options:
+
address@hidden @code
address@hidden
address@hidden address@hidden
address@hidden Searching all indices
address@hidden Info address@hidden, searching all indices}
address@hidden address@hidden, in Info files}
+Specify a string to search in every index of every Info file installed
+on your system. Info looks up the named @var{string} in all the indices
+it can find, prints the results to standard output, and then exits. If
+you are not sure which Info file explains certain issues, this option is
+your friend. Note that if your system has a lot of Info files
+installed, searching all of them might take some time.
+
+You can invoke the apropos command from inside Info; see
address@hidden Commands}.
+
address@hidden directory path
address@hidden --directory @var{directory-path}
address@hidden -d @var{directory-path}
+Prepend @var{directory-path} to the list of directory paths searched
+when Info needs to find a file. You may issue @code{--directory}
+multiple times; once for each directory which contains Info files. The
+list of directories searched by Info is constructed from the value of
+the environment variable @code{INFOPATH}; @code{--directory} causes the
+named @var{directory-path} to be prepended to that list. The value of
address@hidden is a list of directories usually separated by a colon;
+on MS-DOS/MS-Windows systems, the semicolon is used. If you do not
+define @code{INFOPATH}, Info uses a default path defined when Info was
+built as the initial list of directories. If the value of
address@hidden ends with a colon (or semicolon on MS-DOS/MS-Windows),
+the initial list of directories is constructed by appending the
+build-time default to the value of @code{INFOPATH}.
+
address@hidden keystrokes, recording
address@hidden remembering user keystrokes
address@hidden address@hidden
+Specify a file where all user keystrokes will be recorded. This file
+can be used later to replay the same sequence of commands, see the
address@hidden option below.
+
address@hidden --file @var{filename}
address@hidden -f @var{filename}
address@hidden Info file, selecting
+Specify a particular Info file to visit. By default, Info visits
+the file @code{dir}; if you use this option, Info will start with
address@hidden(@var{filename})Top} as the first file and node.
+
address@hidden relative Info file names
address@hidden file names, relative
address@hidden Info files, relative
+If @var{filename} is an absolute file name, or begins with @file{./} or
address@hidden/}, Info looks for @var{filename} only in the directory of the
+specified @var{filename}, and adds the directory of @var{filename} to
+the value of @code{INFOPATH}. In contrast, if @var{filename} is in the
+form of a relative file name, but without the @file{./} or @file{../}
+prefix, Info will only look for it in the directories specified in
address@hidden In other words, Info does @emph{not} treat file names
+which lack @file{./} and @file{../} prefix as relative to the current
+directory.
+
address@hidden compressed Info files
address@hidden files, compressed
address@hidden Info files, compressed
+In every directory Info tries, if @var{filename} is not found, Info
+looks for it with a number of known extensions of Info address@hidden
address@hidden, @file{-info}, @file{/index}, and @file{.inf}.}. For every
+known extension, Info looks for a compressed file, if a regular file
+isn't found. Info supports files compressed with @code{gzip},
address@hidden, @code{compress} and @code{yabba} programs; it calls
address@hidden, @code{bunzip2}, @code{uncompress} and @code{unyabba},
+accordingly, to decompress such files. Compressed Info files are
+assumed to have @file{.z}, @file{.gz}, @file{.bz2}, @file{.Z}, or
address@hidden extensions, possibly in addition to one of the known Info
+files address@hidden MS-DOS version allows for the Info
+extension, such as @code{.inf}, and the short compressed file
+extensions, such as @file{.z} and @file{.gz}, to be merged into a single
+extension, since DOS doesn't allow more than a single dot in the
+basename of a file. Thus, on MS-DOS, if Info looks for @file{bison},
+file names like @file{bison.igz} and @file{bison.inz} will be found and
+decompressed by @code{gunzip}.}.
+
address@hidden --help
address@hidden -h
+Produces a relatively brief description of the available Info options.
+
address@hidden --index-search @var{string}
address@hidden index search, selecting from the command line
address@hidden online help, using Info as
+After processing all command-line arguments, go to the index in the Info
+file and search for index entries which matche @var{string}. If such an
+entry is found, the Info session begins with displaying the node pointed
+to by the first matching index entry; press @kbd{,} to step through the
+rest of the matching entries. If no such entry exists, print @samp{no
+entries found} and exit with nonzero status. This can be used from
+another program as a way to provide online help, or as a quick way of
+starting to read an Info file at a certain node when you don't know the
+exact name of that node.
+
+This command can also be invoked from inside Info; see @ref{Searching
+Commands}.
+
address@hidden --node @var{nodename}
address@hidden -n @var{nodename}
address@hidden node, selecting from the command line
+Specify a particular node to visit in the initial file that Info
+loads. This is especially useful in conjunction with
address@hidden@footnote{Of course, you can specify both the file and node
+in a @code{--node} command; but don't forget to escape the open and
+close parentheses and whitespace from the shell as in: @code{info --node
+"(emacs)Buffers"}.}. You may specify @code{--node} multiple times; for
+an interactive Info, each @var{nodename} is visited in its own window,
+for a non-interactive Info (such as when @code{--output} is given) each
address@hidden is processed sequentially.
+
address@hidden --output @var{filename}
address@hidden -o @var{filename}
address@hidden file, outputting to
address@hidden outputting to a file
+Specify @var{filename} as the name of a file to which to direct output.
+Each node that Info visits will be output to @var{filename} instead of
+interactively viewed. A value of @code{-} for @var{filename} specifies
+the standard output.
+
address@hidden colors in man pages
address@hidden ANSI escape sequences in man pages
address@hidden --raw-escapes
address@hidden -R
+Do not remove ANSI escape sequences from man pages. Some versions of
+Groff, the GNU document formatter, produce man pages with ANSI escape
+sequences for bold, italics, and underlined characters, and for
+colorized text. By default, Info removes those escape sequences
+before it displays the man page. If your terminal supports these
+escapes, use @code{--raw-escapes} to let the terminal handle them and
+display the man pages with those attributes.
+
address@hidden replaying recorded keystrokes
address@hidden address@hidden
+Read keystrokes from @var{dribble-file}, presumably recorded during
+previous Info session (see the description of the @samp{--dribble}
+option above). When the keystrokes in the files are all read, Info
+reverts its input to the usual interactive operation.
+
address@hidden
address@hidden command-line options, how to find
address@hidden invocation description, how to find
address@hidden --show-options
address@hidden --usage
address@hidden -O
+This option causes Info to look for the node that describes how to
+invoke the program and its command-line options, and begin the session
+by displaying that node. It is provided to make it easier to find the
+most important usage information in a manual without the need to wade
+through complex menu hierarchies. The effect is similar to the
address@hidden goto-invocation} command (@pxref{goto-invocation}) from inside
+Info.
+
address@hidden speech synthesizers
address@hidden --speech-friendly
address@hidden -b
+On MS-DOS/MS-Windows only, this option causes Info to use standard file
+I/O functions for screen writes. (By default, Info uses direct writes
+to the video memory on these systems, for faster operation and colored
+display support.) This allows the speech synthesizers used by blind
+persons to catch the output and convert it to audible speech.
+
address@hidden --subnodes
address@hidden @code{--subnodes}, command line option
+This option only has meaning when given in conjunction with
address@hidden It means to recursively output the nodes appearing in
+the menus of each node being output. Menu items which resolve to
+external Info files are not output, and neither are menu items which are
+members of an index. Each node is only output once.
+
address@hidden --version
address@hidden version information
+Prints the version information of Info and exits.
+
address@hidden
address@hidden vi-like key bindings
address@hidden Less-like key bindings
address@hidden --vi-keys
+This option binds functions to keys differently, to emulate the key
+bindings of @code{vi} and Less. The default key bindings are generally
+modeled after Emacs.
+(@xref{Custom Key Bindings},
+for a more general way of altering GNU Info's key bindings.)
+
address@hidden @var{menu-item}
address@hidden menu, following
address@hidden menu items}
+Info treats its remaining arguments as the names of menu items. The
+first argument is a menu item in the initial node visited (generally
address@hidden), the second argument is a menu item in the first argument's
+node, etc. You can easily move to the node of your choice by specifying
+the menu names which describe the path to that node. For example,
+
address@hidden
+info emacs buffers
address@hidden example
+
address@hidden
+first selects the menu item @samp{Emacs} in the node @samp{(dir)Top},
+and then selects the menu item @samp{Buffers} in the node
address@hidden(emacs)Top}.
address@hidden table
+
+To avoid searching the @file{dir} files and just show some arbitrary
+file, use @samp{-f} and the filename, as in @samp{info -f ./foo.info}.
+
+The index search and the search for the node which describes program
+invocation and command-line options begins @emph{after} processing all
+the command-line menu items. Therefore, the Info file searched for the
+index or the invocation node is the file where Info finds itself after
+following all the menu items given on the command line. This is so
address@hidden emacs --show-options} does what you'd expect.
+
address@hidden FIXME: the feature with lowercasing the file name isn't
documented
+
+
address@hidden Cursor Commands
address@hidden Moving the Cursor
address@hidden cursor, moving
address@hidden moving the cursor
+
+Many people find that reading screens of text page by page is made
+easier when one is able to indicate particular pieces of text with some
+kind of pointing device. Since this is the case, GNU Info (both the
+Emacs and standalone versions) have several commands which allow you to
+move the cursor about the screen. The notation used in this manual to
+describe keystrokes is identical to the notation used within the Emacs
+manual, and the GNU Readline manual. @xref{Characters, , Character
+Conventions, emacs, the GNU Emacs Manual}, if you are unfamiliar with the
address@hidden
+Here's a short summary. @address@hidden means press the @kbd{CTRL} key
+and the key @var{x}. @address@hidden means press the @kbd{META} key and
+the key @var{x}. On many terminals th @kbd{META} key is known as the
address@hidden key. @kbd{SPC} is the space bar. The other keys are usually
+called by the names imprinted on them.}.
+
+The following table lists the basic cursor movement commands in Info.
+Each entry consists of the key sequence you should type to execute the
+cursor movement, the @address@hidden@code{M-x} is also a command; it
+invokes @code{execute-extended-command}. @xref{M-x, , Executing an
+extended command, emacs, the GNU Emacs Manual}, for more detailed
+information.} command name (displayed in parentheses), and a short
+description of what the command does. All of the cursor motion commands
+can take a @dfn{numeric} argument (see @ref{Miscellaneous Commands,
address@hidden, to find out how to supply them}. With a
+numeric argument, the motion commands are simply executed that
+many times; for example, a numeric argument of 4 given to
address@hidden causes the cursor to move down 4 lines. With a
+negative numeric argument, the motion is reversed; an argument of -4
+given to the @code{next-line} command would cause the cursor to move
address@hidden 4 lines.
+
address@hidden @asis
address@hidden @key{C-n} (@code{next-line})
address@hidden @key{DOWN} (an arrow key)
address@hidden C-n
address@hidden DOWN (an arrow key)
address@hidden next-line
+Move the cursor down to the next line.
+
address@hidden @key{C-p} (@code{prev-line})
address@hidden @key{UP} (an arrow key)
address@hidden C-p
address@hidden UP (an arrow key)
address@hidden prev-line
+Move the cursor up to the previous line.
+
address@hidden @key{C-a} (@code{beginning-of-line})
address@hidden @key{Home} (on DOS/Windows only)
address@hidden C-a, in Info windows
address@hidden Home
address@hidden beginning-of-line
+Move the cursor to the start of the current line.
+
address@hidden @key{C-e} (@code{end-of-line})
address@hidden @key{End} (on DOS/Windows only)
address@hidden C-e, in Info windows
address@hidden End
address@hidden end-of-line
+Move the cursor to the end of the current line.
+
address@hidden @key{C-f} (@code{forward-char})
address@hidden @key{RIGHT} (an arrow key)
address@hidden C-f, in Info windows
address@hidden RIGHT (an arrow key)
address@hidden forward-char
+Move the cursor forward a character.
+
address@hidden @key{C-b} (@code{backward-char})
address@hidden @key{LEFT} (an arrow key)
address@hidden C-b, in Info windows
address@hidden LEFT (an arrow key)
address@hidden backward-char
+Move the cursor backward a character.
+
address@hidden @key{M-f} (@code{forward-word})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden M-f, in Info windows
address@hidden C-RIGHT
address@hidden forward-word
+Move the cursor forward a word.
+
address@hidden @key{M-b} (@code{backward-word})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden M-b, in Info windows
address@hidden C-LEFT
address@hidden backward-word
+Move the cursor backward a word.
+
address@hidden @key{M-<} (@code{beginning-of-node})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden @key{b}
address@hidden @key{M-b}, vi-like operation
address@hidden b, in Info windows
address@hidden M-<
address@hidden C-Home
address@hidden M-b, vi-like operation
address@hidden beginning-of-node
+Move the cursor to the start of the current node.
+
address@hidden @key{M->} (@code{end-of-node})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden @key{e}
address@hidden M->
address@hidden e, in Info windows
address@hidden C-End
address@hidden end-of-node
+Move the cursor to the end of the current node.
+
address@hidden @key{M-r} (@code{move-to-window-line})
address@hidden M-r
address@hidden move-to-window-line
+Move the cursor to a specific line of the window. Without a numeric
+argument, @code{M-r} moves the cursor to the start of the line in the
+center of the window. With a numeric argument of @var{n}, @code{M-r}
+moves the cursor to the start of the @var{n}th line in the window.
address@hidden table
+
+
address@hidden Scrolling Commands
address@hidden Moving Text Within a Window
address@hidden scrolling
+
+Sometimes you are looking at a screenful of text, and only part of the
+current paragraph you are reading is visible on the screen. The
+commands detailed in this section are used to shift which part of the
+current node is visible on the screen.
+
+Scrolling commands are bound differently when @samp{--vi-keys} operation
+(@pxref{--vi-keys}) is in effect. These key bindings are designated
+with ``vi-like operation''.
+
address@hidden @asis
address@hidden @key{SPC} (@code{scroll-forward})
address@hidden SPC, in Info windows
address@hidden scroll-forward
+Shift the text in this window up. That is, show more of the node which
+is currently below the bottom of the window. With a numeric argument,
+show that many more lines at the bottom of the window; a numeric
+argument of 4 would shift all of the text in the window up 4 lines
+(discarding the top 4 lines), and show you four new lines at the bottom
+of the window. Without a numeric argument, @key{SPC} takes the bottom
+two lines of the window and places them at the top of the window,
+redisplaying almost a completely new screenful of lines. If you are at
+the end of a node, @key{SPC} takes you to the ``next'' node, so that you can
+read an entire manual from start to finish by repeating @key{SPC}.
+
+The default scroll size is one screen-full, but it can be changed by
+invoking the (@code{scroll-forward-page-only-set-window}) command,
address@hidden under @samp{--vi-keys}, with a numeric argument.
+
address@hidden @key{NEXT} (an arrow key) (@code{scroll-forward-page-only})
address@hidden @key{C-v}
address@hidden @key{C-f}, vi-like operation
address@hidden @key{f}, vi-like operation
address@hidden @key{M-SPC}, vi-like operation
address@hidden NEXT
address@hidden C-v
address@hidden C-f, vi-like operation
address@hidden f, vi-like operation
address@hidden M-SPC, vi-like operation
address@hidden scroll-forward-page-only
+Shift the text in this window up. This is identical to the @key{SPC}
+operation above, except that it never scrolls beyond the end of the
+current node.
+
address@hidden PageDown
+The @key{NEXT} key is known as the @key{PageDown} key on some
+keyboards.
+
address@hidden @key{z} (@code{scroll-forward-page-only-set-window}, vi-like
operation)
address@hidden z, vi-like operation
address@hidden scroll-forward-page-only-set-window
+Scroll forward, like with @key{NEXT}, but if a numeric argument is
+specified, it becomes the default scroll size for subsequent
address@hidden and @code{scroll-backward} commands and their
+ilk.
+
address@hidden @key{DEL} (@code{scroll-backward})
address@hidden DEL, in Info windows
address@hidden scroll-backward
+Shift the text in this window down. The inverse of
address@hidden
+If you are at the start of a node, @key{DEL} takes you to the
+``previous'' node, so that you can read an entire manual from finish to
+start by repeating @key{DEL}. The default scroll size can be changed by
+invoking the (@code{scroll-backward-page-only-set-window}) command,
address@hidden under @samp{--vi-keys}, with a numeric argument.
+
address@hidden @key{PREVIOUS} (arrow key) (@code{scroll-backward-page-only})
address@hidden @key{PRIOR} (arrow key)
address@hidden @key{M-v}
address@hidden @key{b}, vi-like operation
address@hidden @key{C-b}, vi-like operation
address@hidden PREVIOUS
address@hidden M-v
address@hidden b, vi-like operation
address@hidden C-b, vi-like operation
address@hidden scroll-backward-page-only
+Shift the text in this window down. The inverse of
address@hidden Does not scroll beyond the start of
+the current node. The default scroll size can be changed by invoking
+the(@code{scroll-backward-page-only-set-window}) command, @samp{w} under
address@hidden, with a numeric argument.
+
address@hidden @key{w} (@code{scroll-backward-page-only-set-window}, vi-like
operation)
address@hidden w, vi-like operation
address@hidden scroll-backward-page-only-set-window
+Scroll backward, like with @key{PREVIOUS}, but if a numeric argument is
+specified, it becomes the default scroll size for subsequent
address@hidden and @code{scroll-backward} commands.
+
address@hidden @key{C-n} (@code{down-line}, vi-like operation)
address@hidden @key{C-e}, vi-like operation
address@hidden @key{RET}, vi-like operation
address@hidden @key{LFD}, vi-like operation
address@hidden @key{DOWN}, vi-like operation
address@hidden C-n, vi-like operation
address@hidden C-e, vi-like operation
address@hidden RET, vi-like operation
address@hidden LFD, vi-like operation
address@hidden DOWN, vi-like operation
address@hidden down-line
+Scroll forward by one line. With a numeric argument, scroll forward
+that many lines.
+
address@hidden @key{C-p} (@code{up-line}, vi-like operation)
address@hidden @key{UP}, vi-like operation
address@hidden @key{y}, vi-like operation
address@hidden @key{k}, vi-like operation
address@hidden @key{C-k}, vi-like operation
address@hidden @key{C-y}, vi-like operation
address@hidden C-p, vi-like operation
address@hidden UP, vi-like operation
address@hidden y, vi-like operation
address@hidden k, vi-like operation
address@hidden C-k, vi-like operation
address@hidden C-y, vi-like operation
address@hidden up-line
+Scroll backward one line. With a numeric argument, scroll backward that
+many lines.
+
address@hidden @key{d} (@code{scroll-half-screen-down}, vi-like operation)
address@hidden @key{C-d}, vi-like operation
address@hidden d, vi-like operation
address@hidden C-d, vi-like operation
address@hidden scroll-half-screen-down
+Scroll forward by half of the screen size. With a numeric argument,
+scroll that many lines. If an argument is specified, it becomes the new
+default number of lines to scroll for subsequent @samp{d} and @samp{u}
+commands.
+
address@hidden @key{u} (@code{scroll-half-screen-up}, vi-like operation)
address@hidden @key{C-u}, vi-like operation
address@hidden u, vi-like operation
address@hidden C-u, vi-like operation
address@hidden scroll-half-screen-up
+Scroll back by half of the screen size. With a numeric argument,
+scroll that many lines. If an argument is specified, it becomes the new
+default number of lines to scroll for subsequent @samp{u} and @samp{d}
+commands.
address@hidden table
+
address@hidden scrolling through node structure
+The @code{scroll-forward} and @code{scroll-backward} commands can also
+move forward and backward through the node structure of the file. If
+you press @key{SPC} while viewing the end of a node, or @key{DEL} while
+viewing the beginning of a node, what happens is controlled by the
+variable @code{scroll-behavior}. @xref{Variables,
address@hidden, for more information.
+
+The @code{scroll-forward-page-only} and @code{scroll-backward-page-only}
+commands never scroll beyond the current node.
+
address@hidden PageUp
+The @key{PREVIOUS} key is the @key{PageUp} key on many keyboards. Emacs
+refers to it by the name @key{PRIOR}. When you use @key{PRIOR} or
address@hidden to scroll, Info never scrolls beyond the beginning of the
+current node.
+
address@hidden BS (backspace)
+If your keyboard lacks the @key{DEL} key, look for a key called
address@hidden, or @samp{BackSpace}, sometimes designated with an arrow which
+points to the left, which should perform the same function.
+
address@hidden @asis
address@hidden @key{C-l} (@code{redraw-display})
address@hidden C-l
address@hidden redraw-display
+Redraw the display from scratch, or shift the line containing the cursor
+to a specified location. With no numeric argument, @samp{C-l} clears
+the screen, and then redraws its entire contents. Given a numeric
+argument of @var{n}, the line containing the cursor is shifted so that
+it is on the @var{n}th line of the window.
+
address@hidden @kbd{C-x @key{w}} (@code{toggle-wrap})
address@hidden C-w
address@hidden toggle-wrap
+Toggles the state of line wrapping in the current window. Normally,
+lines which are longer than the screen width @dfn{wrap}, i.e., they are
+continued on the next line. Lines which wrap have a @samp{\} appearing
+in the rightmost column of the screen. You can cause such lines to be
+terminated at the rightmost column by changing the state of line
+wrapping in the window with @code{C-x w}. When a line which needs more
+space than one screen width to display is displayed, a @samp{$} appears
+in the rightmost column of the screen, and the remainder of the line is
+invisible. When long lines are truncated, the modeline displays the
address@hidden character near its left edge.
address@hidden table
+
+
address@hidden Node Commands
address@hidden Selecting a Node
address@hidden nodes, selection of
+
+This section details the numerous Info commands which select a new node
+to view in the current window.
+
+The most basic node commands are @samp{n}, @samp{p}, @samp{u}, and
address@hidden Note that the commands to select nodes are mapped differently
+when @samp{--vi-keys} is in effect; these keybindings are designated
+below as ``vi-like operation''.
+
+When you are viewing a node, the top line of the node contains some Info
address@hidden which describe where the next, previous, and up nodes
+are. Info uses this line to move about the node structure of the file
+when you use the following commands:
+
address@hidden @asis
address@hidden @key{n} (@code{next-node})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden @kbd{C-x @key{n}}, vi-like operation
address@hidden n
address@hidden C-NEXT
address@hidden C-x n, vi-like operation
address@hidden next-node
+Select the `Next' node.
+
address@hidden C-PgDn
+The @key{NEXT} key is known as the @key{PgDn} key on some
+keyboards.
+
address@hidden @key{p} (@code{prev-node})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden p
address@hidden C-PREVIOUS
address@hidden prev-node
+Select the `Prev' node.
+
address@hidden C-PgUp
+The @key{PREVIOUS} key is known as the @key{PgUp} key on some
+keyboards.
+
address@hidden @key{u} (@code{up-node})
address@hidden @address@hidden (an arrow key on DOS/Windows only)
address@hidden @kbd{C-x @key{u}}, vi-like operation
address@hidden u
address@hidden C-UP
address@hidden C-x u, vi-like operation
address@hidden up-node
+Select the `Up' node.
address@hidden table
+
+You can easily select a node that you have already viewed in this window
+by using the @samp{l} command -- this name stands for "last", and
+actually moves backwards through the history of visited nodes for this
+window. This is handy when you followed a reference to another node,
+possibly to read about a related issue, and would like then to resume
+reading at the same place where you started the excursion.
+
+Each node where you press @samp{l} is discarded from the history. Thus,
+by the time you get to the first node you visited in a window, the
+entire history of that window is discarded.
+
address@hidden @asis
address@hidden @key{l} (@code{history-node})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden @key{'}, vi-like operation
address@hidden l
address@hidden C-CENTER
address@hidden ', vi-like operation
address@hidden history-node
+Pop the most recently selected node in this window from the node
+history.
address@hidden table
+
+Two additional commands make it easy to select the most commonly
+selected nodes; they are @samp{t} and @samp{d}.
+
address@hidden @asis
address@hidden @key{t} (@code{top-node})
address@hidden @key{M-t}, vi-like operation
address@hidden t
address@hidden M-t, vi-like operation
address@hidden top-node
+Select the node @samp{Top} in the current Info file.
+
address@hidden @key{d} (@code{dir-node})
address@hidden @key{M-d}, vi-like operation
address@hidden d
address@hidden M-d, vi-like operation
address@hidden dir-node
+Select the directory node (i.e., the node @samp{(dir)}).
address@hidden table
+
+Here are some other commands which immediately result in the selection
+of a different node in the current window:
+
address@hidden @asis
address@hidden @key{<} (@code{first-node})
address@hidden @key{g}, vi-like operation
address@hidden <
address@hidden g, vi-like operation
address@hidden first-node
+Selects the first node which appears in this file. This node is most
+often @samp{Top}, but it does not have to be. With a numeric argument
address@hidden, select the @var{N}th node (the first node is node 1). An
+argument of zero is the same as the argument of 1.
+
address@hidden @key{>} (@code{last-node})
address@hidden @key{G}, vi-like operation
address@hidden >
address@hidden G, vi-like operation
address@hidden last-node
+Select the last node which appears in this file. With a numeric argument
address@hidden, select the @var{N}th node (the first node is node 1). An
+argument of zero is the same as no argument, i.e., it selects the last
+node.
+
address@hidden @key{]} (@code{global-next-node})
address@hidden ]
address@hidden global-next-node
+Move forward or down through node structure. If the node that you are
+currently viewing has a @samp{Next} pointer, that node is selected.
+Otherwise, if this node has a menu, the first menu item is selected. If
+there is no @samp{Next} and no menu, the same process is tried with the
address@hidden node of this node.
+
address@hidden @key{[} (@code{global-prev-node})
address@hidden [
address@hidden global-prev-node
+Move backward or up through node structure. If the node that you are
+currently viewing has a @samp{Prev} pointer, that node is selected.
+Otherwise, if the node has an @samp{Up} pointer, that node is selected,
+and if it has a menu, the last item in the menu is selected.
address@hidden table
+
+You can get the same behavior as @code{global-next-node} and
address@hidden while simply scrolling through the file with
address@hidden and @key{DEL}; @xref{Variables, @code{scroll-behavior}}, for
+more information.
+
address@hidden @asis
address@hidden
address@hidden @key{g} (@code{goto-node})
address@hidden @kbd{C-x @key{g}}, vi-like operation
address@hidden g
address@hidden C-x g, vi-like operation
address@hidden goto-node
+Read the name of a node and select it. While reading the node name,
+completion (@pxref{The Echo Area, completion}) is only done for the
+nodes which reside in one of the Info files that were loaded in the
+current Info session; if the desired node resides in some other file,
+you must type the node exactly as it appears in that Info file, and you
+must include the Info file of the other file. For example,
+
address@hidden
address@hidden(emacs)Buffers}
address@hidden example
+
+finds the node @samp{Buffers} in the Info file @file{emacs}.
+
address@hidden
address@hidden @key{O} (@code{goto-invocation}
address@hidden @key{I}
address@hidden O
address@hidden I
address@hidden goto-invocation
address@hidden finding the Invocation node
+Read the name of a program and look for a node in the current Info file
+which describes the invocation and the command-line options for that
+program. The default program name is derived from the name of the
+current Info file. This command does the same as the
address@hidden command-line option (@pxref{--show-options}), but
+it also allows to specify the program name; this is important for those
+manuals which describe several programs.
+
+If you need to find the Invocation node of a program that is documented
+in another Info file, you need to visit that file before invoking
address@hidden For example, if you are reading the Emacs manual and want to
+see the command-line options of the @code{makeinfo} program, type @kbd{g
+(texinfo) @key{RET}} and then @kbd{I makeinfo @key{RET}}. If you don't
+know what Info file documents the command, or if invoking @samp{I}
+doesn't display the right node, go to the @samp{(dir)} node (using the
address@hidden command) and invoke @samp{I} from there.
+
address@hidden @key{G} (@code{menu-sequence})
address@hidden G
address@hidden menu-sequence
address@hidden menu, following, from inside Info
+Read a sequence of menu entries and follow it. Info prompts for a
+sequence of menu items separated by commas. (Since commas are not
+allowed in a node name, they are a natural choice for a delimiter in a
+list of menu items.) Info then looks up the first item in the menu of
+the node @samp{(dir)} (if the @samp{(dir)} node cannot be found, Info
+uses @samp{Top}). If such an entry is found, Info goes to the node it
+points to and looks up the second item in the menu of that node, etc.
+In other words, you can specify a complete path which descends through
+the menu hierarchy of a particular Info file starting at the
address@hidden(dir)} node. This has the same effect as if you typed the menu
+item sequence on Info's command line, see @ref{command-line menu items,,
+Info command-line arguments processing}. For example,
+
address@hidden
+ @kbd{G Texinfo,Overview,Reporting Bugs @key{RET}}
address@hidden example
+
address@hidden
+displays the node @samp{Reporting Bugs} in the Texinfo manual. (You
+don't actually need to type the menu items in their full length, or in
+their exact letter-case. However, if you do type the menu items
+exactly, Info will find it faster.)
+
+If any of the menu items you type are not found, Info stops at the last
+entry it did find and reports an error.
+
address@hidden @kbd{C-x @key{k}} (@code{kill-node})
address@hidden C-x k
address@hidden kill-node
+Kill a node. The node name is prompted for in the echo area, with a
+default of the current node. @dfn{Killing} a node means that Info tries
+hard to forget about it, removing it from the list of history nodes kept
+for the window where that node is found. Another node is selected in
+the window which contained the killed node.
+
address@hidden @kbd{C-x C-f} (@code{view-file})
address@hidden C-x C-f
address@hidden view-file
+Read the name of a file and selects the entire file. The command
address@hidden
address@hidden C-f @var{filename}}
address@hidden example
+is equivalent to typing
address@hidden
address@hidden(@var{filename})*}
address@hidden example
+
address@hidden @kbd{C-x C-b} (@code{list-visited-nodes})
address@hidden C-x C-b
address@hidden list-visited-nodes
+Make a window containing a menu of all of the currently visited nodes.
+This window becomes the selected window, and you may use the standard
+Info commands within it.
+
address@hidden @kbd{C-x @key{b}} (@code{select-visited-node})
address@hidden C-x b
address@hidden select-visited-node
+Select a node which has been previously visited in a visible window.
+This is similar to @samp{C-x C-b} followed by @samp{m}, but no window is
+created.
address@hidden table
+
+
address@hidden Searching Commands
address@hidden Searching an Info File
address@hidden searching
+
+GNU Info allows you to search for a sequence of characters throughout an
+entire Info file, search through the indices of an Info file, or find
+areas within an Info file which discuss a particular topic.
+
address@hidden @asis
address@hidden @key{s} (@code{search})
address@hidden @key{/}
address@hidden s
address@hidden /
address@hidden search
+Read a string in the echo area and search for it. If the string
+includes upper-case characters, the Info file is searched
+case-sensitively; otherwise Info ignores the letter case. With a
+numeric argument of @var{N}, search for @var{N}th occurrence of the
+string. Negative arguments search backwards.
+
address@hidden @key{?} (@code{search-backward}, vi-like operation)
address@hidden ?, vi-like operation
address@hidden search-backward
+Read a string in the echo area and search backward through the Info file
+for that string. If the string includes upper-case characters, the Info
+file is searched case-sensitively; otherwise Info ignores the letter
+case. With a numeric argument of @var{N}, search for @var{N}th
+occurrence of the string. Negative arguments search forward.
+
address@hidden @key{S} (@code{search-case-sensitively}
address@hidden S
address@hidden search-case-sensitively
address@hidden search, case-sensitive
address@hidden case-sensitive search
+Read a string in the echo area and search for it case-sensitively, even
+if the string includes only lower-case letters. With a numeric argument
+of @var{N}, search for @var{N}th occurrence of the string. Negative
+arguments search backwards.
+
address@hidden @kbd{C-x @key{n}} (@code{search-next})
address@hidden @key{n}, vi-like operation
address@hidden C-x n
address@hidden n, vi-like operation
address@hidden search-next
address@hidden repeated search
+Search for the same string used in the last search command, in the same
+direction, and with the same case-sensitivity option. With a numeric
+argument of @var{N}, search for @var{N}th next occurrence.
+
address@hidden @kbd{C-x @key{N}} (@code{search-previous})
address@hidden @key{N}, vi-like operation
address@hidden C-x N
address@hidden n, vi-like operation
address@hidden search-previous
+Search for the same string used in the last search command, and with the
+same case-sensitivity option, but in the reverse direction. With a
+numeric argument of @var{N}, search for @var{N}th previous occurrence.
+
address@hidden @key{C-s} (@code{isearch-forward})
address@hidden C-s
address@hidden isearch-forward
address@hidden incremental search
+Interactively search forward through the Info file for a string as you
+type it. If the string includes upper-case characters, the search is
+case-sensitive; otherwise Info ignores the letter case.
+
address@hidden @key{C-r} (@code{isearch-backward})
address@hidden C-r
address@hidden isearch-backward
+Interactively search backward through the Info file for a string as
+you type it. If the string includes upper-case characters, the search
+is case-sensitive; otherwise Info ignores the letter case.
+
address@hidden @key{i} (@code{index-search})
address@hidden i
address@hidden index-search
address@hidden index, searching
address@hidden searching, in the indices
+Look up a string in the indices for this Info file, and select a node
+where the found index entry points to.
+
address@hidden @key{,} (@code{next-index-match})
address@hidden ,
address@hidden next-index-match
+Move to the node containing the next matching index item from the last
address@hidden command.
+
address@hidden @kbd{M-x index-apropos}
address@hidden index-apropos
+Grovel the indices of all the known Info files on your system for a
+string, and build a menu of the possible matches.
address@hidden table
+
+The most basic searching command is @samp{s} or @samp{/}
+(@code{search}). The @samp{s} command prompts you for a string in the
+echo area, and then searches the remainder of the Info file for an
+occurrence of that string. If the string is found, the node containing
+it is selected, and the cursor is left positioned at the start of the
+found string. Subsequent @samp{s} commands show you the default search
+string within @samp{[} and @samp{]}; pressing @key{RET} instead of
+typing a new string will use the default search string. Under
address@hidden (@pxref{--vi-keys}), using the @samp{n} or @samp{N}
+commands is a faster way of searching for the same string.
+
address@hidden searching} is similar to basic searching, but the
+string is looked up while you are typing it, instead of waiting until
+the entire search string has been specified.
+
address@hidden search, and case-sensitivity
address@hidden case-sensitivity, and search
+Both incremental and non-incremental search by default ignore the case
+of letters when comparing the Info file text with the search string.
+However, an uppercase letter in the search string makes the search
+case-sensitive. You can force a case-sensitive non-incremental search,
+even for a string that includes only lower-case letters, by using the
address@hidden command (@code{search-case-sensitively}). The @samp{n} and
address@hidden commands operate case-sensitively if the last search command
+was @samp{S}.
+
+The most efficient means of finding something quickly in a manual is
+the @samp{i} command (@code{index-search}). This command prompts for
+a string, and then looks for that string in all the indices of the
+current Info manual. If it finds a matching index entry, it displays
+the node to which that entry refers and prints the full text of the
+entry in the echo area. You can press @samp{,}
+(@code{next-index-match}) to find more matches. A good Info manual
+has all of its important concepts indexed, so the @samp{i} command
+lets you use a manual as a reference.
+
+If you don't know what manual documents something, try the @kbd{M-x
+index-apropos}. It prompts for a string and then looks up that string
+in all the indices of all the Info documents installed on your system.
+It can also be invoked from the command line; see @ref{--apropos}.
+
+
address@hidden Xref Commands
address@hidden Selecting Cross References
+
+We have already discussed the @samp{Next}, @samp{Prev}, and @samp{Up}
+pointers which appear at the top of a node. In addition to these
+pointers, a node may contain other pointers which refer you to a
+different node, perhaps in another Info file. Such pointers are called
address@hidden references}, or @dfn{xrefs} for short.
+
address@hidden
+* Parts of an Xref:: What a cross reference is made of.
+* Selecting Xrefs:: Commands for selecting menu or note items.
address@hidden menu
+
address@hidden Parts of an Xref, Selecting Xrefs, , Xref Commands
address@hidden Parts of an Xref
+
+Cross references have two major parts: the first part is called the
address@hidden; it is the name that you can use to refer to the cross
+reference, and the second is the @dfn{target}; it is the full name of
+the node that the cross reference points to.
+
+The target is separated from the label by a colon @samp{:}; first the
+label appears, and then the target. For example, in the sample menu
+cross reference below, the single colon separates the label from the
+target.
+
address@hidden
+* Foo Label: Foo Target. More information about Foo.
address@hidden example
+
+Note the @samp{.} which ends the name of the target. The @samp{.} is
+not part of the target; it serves only to let Info know where the target
+name ends.
+
+A shorthand way of specifying references allows two adjacent colons to
+stand for a target name which is the same as the label name:
+
address@hidden
+* Foo Commands:: Commands pertaining to Foo.
address@hidden example
+
+In the above example, the name of the target is the same as the name of
+the label, in this case @code{Foo Commands}.
+
+You will normally see two types of cross reference while viewing nodes:
address@hidden references, and @dfn{note} references. Menu references
+appear within a node's menu; they begin with a @samp{*} at the beginning
+of a line, and continue with a label, a target, and a comment which
+describes what the contents of the node pointed to contains.
+
+Note references appear within the body of the node text; they begin with
address@hidden, and continue with a label and a target.
+
+Like @samp{Next}, @samp{Prev}, and @samp{Up} pointers, cross references
+can point to any valid node. They are used to refer you to a place
+where more detailed information can be found on a particular subject.
+Here is a cross reference which points to a node within the Texinfo
+documentation: @xref{xref, , Writing an Xref, texinfo, the Texinfo
+Manual}, for more information on creating your own texinfo cross
+references.
+
address@hidden Selecting Xrefs, , Parts of an Xref, Xref Commands
address@hidden Selecting Xrefs
+
+The following table lists the Info commands which operate on menu items.
+
address@hidden @asis
address@hidden @key{1} (@code{menu-digit})
address@hidden @key{2} @dots{} @key{9}
address@hidden @key{M-1}, vi-like operation
address@hidden @key{M-2} @dots{} @key{M-9}, vi-like operation
address@hidden 1 @dots{} 9, in Info windows
address@hidden M-1 @dots{} M-9, vi-like operation
address@hidden 1 @dots{} 9, in Info windows
address@hidden M-1 @dots{} M-9, vi-like operation
address@hidden menu-digit
+Within an Info window, pressing a single digit, (such as @samp{1}),
+selects that menu item, and places its node in the current window.
+For convenience, there is one exception; pressing @samp{0} selects the
address@hidden item in the node's menu. When @samp{--vi-keys} is in
+effect, digits set the numeric argument, so these commands are remapped
+to their @samp{M-} varieties. For example, to select the last menu
+item, press @key{M-0}.
+
address@hidden @key{0} (@code{last-menu-item})
address@hidden @key{M-0}, vi-like operation
address@hidden 0, in Info windows
address@hidden M-0, vi-like operation
address@hidden last-menu-item
+Select the last item in the current node's menu.
+
address@hidden @key{m} (@code{menu-item})
address@hidden m
address@hidden menu-item
+Reads the name of a menu item in the echo area and selects its node.
+Completion is available while reading the menu label. @xref{The Echo
+Area, completion}.
+
address@hidden @kbd{M-x find-menu}
address@hidden find-menu
+Move the cursor to the start of this node's menu.
address@hidden table
+
+This table lists the Info commands which operate on cross references.
+
address@hidden @asis
address@hidden @key{f} (@code{xref-item})
address@hidden @key{r}
address@hidden @key{M-f}, vi-like operation
address@hidden @kbd{C-x @key{r}}, vi-like operation
address@hidden f
address@hidden r
address@hidden M-f, vi-like operation
address@hidden C-x r, vi-like operation
address@hidden xref-item
+Reads the name of a note cross reference in the echo area and selects
+its node. Completion is available while reading the cross reference
+label. @xref{The Echo Area, completion}.
address@hidden table
+
+Finally, the next few commands operate on menu or note references alike:
+
address@hidden @asis
address@hidden @key{TAB} (@code{move-to-next-xref})
address@hidden TAB, in Info windows
address@hidden move-to-next-xref
+Move the cursor to the start of the next nearest menu item or note
+reference in this node. You can then use @key{RET}
+(@code{select-reference-this-line}) to select the menu or note reference.
+
address@hidden @key{M-TAB} (@code{move-to-prev-xref})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden M-TAB, in Info windows
address@hidden move-to-prev-xref
+Move the cursor the start of the nearest previous menu item or note
+reference in this node.
+
address@hidden Shift-TAB, in Info windows
address@hidden BackTab, in Info windows
+On DOS/Windows only, the @address@hidden key is an alias for
address@hidden@key{TAB}}. This key is sometimes called @samp{BackTab}.
+
address@hidden @key{RET} (@code{select-reference-this-line})
address@hidden @key{M-g}, vi-like operation
address@hidden RET, in Info windows
address@hidden M-g, vi-like operation
address@hidden select-reference-this-line
+Select the menu item or note reference appearing on this line.
address@hidden table
+
+
address@hidden Window Commands
address@hidden Manipulating Multiple Windows
address@hidden windows, manipulating
+
+A @dfn{window} is a place to show the text of a node. Windows have a
+view area where the text of the node is displayed, and an associated
address@hidden line}, which briefly describes the node being viewed.
+
+GNU Info supports multiple windows appearing in a single screen; each
+window is separated from the next by its modeline. At any time, there
+is only one @dfn{active} window, that is, the window in which the cursor
+appears. There are commands available for creating windows, changing
+the size of windows, selecting which window is active, and for deleting
+windows.
+
address@hidden
+* The Mode Line:: What appears in the mode line?
+* Basic Windows:: Manipulating windows in Info.
+* The Echo Area:: Used for displaying errors and reading input.
address@hidden menu
+
address@hidden The Mode Line, Basic Windows, , Window Commands
address@hidden The Mode Line
+
+A @dfn{mode line} is a line of inverse video which appears at the bottom
+of an Info window. It describes the contents of the window just above
+it; this information includes the name of the file and node appearing in
+that window, the number of screen lines it takes to display the node,
+and the percentage of text that is above the top of the window. It can
+also tell you if the indirect tags table for this Info file needs to be
+updated, and whether or not the Info file was compressed when stored on
+disk.
+
+Here is a sample mode line for a window containing an uncompressed file
+named @file{dir}, showing the node @samp{Top}.
+
address@hidden
address@hidden
+-----Info: (dir)Top, 40 lines --Top-------------------------------------
+ ^^ ^ ^^^ ^^
+ (file)Node #lines where
address@hidden group
address@hidden example
+
+When a node comes from a file which is compressed on disk, this is
+indicated in the mode line with two small @samp{z}'s. In addition, if
+the Info file containing the node has been split into subfiles, the name
+of the subfile containing the node appears in the modeline as well:
+
address@hidden
+--zz-Info: (emacs)Top, 291 lines --Top-- Subfile: emacs-1.Z-------------
address@hidden example
+
+Truncation of long lines (as opposed to wrapping them to the next
+display line, @pxref{Scrolling Commands, toggle-wrap}) is indicated by a
address@hidden at the left edge of the mode line:
+
address@hidden
+--$--Info: (texinfo)Top, 480 lines --Top-- Subfile: texinfo-1-----------
address@hidden example
+
+When Info makes a node internally, such that there is no corresponding
+info file on disk, the name of the node is surrounded by asterisks
+(@samp{*}). The name itself tells you what the contents of the window
+are; the sample mode line below shows an internally constructed node
+showing possible completions:
+
address@hidden
+-----Info: *Completions*, 7 lines --All---------------------------------
address@hidden example
+
address@hidden Basic Windows, The Echo Area, The Mode Line, Window Commands
address@hidden Window Commands
+
+It can be convenient to view more than one node at a time. To allow
+this, Info can display more than one @dfn{window}. Each window has its
+own mode line (@pxref{The Mode Line}) and history of nodes viewed in that
+window (@pxref{Node Commands, , @code{history-node}}).
+
address@hidden @asis
address@hidden @kbd{C-x @key{o}} (@code{next-window})
address@hidden windows, selecting
address@hidden C-x o
address@hidden next-window
+Select the next window on the screen. Note that the echo area can only be
+selected if it is already in use, and you have left it temporarily.
+Normally, @samp{C-x o} simply moves the cursor into the next window on
+the screen, or if you are already within the last window, into the first
+window on the screen. Given a numeric argument, @samp{C-x o} moves over
+that many windows. A negative argument causes @samp{C-x o} to select
+the previous window on the screen.
+
address@hidden @kbd{M-x prev-window}
address@hidden prev-window
+Select the previous window on the screen. This is identical to
address@hidden o} with a negative argument.
+
address@hidden @kbd{C-x @key{2}} (@code{split-window})
address@hidden windows, creating
address@hidden C-x 2
address@hidden split-window
+Split the current window into two windows, both showing the same node.
+Each window is one half the size of the original window, and the cursor
+remains in the original window. The variable @code{automatic-tiling}
+can cause all of the windows on the screen to be resized for you
+automatically, please @pxref{Variables, , automatic-tiling} for more
+information.
+
address@hidden @kbd{C-x @key{0}} (@code{delete-window})
address@hidden windows, deleting
address@hidden C-x 0
address@hidden delete-window
+Delete the current window from the screen. If you have made too many
+windows and your screen appears cluttered, this is the way to get rid of
+some of them.
+
address@hidden @kbd{C-x @key{1}} (@code{keep-one-window})
address@hidden C-x 1
address@hidden keep-one-window
+Delete all of the windows excepting the current one.
+
address@hidden @kbd{ESC @key{C-v}} (@code{scroll-other-window})
address@hidden ESC C-v, in Info windows
address@hidden scroll-other-window
+Scroll the other window, in the same fashion that @samp{C-v} might
+scroll the current window. Given a negative argument, scroll the
+"other" window backward.
+
address@hidden @kbd{C-x @key{^}} (@code{grow-window})
address@hidden C-x ^
address@hidden grow-window
+Grow (or shrink) the current window. Given a numeric argument, grow
+the current window that many lines; with a negative numeric argument,
+shrink the window instead.
+
address@hidden @kbd{C-x @key{t}} (@code{tile-windows})
address@hidden tiling
address@hidden C-x t
address@hidden tile-windows
+Divide the available screen space among all of the visible windows.
+Each window is given an equal portion of the screen in which to display
+its contents. The variable @code{automatic-tiling} can cause
address@hidden to be called when a window is created or deleted.
address@hidden, , @code{automatic-tiling}}.
address@hidden table
+
address@hidden The Echo Area, , Basic Windows, Window Commands
address@hidden The Echo Area
address@hidden echo area
+
+The @dfn{echo area} is a one line window which appears at the bottom of
+the screen. It is used to display informative or error messages, and to
+read lines of input from you when that is necessary. Almost all of the
+commands available in the echo area are identical to their Emacs
+counterparts, so please refer to that documentation for greater depth of
+discussion on the concepts of editing a line of text. The following
+table briefly lists the commands that are available while input is being
+read in the echo area:
+
address@hidden @asis
address@hidden @key{C-f} (@code{echo-area-forward})
address@hidden @key{RIGHT} (an arrow key)
address@hidden @key{M-h}, vi-like operation
address@hidden C-f, in the echo area
address@hidden RIGHT, in the echo area
address@hidden M-h, in the echo area, vi-like operation
address@hidden echo-area-forward
+Move forward a character.
+
address@hidden @key{C-b} (@code{echo-area-backward})
address@hidden @key{LEFT} (an arrow key)
address@hidden @key{M-l}, vi-like operation
address@hidden LEFT, in the echo area
address@hidden C-b, in the echo area
address@hidden M-l, in the echo area, vi-like operation
address@hidden echo-area-backward
+Move backward a character.
+
address@hidden @key{C-a} (@code{echo-area-beg-of-line})
address@hidden @key{M-0}, vi-like operation
address@hidden C-a, in the echo area
address@hidden M-0, in the echo area, vi-like operation
address@hidden echo-area-beg-of-line
+Move to the start of the input line.
+
address@hidden @key{C-e} (@code{echo-area-end-of-line})
address@hidden @key{M-$}, vi-like operation
address@hidden C-e, in the echo area
address@hidden M-$, vi-like operation
address@hidden echo-area-end-of-line
+Move to the end of the input line.
+
address@hidden @key{M-f} (@code{echo-area-forward-word})
address@hidden @address@hidden (DOS/Windows only)
address@hidden @key{M-w}, vi-like operation
address@hidden M-f, in the echo area
address@hidden M-w, in the echo area, vi-like operation
address@hidden echo-area-forward-word
+Move forward a word.
+
address@hidden C-RIGHT, in the echo area
+On DOS/Windows, @address@hidden moves forward by words.
+
address@hidden @key{M-b} (@code{echo-area-backward-word})
address@hidden @address@hidden (DOS/Windows only)
address@hidden M-b, in the echo area
address@hidden echo-area-backward-word
+Move backward a word.
+
address@hidden C-LEFT, in the echo area
+On DOS/Windows, @address@hidden moves backward by words.
+
address@hidden @key{C-d} (@code{echo-area-delete})
address@hidden @key{M-x}, vi-like operation
address@hidden C-d, in the echo area
address@hidden M-x, in the echo area, vi-like operation
address@hidden echo-area-delete
+Delete the character under the cursor.
+
address@hidden @key{DEL} (@code{echo-area-rubout})
address@hidden DEL, in the echo area
address@hidden echo-area-rubout
+Delete the character behind the cursor.
+
+On some keyboards, this key is designated @key{BS}, for
address@hidden Those keyboards will usually bind @key{DEL} in the
+echo area to @code{echo-area-delete}.
+
address@hidden @key{C-g} (@code{echo-area-abort})
address@hidden @key{C-u}, vi-like operation
address@hidden C-g, in the echo area
address@hidden C-u, in the echo area, vi-like operation
address@hidden echo-area-abort
+Cancel or quit the current operation. If completion is being read, this
+command discards the text of the input line which does not match any
+completion. If the input line is empty, it aborts the calling function.
+
address@hidden @key{RET} (@code{echo-area-newline})
address@hidden RET, in the echo area
address@hidden echo-area-newline
+Accept (or forces completion of) the current input line.
+
address@hidden @key{C-q} (@code{echo-area-quoted-insert})
address@hidden @key{C-v}, vi-like operation
address@hidden C-q, in the echo area
address@hidden C-v, in the echo area, vi-like operation
address@hidden echo-area-quoted-insert
+Insert the next character verbatim. This is how you can insert control
+characters into a search string, for example, or the @samp{?} character
+when Info prompts with completion.
+
address@hidden @var{printing character} (@code{echo-area-insert})
address@hidden printing characters, in the echo area
address@hidden echo-area-insert
+Insert the character. Characters that have their 8th bit set, and not
+bound to @samp{M-} commands, are also inserted verbatim; this is useful
+for terminals which support Latin scripts.
+
address@hidden @key{M-TAB} (@code{echo-area-tab-insert})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden M-TAB, in the echo area
address@hidden Shift-TAB, in the echo area
address@hidden echo-area-tab-insert
+Insert a TAB character.
+
address@hidden Shift-TAB, in the echo area
address@hidden BackTab, in the echo area
+On DOS/Windows only, the @address@hidden key is an alias for
address@hidden@key{TAB}}. This key is sometimes called @samp{BackTab}.
+
address@hidden @key{C-t} (@code{echo-area-transpose-chars})
address@hidden C-t, in the echo area
address@hidden echo-area-transpose-chars
+Transpose the characters at the cursor.
address@hidden table
+
+The next group of commands deal with @dfn{killing}, and @dfn{yanking}
address@hidden
+Some people are used to calling these operations @dfn{cut} and
address@hidden, respectively.}. For an in depth discussion of killing and
+yanking, @pxref{Killing, , Killing and Deleting, emacs, the GNU Emacs
+Manual}
+
address@hidden @asis
address@hidden @key{M-d} (@code{echo-area-kill-word})
address@hidden @key{M-X}, vi-like operation
address@hidden M-d, in the echo area
address@hidden M-X, in the echo area, vi-like operation
address@hidden echo-area-kill-word
+Kill the word following the cursor.
+
address@hidden @key{M-DEL} (@code{echo-area-backward-kill-word})
address@hidden @address@hidden
address@hidden M-DEL, in the echo area
address@hidden echo-area-backward-kill-word
+Kill the word preceding the cursor.
+
address@hidden M-BS, in the echo area
+On some keyboards, the @code{Backspace} key is used instead of
address@hidden, so @address@hidden has the same effect as
address@hidden@key{DEL}}.
+
address@hidden @key{C-k} (@code{echo-area-kill-line})
address@hidden C-k, in the echo area
address@hidden echo-area-kill-line
+Kill the text from the cursor to the end of the line.
+
address@hidden @kbd{C-x @key{DEL}} (@code{echo-area-backward-kill-line})
address@hidden C-x DEL, in the echo area
address@hidden echo-area-backward-kill-line
+Kill the text from the cursor to the beginning of the line.
+
address@hidden @key{C-y} (@code{echo-area-yank})
address@hidden C-y, in the echo area
address@hidden echo-area-yank
+Yank back the contents of the last kill.
+
address@hidden @key{M-y} (@code{echo-area-yank-pop})
address@hidden M-y, in the echo area
address@hidden echo-area-yank-pop
+Yank back a previous kill, removing the last yanked text first.
address@hidden table
+
address@hidden completion
+Sometimes when reading input in the echo area, the command that needed
+input will only accept one of a list of several choices. The choices
+represent the @dfn{possible completions}, and you must respond with one
+of them. Since there are a limited number of responses you can make,
+Info allows you to abbreviate what you type, only typing as much of the
+response as is necessary to uniquely identify it. In addition, you can
+request Info to fill in as much of the response as is possible; this
+is called @dfn{completion}.
+
+The following commands are available when completing in the echo area:
+
address@hidden @asis
address@hidden @key{TAB} (@code{echo-area-complete})
address@hidden @key{SPC}
address@hidden TAB, in the echo area
address@hidden SPC, in the echo area
address@hidden echo-area-complete
+Insert as much of a completion as is possible.
+
address@hidden @key{?} (@code{echo-area-possible-completions})
address@hidden ?, in the echo area
address@hidden echo-area-possible-completions
+Display a window containing a list of the possible completions of what
+you have typed so far. For example, if the available choices are:
+
address@hidden
address@hidden
+bar
+foliate
+food
+forget
address@hidden group
address@hidden example
+
address@hidden
+and you have typed an @samp{f}, followed by @samp{?}, Info will pop up a
+window showing a node called @samp{*Completions*} which lists the
+possible completions like this:
+
address@hidden
address@hidden
+3 completions:
+foliate food
+forget
address@hidden group
address@hidden example
+
address@hidden
+i.e., all of the choices which begin with @samp{f}. Pressing @key{SPC}
+or @key{TAB} would result in @samp{fo} appearing in the echo area, since
+all of the choices which begin with @samp{f} continue with @samp{o}.
+Now, typing @samp{l} followed by @samp{TAB} results in @samp{foliate}
+appearing in the echo area, since that is the only choice which begins
+with @samp{fol}.
+
address@hidden @key{ESC C-v} (@code{echo-area-scroll-completions-window})
address@hidden ESC C-v, in the echo area
address@hidden echo-area-scroll-completions-window
+Scroll the completions window, if that is visible, or the "other"
+window if not.
address@hidden table
+
+
address@hidden Printing Nodes
address@hidden Printing Nodes
address@hidden printing
+
+In general, we recommend that you use @TeX{} to format the document and
+print sections of it, by running @code{tex} on the Texinfo source file.
+However, you may wish to print out the contents of a node as a quick
+reference document for later use, or if you don't have @TeX{} installed.
+Info provides you with a command for doing this.
+
address@hidden @asis
address@hidden @kbd{M-x print-node}
address@hidden print-node
address@hidden INFO_PRINT_COMMAND, environment variable
+Pipe the contents of the current node through the command in the
+environment variable @code{INFO_PRINT_COMMAND}. If the variable does not
+exist, the node is simply piped to @code{lpr} (on DOS/Windows, the
+default is to print the node to the local printer device, @file{PRN}).
+
address@hidden printing nodes to the local printer
address@hidden local printer device
+The value of @code{INFO_PRINT_COMMAND} may begin with the @samp{>}
+character, as in @samp{>/dev/printer}, in which case Info treats the
+rest as the name of a file or a device. Instead of piping to a command,
+Info opens the file, writes the node contents, and closes the file,
+under the assumption that text written to that file will be printed by
+the underlying OS.
address@hidden table
+
+
address@hidden Miscellaneous Commands
address@hidden Miscellaneous Commands
+
+GNU Info contains several commands which self-document GNU Info:
+
address@hidden @asis
address@hidden @kbd{M-x describe-command}
address@hidden functions, describing
address@hidden commands, describing
address@hidden describe-command
+Read the name of an Info command in the echo area and then display a
+brief description of what that command does.
+
address@hidden @kbd{M-x describe-key}
address@hidden keys, describing
address@hidden describe-key
+Read a key sequence in the echo area, and then display the name and
+documentation of the Info command that the key sequence invokes.
+
address@hidden @kbd{M-x describe-variable}
+Read the name of a variable in the echo area and then display a brief
+description of what the variable affects.
+
address@hidden @kbd{M-x where-is}
address@hidden where-is
+Read the name of an Info command in the echo area, and then display
+a key sequence which can be typed in order to invoke that command.
+
address@hidden @key{C-h} (@code{get-help-window})
address@hidden @key{?}
address@hidden @key{F1} (on DOS/Windows only)
address@hidden h, vi-like operation
address@hidden C-h
address@hidden ?, in Info windows
address@hidden F1
address@hidden h, vi-like operation
address@hidden get-help-window
+Create (or Move into) the window displaying @code{*Help*}, and place
+a node containing a quick reference card into it. This window displays
+the most concise information about GNU Info available.
+
address@hidden @key{h} (@code{get-info-help-node})
address@hidden @key{M-h}, vi-like operation
address@hidden h
address@hidden M-h, vi-like operation
address@hidden get-info-help-node
+Try hard to visit the node @code{(info)Help}. The Info file
address@hidden distributed with GNU Info contains this node. Of
+course, the file must first be processed with @code{makeinfo}, and then
+placed into the location of your Info directory.
address@hidden table
+
+Here are the commands for creating a numeric argument:
+
address@hidden @asis
address@hidden @key{C-u} (@code{universal-argument})
address@hidden numeric arguments
address@hidden C-u
address@hidden universal-argument
+Start (or multiply by 4) the current numeric argument. @samp{C-u} is
+a good way to give a small numeric argument to cursor movement or
+scrolling commands; @samp{C-u C-v} scrolls the screen 4 lines, while
address@hidden C-u C-n} moves the cursor down 16 lines. @samp{C-u} followed
+by digit keys sets the numeric argument to the number thus typed:
address@hidden 1 2 0} sets the argument to 120.
+
address@hidden @key{M-1} (@code{add-digit-to-numeric-arg})
address@hidden @key{1}, vi-like operation
address@hidden @key{M-2} @dots{} @key{M-9}
address@hidden @key{2} @dots{} @key{9}, vi-like operation
address@hidden @key{M-0}
address@hidden @key{0}, vi-like operation
address@hidden M-0 @dots{} M-9
address@hidden 0 @dots{} 9, vi-like operation
address@hidden add-digit-to-numeric-arg
+Add the digit value of the invoking key to the current numeric
+argument. Once Info is reading a numeric argument, you may just type
+the digits of the argument, without the Meta prefix. For example, you
+might give @samp{C-l} a numeric argument of 32 by typing:
+
address@hidden
address@hidden 3 2 C-l}
address@hidden example
+
address@hidden
+or
+
address@hidden
address@hidden 2 C-l}
address@hidden example
+
address@hidden @key{M--} (@code{add-digit-to-numeric-arg}
address@hidden @key{-}
address@hidden M--
address@hidden -
address@hidden negative arguments
address@hidden arguments, negative
address@hidden numeric arguments, negative
+To make a negative argument, type @kbd{-}. Typing @kbd{-} alone makes a
+negative argument with a value of -1. If you continue to type digit or
+Meta-digit keys after @kbd{-}, the result is a negative number produced
+by those digits.
+
address@hidden doesn't work when you type in the echo area, because you need to
+be able to insert the @samp{-} character itself; use @kbd{M--} instead,
+if you need to specify negative arguments in the echo area.
address@hidden table
+
address@hidden is used to abort the reading of a multi-character key
+sequence, to cancel lengthy operations (such as multi-file searches) and
+to cancel reading input in the echo area.
+
address@hidden @asis
address@hidden @key{C-g} (@code{abort-key})
address@hidden @key{C-u}, vi-like operation
address@hidden cancelling typeahead
address@hidden cancelling the current operation
address@hidden C-g, in Info windows
address@hidden C-u cancels typeahead, vi-like operation
address@hidden abort-key
+Cancel current operation.
address@hidden table
+
+The @samp{q} command of Info simply quits running Info. Under
address@hidden (@pxref{--vi-keys}), you can also exit with @samp{:q}
+or @samp{ZZ}.
+
address@hidden @asis
address@hidden @key{q} (@code{quit})
address@hidden @kbd{C-x C-c}
address@hidden @kbd{:q}, vi-like operation
address@hidden @kbd{ZZ}, vi-like operation
address@hidden quitting
address@hidden q
address@hidden C-x C-c
address@hidden ZZ, vi-like operation
address@hidden quit
+Exit GNU Info.
address@hidden table
+
+If the operating system tells GNU Info that the screen is 60 lines tall,
+and it is actually only 40 lines tall, here is a way to tell Info that
+the operating system is correct.
+
address@hidden @asis
address@hidden @kbd{M-x set-screen-height}
address@hidden set-screen-height
address@hidden screen, changing the height of
+Read a height value in the echo area and set the height of the
+displayed screen to that value.
address@hidden table
+
+On MS-DOS/MS-Windows, this command actually tries to change the
+dimensions of the visible screen to the value you type in the echo
+area.
+
+Finally, Info provides a convenient way to display footnotes which might
+be associated with the current node that you are viewing:
+
address@hidden @asis
address@hidden @key{ESC C-f} (@code{show-footnotes})
address@hidden ESC C-f
address@hidden show-footnotes
address@hidden footnotes, displaying
+Show the footnotes (if any) associated with the current node in another
+window. You can have Info automatically display the footnotes
+associated with a node when the node is selected by setting the variable
address@hidden @xref{Variables, , @code{automatic-footnotes}}.
address@hidden table
+
+
address@hidden Variables
address@hidden Manipulating Variables
+
+GNU Info contains several @dfn{variables} whose values are looked at by
+various Info commands. You can change the values of these variables,
+and thus change the behavior of Info to more closely match your
+environment and Info file reading manner.
+
+There are two ways to set the value of a variable: interactively, using
+the @code{set-variable} command described below, or in the @code{#var}
+section of the @code{.infokey} file. @xref{Custom Key Bindings}.
+
address@hidden @asis
address@hidden @kbd{M-x set-variable}
address@hidden variables, setting
address@hidden set-variable
+Read the name of a variable, and the value for it, in the echo area and
+then set the variable to that value. Completion is available when
+reading the variable name (@pxref{The Echo Area, completion}); often,
+completion is available when reading the value to give to the variable,
+but that depends on the variable itself. If a variable does @emph{not}
+supply multiple choices to complete over, it expects a numeric value.
+
address@hidden @kbd{M-x describe-variable}
address@hidden variables, describing
address@hidden describe-variable
+Read the name of a variable in the echo area and then display a brief
+description of what the variable affects.
address@hidden table
+
+Here is a list of the variables that you can set in Info.
+
address@hidden @code
address@hidden automatic-footnotes
address@hidden automatic-footnotes
+When set to @code{On}, footnotes appear and disappear automatically.
+This variable is @code{On} by default. When a node is selected, a
+window containing the footnotes which appear in that node is created,
+and the footnotes are displayed within the new window. The window that
+Info creates to contain the footnotes is called @samp{*Footnotes*}. If
+a node is selected which contains no footnotes, and a @samp{*Footnotes*}
+window is on the screen, the @samp{*Footnotes*} window is deleted.
+Footnote windows created in this fashion are not automatically tiled so
+that they can use as little of the display as is possible.
+
address@hidden automatic-tiling
address@hidden automatic-tiling
+When set to @code{On}, creating or deleting a window resizes other
+windows. This variable is @code{Off} by default. Normally, typing
address@hidden 2} divides the current window into two equal parts. When
address@hidden is set to @code{On}, all of the windows are
+resized automatically, keeping an equal number of lines visible in each
+window. There are exceptions to the automatic tiling; specifically, the
+windows @samp{*Completions*} and @samp{*Footnotes*} are @emph{not}
+resized through automatic tiling; they remain their original size.
+
address@hidden errors-ring-bell
address@hidden errors-ring-bell
+When set to @code{On}, errors cause the bell to ring. The default
+setting of this variable is @code{On}.
+
address@hidden gc-compressed-files
address@hidden gc-compressed-files
+When set to @code{On}, Info garbage collects files which had to be
+uncompressed. The default value of this variable is @code{Off}.
+Whenever a node is visited in Info, the Info file containing that node
+is read into core, and Info reads information about the tags and nodes
+contained in that file. Once the tags information is read by Info, it
+is never forgotten. However, the actual text of the nodes does not need
+to remain in core unless a particular Info window needs it. For
+non-compressed files, the text of the nodes does not remain in core when
+it is no longer in use. But de-compressing a file can be a time
+consuming operation, and so Info tries hard not to do it twice.
address@hidden tells Info it is okay to garbage collect the
+text of the nodes of a file which was compressed on disk.
+
address@hidden ISO-Latin
address@hidden ISO Latin characters
address@hidden ISO-Latin
+When set to @code{On}, Info accepts and displays ISO Latin characters.
+By default, Info assumes an ASCII character set. @code{ISO-Latin} tells
+Info that it is running in an environment where the European standard
+character set is in use, and allows you to input such characters to
+Info, as well as display them.
+
address@hidden scroll-behavior
address@hidden scroll-behavior
+Control what happens when forward scrolling is requested at the end of
+a node, or when backward scrolling is requested at the beginning of a
+node. The default value for this variable is @code{Continuous}. There
+are three possible values for this variable:
+
address@hidden @code
address@hidden Continuous
+Try to get the first item in this node's menu, or failing that, the
address@hidden node, or failing that, the @samp{Next} of the @samp{Up}.
+This behavior is identical to using the @samp{]}
+(@code{global-next-node}) and @samp{[} (@code{global-prev-node})
+commands.
+
address@hidden Next Only
+Only try to get the @samp{Next} node.
+
address@hidden Page Only
+Simply give up, changing nothing. If @code{scroll-behavior} is
address@hidden Only}, no scrolling command can change the node that is being
+viewed.
address@hidden table
+
address@hidden scroll-step
address@hidden scroll-step
+The number of lines to scroll when the cursor moves out of the window.
+Scrolling happens automatically if the cursor has moved out of the
+visible portion of the node text when it is time to display. Usually
+the scrolling is done so as to put the cursor on the center line of the
+current window. However, if the variable @code{scroll-step} has a
+nonzero value, Info attempts to scroll the node text by that many lines;
+if that is enough to bring the cursor back into the window, that is what
+is done. The default value of this variable is 0, thus placing the
+cursor (and the text it is attached to) in the center of the window.
+Setting this variable to 1 causes a kind of "smooth scrolling" which
+some people prefer.
+
address@hidden show-index-match
address@hidden show-index-match
+When set to @code{On}, the portion of the matched search string is
+highlighted in the message which explains where the matched search
+string was found. The default value of this variable is @code{On}.
+When Info displays the location where an index match was found,
+(@pxref{Searching Commands, , @code{next-index-match}}), the portion of the
+string that you had typed is highlighted by displaying it in the inverse
+case from its surrounding characters.
+
address@hidden visible-bell
address@hidden visible-bell
+When set to @code{On}, GNU Info attempts to flash the screen instead of
+ringing the bell. This variable is @code{Off} by default. Of course,
+Info can only flash the screen if the terminal allows it; in the case
+that the terminal does not allow it, the setting of this variable has no
+effect. However, you can make Info perform quietly by setting the
address@hidden variable to @code{Off}.
+
address@hidden table
+
+
address@hidden Custom Key Bindings
address@hidden Customizing Key Bindings and Variables
+
address@hidden default key bindings, overriding
address@hidden overriding default key bindings
address@hidden customizing key bindings
address@hidden key bindings, customizing
address@hidden infokey
address@hidden .info
address@hidden .infokey
address@hidden _info file (MS-DOS)
+
+For those whose editor/pager of choice is not Emacs and who are not
+entirely satisfied with the --vi-keys option (@pxref{--vi-keys}), GNU
+Info provides a way to define different key-to-command bindings and
+variable settings from the defaults described in this document.
+
+On startup, GNU Info looks for a configuration file in the invoker's
+HOME directory called @address@hidden to the limitations of
+DOS filesystems, the MS-DOS version of Info looks for a file
address@hidden instead. If the @env{HOME} variable is not defined, Info
+additionally looks in the current directory.}. If it is present, and
+appears to contain Info configuration data, and was created with the
+current version of the @code{infokey} command, then Info adopts the
+key bindings and variable settings contained therein.
+
+The @file{.info} file contains compact, non-textual data for reasons of
+efficiency and because its design was lifted wholesale from the GNU Less
+program, which also does it that way. It must be created by compiling a
+textual source file using the @code{infokey} command.
+
address@hidden
+* Invoking infokey::
+* infokey source format::
address@hidden menu
+
+
address@hidden Invoking infokey
address@hidden Invoking @command{infokey}
+
address@hidden invoking infokey
address@hidden infokey, invoking
address@hidden _infokey file (MS-DOS)
+
address@hidden compiles a source file
+(@file{$HOME/address@hidden file is named @file{_infokey} in
+the MS-DOS version, and is looked for in the current directory if
address@hidden is undefined.} by default) containing Info customizations
+into a binary format (@file{$HOME/.info} by default). GNU Info reads
+the binary file at startup to override the default key bindings and
+variable definitions. Synopsis:
+
address@hidden
+infokey address@hidden@dots{}] address@hidden
address@hidden example
+
+Besides the standard @option{--help} and @option{--version}, the only
+option is @option{--output @var{file}}. This tells @command{infokey} to
+write the binary data to @var{file} instead of @file{$HOME/.info}.
+
+
address@hidden infokey source format
address@hidden @command{infokey} source format
+
address@hidden infokey source format
address@hidden .infokey source format
address@hidden format of .infokey source
+
+The format of the source file read by @command{infokey} is most easily
+illustrated by example. For instance, here is a sample @file{.infokey}
+source file suitable for aficionados of @command{vi} or @command{less}:
+
address@hidden
+#info
+j next-line
+k prev-line
+l forward-char
+h backward-char
+\kd next-line
+\ku prev-line
+\kr forward-char
+\kl backward-char
+\ scroll-forward
+\kD scroll-forward-page-only
+b scroll-backward
+\kU scroll-backward-page-only
+g beginning-of-node
+\kh beginning-of-node
+G end-of-node
+\ke end-of-node
+\t select-reference-this-line
+- history-node
+n next-node
+p prev-node
+u up-node
+t top-node
+d dir-node
+#var
+scroll-step=1
address@hidden example
+
+The source file consists of one or more @dfn{sections}.
+Each section starts with a line that identifies the type of section.
+Possible sections are:
+
address@hidden @code
address@hidden #info
+Key bindings for Info windows.
+The start of this section is indicated by a line containing just
address@hidden by itself. If this is the first section in the source
+file, the @code{#info} line can be omitted. The rest of this section
+consists of lines of the form:
+
address@hidden
address@hidden whitespace @var{action} [ whitespace [ # comment ] ] newline
address@hidden example
+
+Whitespace is any sequence of one or more spaces and/or tabs. Comment
+is any sequence of any characters, excluding newline. @var{string} is
+the key sequence which invokes the action. @var{action} is the name of
+an Info command. The characters in @var{string} are interpreted
+literally or prefixed by a caret (@code{^}) to indicate a control
+character. A backslash followed by certain characters specifies input
+keystrokes as follows:
+
address@hidden @code
address@hidden \b
+Backspace
address@hidden \e
+Escape (ESC)
address@hidden \n
+Newline
address@hidden \r
+Return
address@hidden \t
+Tab
address@hidden \ku
+Up arrow
address@hidden \kd
+Down arrow
address@hidden \kl
+Left arrow
address@hidden \kr
+Right arrow
address@hidden \kU
+Page Up
address@hidden \kD
+Page Down
address@hidden \kh
+HOME
address@hidden \ke
+END
address@hidden \kx
+Delete (DEL)
address@hidden address@hidden
address@hidden where @var{x} is any character as described above.
address@hidden table
+
+Backslash followed by any other character indicates that character is to
+be taken literally. Characters which must be preceded by a backslash
+include caret, space, tab, and backslash itself.
+
address@hidden #echo-area
+Key bindings for the echo area.
+The start of this section is indicated by a line containing just
address@hidden by itself. The rest of this section has a syntax
+identical to that for the key definitions for the Info area, described
+above.
+
address@hidden #var
+Variable initializations.
+The start of this section is indicated by a line containing just
address@hidden by itself. Following this line is a list of variable
+assignments, one per line. Each line consists of a variable name
+(@xref{Variables},) followed by @code{=} followed by a value.
+There may be no white space between the variable name and the @code{=},
+and all characters following the @code{=}, including white space,
+are included in the value.
address@hidden table
+
+Blank lines and lines starting with @code{#} are ignored, except for
+the special section header lines.
+
+Key bindings defined in the @file{.info} file take precedence over GNU
+Info's default key bindings, whether or not @samp{--vi-keys} is used. A
+default key binding may be disabled by overriding it in the @file{.info}
+file with the action @code{invalid}. In addition, @emph{all} default
+key bindings can be disabled by adding this line @emph{anywhere} in the
+relevant section:
+
address@hidden
+#stop
address@hidden example
+
+This will cause GNU Info to ignore all the default key commands for that
+section.
+
+Beware: @code{#stop} can be dangerous. Since it disables all default
+key bindings, you must supply enough new key bindings to enable all
+necessary actions. Failure to bind any key to the @code{quit} command,
+for example, can lead to frustration.
+
+The order in which key bindings are defined in the @file{.info} file is
+not important, except that the command summary produced by the
address@hidden command only displays the @emph{first} key that
+is bound to each command.
+
+
address@hidden the following is incomplete
+
+
address@hidden Copying This Manual
address@hidden Copying This Manual
+
address@hidden
+* GNU Free Documentation License:: License for copying this manual.
address@hidden menu
+
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
+
address@hidden FDL, GNU Free Documentation License
address@hidden Version 1.1, March 2000
+
address@hidden
+Copyright @copyright{} 2000 Free Software Foundation, Inc.
+59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
address@hidden display
+
address@hidden 0
address@hidden
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+written document @dfn{free} in the sense of freedom: to assure everyone
+the effective freedom to copy and redistribute it, with or without
+modifying it, either commercially or noncommercially. Secondarily,
+this License preserves for the author and publisher a way to get
+credit for their work, while not being considered responsible for
+modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
address@hidden
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work that contains a
+notice placed by the copyright holder saying it can be distributed
+under the terms of this License. The ``Document'', below, refers to any
+such manual or work. Any member of the public is a licensee, and is
+addressed as ``you''.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (For example, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, whose contents can be viewed and edited directly and
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is
+not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
address@hidden without markup, Texinfo input format, address@hidden input
format,
address@hidden or @acronym{XML} using a publicly available
address@hidden, and standard-conforming simple @acronym{HTML} designed
+for human modification. Opaque formats include PostScript,
address@hidden, proprietary formats that can be read and edited only by
+proprietary word processors, @acronym{SGML} or @acronym{XML} for which
+the @acronym{DTD} and/or processing tools are not generally available,
+and the machine-generated @acronym{HTML} produced by some word
+processors for output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
address@hidden
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
address@hidden
+COPYING IN QUANTITY
+
+If you publish printed copies of the Document numbering more than 100,
+and the Document's license notice requires Cover Texts, you must enclose
+the copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols. If you use the latter
+option, you must take reasonably prudent steps, when you begin
+distribution of Opaque copies in quantity, to ensure that this
+Transparent copy will remain thus accessible at the stated location
+until at least one year after the last time you distribute an Opaque
+copy (directly or through your agents or retailers) of that edition to
+the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
address@hidden
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
address@hidden A
address@hidden
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
address@hidden
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has less than five).
+
address@hidden
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
address@hidden
+Preserve all the copyright notices of the Document.
+
address@hidden
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
address@hidden
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
address@hidden
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
address@hidden
+Include an unaltered copy of this License.
+
address@hidden
+Preserve the section entitled ``History'', and its title, and add to
+it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
address@hidden
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
address@hidden
+In any section entitled ``Acknowledgments'' or ``Dedications'',
+preserve the section's title, and preserve in the section all the
+substance and tone of each of the contributor acknowledgments
+and/or dedications given therein.
+
address@hidden
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
address@hidden
+Delete any section entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
address@hidden
+Do not retitle any existing section as ``Endorsements''
+or to conflict in title with any Invariant Section.
address@hidden enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
address@hidden
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections entitled ``History''
+in the various original documents, forming one section entitled
+``History''; likewise combine any sections entitled ``Acknowledgments'',
+and any sections entitled ``Dedications''. You must delete all sections
+entitled ``Endorsements.''
+
address@hidden
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
address@hidden
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, does not as a whole count as a Modified Version
+of the Document, provided no compilation copyright is claimed for the
+compilation. Such a compilation is called an ``aggregate'', and this
+License does not apply to the other self-contained works thus compiled
+with the Document, on account of their being thus compiled, if they
+are not themselves derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one quarter
+of the entire aggregate, the Document's Cover Texts may be placed on
+covers that surround only the Document within the aggregate.
+Otherwise they must appear on covers around the whole aggregate.
+
address@hidden
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License provided that you also include the
+original English version of this License. In case of a disagreement
+between the translation and the original English version of this
+License, the original English version will prevail.
+
address@hidden
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
address@hidden
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
address@hidden://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
address@hidden enumerate
+
address@hidden
address@hidden ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
address@hidden
address@hidden
+ Copyright (C) @var{year} @var{your name}.
+ 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 the Invariant Sections being @var{list their titles}, with the
+ Front-Cover Texts being @var{list}, and with the Back-Cover Texts being
@var{list}.
+ A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
address@hidden group
address@hidden smallexample
+
+If you have no Invariant Sections, write ``with no Invariant Sections''
+instead of saying which ones are invariant. If you have no
+Front-Cover Texts, write ``no Front-Cover Texts'' instead of
+``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
address@hidden Local Variables:
address@hidden ispell-local-pdict: "ispell-dict"
address@hidden End:
+
+
+
address@hidden Index
address@hidden Index
+
address@hidden cp
+
address@hidden
Index: res_all/texi_mini_ker/mini_ker.texi.first
===================================================================
RCS file: res_all/texi_mini_ker/mini_ker.texi.first
diff -N res_all/texi_mini_ker/mini_ker.texi.first
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ res_all/texi_mini_ker/mini_ker.texi.first 2 Aug 2009 13:11:02 -0000
1.1
@@ -0,0 +1,4300 @@
+\input texinfo @c -*-texinfo-*-
address@hidden mini_ker.info
address@hidden UPDATED 28 March 2002
address@hidden UPDATED-MONTH March 2002
address@hidden EDITION 4.2
address@hidden VERSION 4.2
+
address@hidden @set myversion @value{VERSION}
address@hidden myversion 102
+
address@hidden myurl
@url{http://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}
+
address@hidden Minik{}
+Miniker
address@hidden macro
+
address@hidden Miniker 102 manual
+
address@hidden fn vr
+
address@hidden Miscellaneous
address@hidden
+* Miniker: (mini_ker). The mini_ker modeling tool.
address@hidden direntry
+
+
+
+
address@hidden Top
address@hidden Miniker 102 manual
+
+
address@hidden @insertcopying
+
address@hidden Miniker 102 manual
+
address@hidden: The TEF Collaboration}
+
address@hidden
+
+
address@hidden
+* Introduction::
+* TEF overview::
+* A model with Miniker::
+* Advanced programming::
+* Dynamic system analysis::
+* Advanced use of Miniker with make::
+
+Indices
+
+* Concepts index::
+* Variables macros and functions index::
+
+Appendices
+
+* Installation::
+* Cmz directives reference::
+* Copying This Manual:: The GNU Free Documentation License.
address@hidden menu
+
address@hidden
+
address@hidden Introduction
address@hidden Introduction
+
address@hidden TEF
address@hidden cells
address@hidden transfers
address@hidden ZOOM
address@hidden mortran
+
+ Miniker is a modeling tool, built especially in order to implement
+models written following the @acronym{TEF,Transfer Evolution Formalism}
+formalism, a mathematical framework for system analysis and
+simulation. Miniker allows for timewise simulation, system analysis,
+adjoint computation, Kalman filtering and more.
+
+Miniker uses a fortran preprocessor, @command{mortran}, designed in the
+1970's, to ease model writing using dedicated specific languages.
+For example partial derivatives are
+symbolicaly determined by @command{mortran} macros in Miniker.
+For the selection of
+another compile-time features, another set of preprocessor directives,
+the @dfn{cmz directives}, are used. In most cases the user does not need to
+know anything about that preprocessing that occurs behind the scene,
+he simply writes down the equations of his model and he is done.
+
address@hidden All partial derivatives needed to solve the TEF system are
automatically
address@hidden determined during the pre-compilation stage.
address@hidden Once all models written down and initial conditions
address@hidden given using a pseudo-Fortran type of language, the model is
ready to run.
+
address@hidden The language developed to get automatic symbolic partial
derivatives
address@hidden uses the Fortran pre-compiler @command{mortran}, designed in the
1970's.
+
+A comprehensive description
+of the @acronym{TEF} formalism in available on
address@hidden://www.lmd.jussieu.fr/ZOOM/doc/tef-GB-partA5.pdf}).
+The Miniker software is a reduced version of
address@hidden://www.lmd.jussieu.fr@//zoom,@strong{ZOOM}},
+that can only handle a hundreds of variables, but is much easier to use.
+
address@hidden
+* Intended audience::
+* Reading guide::
+* Other Manuals and documentation::
address@hidden menu
+
address@hidden Intended audience
address@hidden Intended audience
+
+The reader should have notions in system dynamics.
address@hidden and understand the basis of the TEF.
+Moreover a minimal knowledge of programmation and fortran is
+required. What is required is a basic understanding of variable types,
+affectation and fortran expressions.
+
address@hidden Reading guide
address@hidden Reading guide
+
+The first chapter is a brief overview of the @acronym{TEF}.
+The following describes how to write, compile and run a model in Miniker
+in its basic and comprehensive syntax.
address@hidden Reading the sections of this chapter up to the section
address@hidden @emph{Symbolic model description} is required to know the
address@hidden syntax of model description in @Minik{}.
+Reading up to the section
address@hidden the run} is required to be able to use Miniker.
+In this section it is assumed that Miniker is properly setup. The
+installation instructions are in the appendix at
address@hidden
+
address@hidden 2 programming environment to compile the model are available,
with cmz
address@hidden and make, you can skip the method description you are not
interested in.
address@hidden A reference for the usefull cmz directives is also in the
appendix
address@hidden (@pxref{Cmz directives reference}).
+
address@hidden You should also
address@hidden read the following section, @emph{Symbolic model description}
which presents an
address@hidden alternate syntax for model description, such that you can choose
what you
address@hidden prefer.
+
+The next chapter describes advanced features, first a general introduction to
+features settings and then a description of other model description related
+features.
+
+The next chapter describes system analysis tools available with Miniker. The
+sections are independant and each describes how to use a specific feature. If
+you plan on using these features, you should also read
address@hidden features, , Overview of feature setting}.
+
+A final chapter describes advanced features in a development environment
+using make,
+
+In the appendix the instructions for the installation are described
+(@pxref{Installation}).
+
address@hidden Other Manuals and documentation
address@hidden Other Manuals and documentation
+
+A programmers'Manual is available (in French), and can be asked for to
+any member of the collabration. See additional documents in
+ @url{http://www.lmd.jussieu.fr/Zoom/doc} or ask for Research
+texts and articles to members.
+
address@hidden TEF overview
address@hidden An overview of the @acronym{TEF} formalism
+
+The @acronym{TEF, Transfer Evolution Formalism} is based on partitionning
+and recoupling of model subsystems. It allows the study of the coupling
+between subsystems by the means of linearization and time discretization.
+
address@hidden
+* Cell and Transfer::
+* Linearization and discretization::
address@hidden menu
+
address@hidden Cell and Transfer
address@hidden Cell and Transfer equations
+
+In the @acronym{TEF}, a model is
+mathematically represented by a set of equations corresponding
+to two kinds objects:
+
address@hidden
address@hidden Cells which are elementary models and correspond to evolution
equations
+such as:
address@hidden
+$$\partial_t \eta (t) = g(\eta(t),\varphi(t))$$
address@hidden tex
+
address@hidden @math{d eta(t)/d t = g(eta(t),phi(t))}
+
+
+Vector @math{\eta} represent the state variables of cells and
+the vector @math{\varphi} represent the dependent
+boundary conditions, @i{i.e.} the
+variables considered as boundary conditions by a cell, but depending upon
+the complete model state. This dependent boundary conditions are
+required to make the cells correspond to well-posed problems.
address@hidden FIXME acceptable?
+These variables are often called state variables, and prognostic
+variables in meteorology.
+
+
address@hidden Transfers which are determined by constraint equations such as:
address@hidden
+$$
+\varphi(t) = f(\eta(t),\varphi(t))
+$$
address@hidden tex
+
address@hidden @math{phi(t) = f(eta(t),phi(t))}
+
+These equations are often called algebraic equations, and in meteorology
+diagnostic equations.
address@hidden enumerate
+
address@hidden Linearization and discretization
address@hidden Linearization and discretization in the @acronym{TEF}
+
+The relations between sub-systems is excessively difficult to exhibit when
+having to cope with non-linear system. In the @acronym{TEF}, the
address@hidden, Tangent Linear System} is constructed along the trajectory.
+One considers the system over a small portion along the trajectory, say
+between @math{t} and @math{t + \delta t}. The variation @math{\delta \eta}
+of @math{\eta} and @math{\delta \varphi} of @math{\varphi} is obtained
+through a Pad@'e approximation of the state-transition matrix. The final
+form of the algebraic system is closed to the classical Crank-Nicolson scheme:
+
address@hidden FIXME PAd'e? od Taylor?
address@hidden through a Taylor expansion followed by time integration.
address@hidden A time scheme is then applied to the @acronym{TLS} (a
Crank-Nicholson scheme),
address@hidden to obtain an algebraic system describing the relationships
between
address@hidden variations of transfers and cells variables:
+
+
+
address@hidden
+$$\pmatrix{A & B\cr
+-C^+ & I-D\cr} \pmatrix{\delta \eta\cr
+\delta \varphi\cr} = \pmatrix{\Gamma\cr
+\Omega\cr}$$
address@hidden tex
+
+The blocks appearing in the Jacobian matrix are constructed with partial
derivative
+of @math{f} and @math{g}, and with @math{\delta t}. From this system the
+elimination of @math{\delta \eta} leads to another formulation giving
+the coupling between transfers, and allows for the @math{\delta \varphi}
+computation. The @math{\delta \varphi} value is then substitued in
address@hidden \eta} to complete the time-step solving process.
+
address@hidden A model with Miniker
address@hidden Miniker model programming
+
address@hidden sequences
+
+Miniker works by combining the model specification code given by
+the user and other source files provided in the package. The code is
+assembled, preprocessed, compiled, linked and the resulting program
+can be run to produce the model trajectory and dynamic analysis.
+
+The code provided in the package contains a principal program, some usefull
+subroutines and pieces of code called @dfn{sequences} combined with the
+different codes. Among these sequences some hold the code describing the model
+and are to be written by the user (sequences are similar to
+Fortran include files).
+
address@hidden
+* Structure of the code::
+* A model description::
+* Setting and running a model::
+* Controlling the run::
address@hidden menu
+
address@hidden Structure of the code
address@hidden General structure of the code
+
address@hidden sequence
address@hidden zinit, general
+
+The sequences used to enter model description hold the @c vector dimensions,
+mathematical formulae for each cell and transfer component, dedicated
+derived computations, and time-step
+steering. During the code generation stage,
+cmz directives are preprocessed, then the user pseudo-Fortran
+instructions are translated by @command{mortran} using macros designed to
+generate in particular all Fortran instructions that compute the Jacobian
+matrices used in @acronym{TEF} modelling.
+
address@hidden A first users' sequence to program is: @file{dimetaphi} where
the model
address@hidden dimensions are given, for the two vector-array @code{eta(.)} for
cells
address@hidden and @code{ff(.)} for transfers (@pxref{Model size,,Entering
model size}).
+
+The sequence @file{zinit} contains the mathematical formulation of the model
+(@pxref{Model equation and parameters, Entering model equation and
parameters}).
+Another sequence, @file{zsteer}, is merged at
+the end of the time step advance of the simulation, where the user can
+monitor the time step values and printing levels, and perform particular
+computations etc.
+(@pxref{End of time step, ,Executing code at the end of each time step}).
+
address@hidden A model description
address@hidden Miniker programming illustrated
+
address@hidden TEF
+
+The general @acronym{TEF} system writes:
address@hidden
+$$\eqalign{\partial_t \eta (t) &= g(\eta(t),\varphi(t))\cr
+\varphi(t) &= f(\eta(t),\varphi(t))\cr
+}$$
address@hidden tex
+
address@hidden @math{d eta(t)/d t = g(eta(t),phi(t))@*
+phi(t) = f(eta(t),phi(t))}
+
+
+To illustrate the model description in Miniker a simple predator-prey
+model of Lotka-Volterra is used.
+This model can be written in the following @acronym{TEF} form:
+
address@hidden
+$$\left\{\eqalign{\partial_t \eta _{prey} &= a \eta _{prey} - a \varphi
_{meet} \cr
+\partial_t \eta _{pred} &= -c \eta _{pred} + c \varphi _{meet}\cr}\right.$$
address@hidden tex
address@hidden
+$$\varphi _{meet} = \eta _{prey}\eta _{pred}$$
address@hidden tex
address@hidden @math{d eta_prey(t)/d t = a * eta_prey - a * address@hidden
+d eta_pred(t)/d t = -c * eta_pred +c * phi_meet}
+
address@hidden @math{phi_meet = eta_prey * eta_pred}
+
+with two cell equations, @i{i.e}. state evolution of the prey and predator
+groups, and one transfer accounting for the meeting of individuals of
+different group.
+
address@hidden
+* A note about mortran and cmz directives::
+* Model equation and parameters::
address@hidden menu
+
address@hidden A note about mortran and cmz directives
address@hidden All you need to know about mortran and cmz directives
+
address@hidden mortran
+
+The first stage of code generation consists in cmz directives preprocessing.
+Cmz directives are used for conditional selection of features, and sequence
+inclusion. At that point you don't need to know anything about these
+directives. They are only usefull if you want to take advantage of advanced
+features
+(@pxref{Programming with cmz directives}).
+
+The code in sequences is written in Mortran and the second stage of code
+generation consists in mortran macro expansion. The mortran language is
+described
+in its own manual, here we only explain the very basics which is all you need
+to know to use Miniker. Mortran basic instructions are almost Fortran,
+the differences are the following:
+
address@hidden @bullet
address@hidden The code is free-form, and each statement should end with a
semi-colon
address@hidden;}.
address@hidden Comments may be introduced by an exclamation mark @code{!} at
the
+beginning of a line, or appear within double quotes @code{"} in a single line.
address@hidden It is possible to use blocs, for @code{do} or @code{if}
statement
+for example, and they are enclosed within brackets @samp{<} and @samp{>}.
+To be in the safe side, a semi-colon @code{;} should be added after a
+closng bracket @code{>}.
address@hidden itemize
+
+The following fictious code is legal mortran:
+
address@hidden
+real
+ param;
+param = 3.; ff(1) = ff(3)**eta(1); "a comment"
+! a line comment
+do inode=1,n_node <eta_move(inode)=0.01; eta_speed(inode)=0.0;>;
address@hidden example
+
+Thanks to mortran the model code is very simply specified, as you'll
+see next.
+
+
address@hidden Model equation and parameters
address@hidden Entering model equation and parameters
+
address@hidden @file{zinit}
address@hidden dt
address@hidden time
address@hidden nstep
address@hidden modzprint
+
+The model equation and parameters and some Miniker parameters are entered in
+the @file{zinit} sequence. The whole layout of the model is given
+before detailing the keywords.
+
address@hidden
+!%%%%%%%%%%%%%%%%%%%%%%
+! Parameters
+!%%%%%%%%%%%%%%%%%%%%%%
+ real apar,bpar; "optional Fortran type declaration"
+
+! required parameters
+ dt=.01; "initial time-step"
+ nstep=10 000; "number of iterations along the trajectory"
+ time=0.; "time initialisation "
+
+! model parameters
+ apar = 1.5;
+ cpar = 0.7;
+
+! misceallaneous parameters
+ modzprint = 1000; "printouts frequency"
+
+print*,'***************************************';
+print*,'Lotka-Volterra model with parameters as:';
+z_pr: apar,bpar;
+print*,'***************************************';
+
+!%%%%%%%%%%%%%%%%%%%%%%
+! Transfer definition
+!%%%%%%%%%%%%%%%%%%%%%%
+! rencontre (meeting)
+set_Phi
+< var: ff_interact, fun: f_interact = eta_prey*eta_pred;
+>;
+
+!%%%%%%%%%%%%%%%%%%%%%%
+! Cell definition
+!%%%%%%%%%%%%%%%%%%%%%%
+
+set_eta
+< var: eta_prey, fun: deta_prey = apar*eta_prey - apar*ff_interact;
+ var: eta_pred, fun: deta_pred = - cpar*eta_pred + cpar*ff_interact;
+>;
+
+
+!%%%%%%%%%%%%%%%%%%%%%%
+! Initial states
+!%%%%%%%%%%%%%%%%%%%%%%
+ eta_prey = 1.;
+ eta_pred = 1.;
+;
+ OPEN(50,FILE='title.tex',STATUS='UNKNOWN'); "title file"
+ write(50,5000) apar,cpar;
+5000;format('Lotka-Volterra par:',2F4.1);
address@hidden example
+
address@hidden Variables and model parameters
+
+The following variables are mandatory:
+
address@hidden @code
address@hidden dt
+The time step.
address@hidden time
+Model time initialisation.
address@hidden nstep
+Number of iterations along the trajectory.
address@hidden table
+
+There are no other mandatory variables. Some optional variables are used
+to monitor the printout and ouput of results of the code.
+As an example, the variable @code{modzprint} is used to set
+the frequency of the printout of the model matrix and vectors during the
+run (@pxref{Controlling the printout and data output}).
+
+User's defined variable and Fortran or Mortran instructions can always be
+added for intermediate calculus. To avoid conflict with the variables of the
+Miniker code, the rule is that a users symbol must not have characters
address@hidden
+in the first two symbol characters.
+
+In the predator-prey example there are two model parameters. The fortran
+variables are called here @code{apar} for @math{a} and @code{cpar} for
@math{c}.
+If a Fortan type definition is needed, it should be set at the very beginning
+of @file{zinit}. The predator-prey code variable initializations finally reads
+
address@hidden
address@hidden
+!%%%%%%%%%%%%%%%%%%%%%%
+! Parameters
+!%%%%%%%%%%%%%%%%%%%%%%
+ real apar,bpar; "optional Fortran type declaration"
+
+ dt=.01;
+ nstep=10 000;
+ time=0.;
+
+! model parameters
+ apar = 1.5;
+ cpar = 0.7;
+
+ modzprint = 1000;
address@hidden group
address@hidden example
+
address@hidden Model equations
address@hidden equations}
+
address@hidden set_Phi
address@hidden set_eta
address@hidden var:
address@hidden fun:
address@hidden eqn:
+
+The model equations for cells and model equations for transferts are
+entered in two mortran blocks, one for the transferts, the other for the
+cell components. The model equations for cells are entered into a
address@hidden block, and the transfer equations are entered into a
address@hidden block.
+
+In each block the couples variable-function are specified. For
+transfers the function defines the transfer itself while for cells
+the function describes the cell evolution. The variable is specified
+with @code{var:}, the function is defined with @code{fun:}.
+
+In the case of the predator-prey model, the transfer variable
+associated with @math{\varphi_{meet}} could be called @code{ff_interact}
+and the transfer definition would be given by:
address@hidden
+set_Phi
+< var: ff_interact, fun: f_interact = eta_prey*eta_pred;
+>;
address@hidden example
+
+The two cell equations of the predator-prey model, with name
address@hidden for the prey (@math{\eta_{prey}}) and @code{eta_pred}
+for the predator (@math{\eta_{pred}}) are:
+
address@hidden
+set_eta
+< var: eta_prey, fun: deta_prey = apar*eta_prey - apar*ff_interact;
+ var: eta_pred, fun: deta_pred = - cpar*eta_pred + cpar*ff_interact;
+>;
address@hidden example
+
+The @samp{;} at the end of the mortran block is important.
+
address@hidden
+The whole model equations are setup with:
+
address@hidden
address@hidden
+!%%%%%%%%%%%%%%%%%%%%%%
+! Transfer definition
+!%%%%%%%%%%%%%%%%%%%%%%
+! rencontre (meeting)
+set_Phi
+< var: ff_interact, fun: f_interact = eta_prey*eta_pred;
+>;
+
+!%%%%%%%%%%%%%%%%%%%%%%
+! Cell definition
+!%%%%%%%%%%%%%%%%%%%%%%
+
+set_eta
+< var: eta_prey, fun: deta_prey = apar*eta_prey - apar*ff_interact;
+ var: eta_pred, fun: deta_pred = - cpar*eta_pred + cpar*ff_interact;
+>;
address@hidden group
address@hidden example
+
+Whenever the user is not concerned with giving a specific name to a
+function, it is possible to specify the equation only with
address@hidden:}. Therefore the user may replace an instruction as:
address@hidden
+ var: ff_dump,
+ fun: f_dump = - rd*(eta_speed - eta_speed_limiting);
address@hidden example
+with:
address@hidden
+ eqn: ff_dump = - rd*(eta_speed - eta_speed_limiting);
address@hidden example
+
+In that case, the unnamed function will take the name of the defined
+variable preceded by the @samp{$} sign: @code{$ff_dump}.
+
address@hidden Starting points
+
address@hidden starting point
+
+The cells equations require state initial conditions. In some case, the
+transfers may also need starting points although they are determined from
+the cell values.
+
+In the predator-prey model the starting points for cells are:
address@hidden
+! initial state
+! -------------
+ eta_prey = 1.;
+ eta_pred = 1.;
address@hidden example
+
+When there is a non trivial implicit relationship between the transfers
+in the model, it may be usefull or even necessary to set some
+transfers to non-zero values. This difficulty is only relevant for the very
+first step of the simulation and will be used as a
+first guess of @math{\varphi}. The uninitialized transfers having
+a default compiler-dependant (often zero) value, an initialization
+to another value may help avoiding singular functions or matrix and
+ensure convergence in the Newton algorithm used to solve the transfer implicit
+equation.
+
+
address@hidden The cell and transfer arrays
+
address@hidden eta(.)
address@hidden ff(.)
address@hidden mp
address@hidden np
+
+Sometime it is easier to iterate over an array than to use the
+cell or transfer variable name. This is possible because there is a
+correspondence between the variable names
+and the fortran array @code{eta(.)} for the cell variables and
+the fortran array @code{ff(.)} for the transfer address@hidden fact
+the variables names are transformed into fortran array elements
+by mortran generated macros, so the symbolic names defined in the
+mortran blocks never appears in the generated fortran code, they are
+replaced by the fortran arrays.}.
+
+The index of the variable is determined by the order of appearance in
+the variable definition blocks. It is reminded in the output, as
+explained later (@pxref{Simulation and output}).
+
+The number of cells is in the integer @code{np} variable, and the
+number of transfer is in the integer @code{mp} variable.
+
address@hidden title file
+
address@hidden file}
address@hidden title file
address@hidden @file{title.tex}
+
+For some graphics generation, a file with name @file{title.tex} is required
+which sets the title. The following instructions take care of that:
+
address@hidden
+ OPEN(50,FILE='title.tex',STATUS='UNKNOWN');
+ write(50,5000) apar,cpar;
+5000;format('Lotka-Volterra par:',2F4.1);
+
+ close(50);
address@hidden example
+
+In that case the parameter values are written down, to differenciate between
+different runs. This step is in general not needed.
+
address@hidden The correspondence with basic components are printed out at
execution
address@hidden time as explained in @ref{Simulation and output,,
address@hidden Running a simulation and using the output}. Also, a
@file{Model.hlp} is
address@hidden generated that recalls the basic names and equations of the
model.
address@hidden It may be noted that whenever
address@hidden the order of variable-functions is the same between indexed
declaration and
address@hidden symbolic, the two generated Fortran code are almost identical.
+
address@hidden Setting and running a model
address@hidden Setting and running a model
+
+In this section it is assumed that a programming environment has been
+properly setup. This environment may use either cmz or make to drive
+the preprocessing and compilation.
+You can skip the part related with the environment you don't intend to use.
+
+For instructions regarding the
+installation, see @ref{Installation}.
+
+
address@hidden
+* Setting up a model with cmz::
+* Setting up a model with make::
+* Simulation and output::
+* Graphics::
address@hidden menu
+
address@hidden Setting up a model with cmz
address@hidden Setup a model and compile with cmz
+
address@hidden @command{mod}
address@hidden @file{$zinit}
address@hidden @file{$dimetaphi}
+
+The user defined sequences are @samp{KEEP} in the
+cmz world. The most common organization is to have a cmz file in a
+subdirectory of the directory containing the @file{mini_ker.cmz}
+cmz file. In this
+cmz file there should be a @samp{PATCH} called @samp{zinproc}
+with the KEEPs within the patch. The KEEP must be called @file{$zinit}.
address@hidden and @file{$dimetaphi}.
+
+From within cmz in the directory of your model the source extraction,
+compilation and linking will be triggered by a @command{mod} command. This
macro
+uses the @file{selseq.kumac} information to find the @file{mini_ker.cmz}
+cmz file.
address@hidden
+shall create a directory with the same name than the cmz file,
address@hidden/} in our example. In this directory there is another
+directory @file{cfs/} containing the sources extracted from the cmz file.
+
+The file @file{mymodel_o.tmp} contains all the mortran code generated
+by cmz with the sequences substituted, including the @file{$zinit}. @c and
address@hidden @file{$dimetaphi} sequences (assembled code).
+The fortran produced by the preprocessing and
+splitting of this file is in files with the traditional @samp{.f} suffix.
+The principal program is in @file{principal.f}. An efficient way of getting
+familiar with mini_ker methods is looking at the @file{mymodel_o.tmp} where
+all sequences and main Mortran instructions are gathered. Symbolic derivation
address@hidden FIXME pas ici la symbolic derivation
+is noted as @code{F_D(expression)(/variable)}, and the resulting Fortran code
+is in @file{principal.f}.
+
address@hidden also triggers compilation and linking. The object files are in
+the same @file{cfs/} directory and the executable is in the @file{mymodel/}
+directory, with name @file{mymodel.exe}.
+
address@hidden Setting up a model with make
address@hidden Setup a model and compile with make
+
address@hidden compilation
address@hidden @cindex @file{dimetaphi.mti}
address@hidden @file{zinit.mti}
address@hidden model_file_name
+
+With make, the sequences are files ending with @samp{.mti} (for
+mortran include files),
+called, for example, @file{zinit.mti}.
address@hidden and @file{dimetaphi.mti}.
+They are included by
address@hidden in other source files. You also need a @file{Makefile}
+to drive the compilation of the model.
+
+If you don't need additional code or libraries to be linked with your
+model you have two alternatives.
+
address@hidden
address@hidden
+The simplest alternative is to run
+the @command{start_miniker} script with the model file name as argument.
+It should copy a @file{zinit.mti} file
+ready to be edited and a Makefile ready to compile the model. For
+the predator prey model, for example, you could run
+
address@hidden
+$ start_miniker predator
address@hidden example
+
address@hidden
+Otherwise you can copy the Makefile from @file{template/Makefile}
+in the directory containing the sequences. You should then change the compiled
+model file name, by changing the value of the
address@hidden variable to the name of your choice
+in the Makefile. It is set to @file{mymodel} in the template. For the
+predator-prey model, it could be set like
+
address@hidden
+model_file_name = predator
address@hidden example
+
+If you want the executable model file to be built in another directory, you
could
+set
+
address@hidden
+model_file_name = some_dir/predator
address@hidden example
+
+The other items set in the default Makefile should be right.
address@hidden enumerate
+
+The preprocessing and the compilation are launched with
+
address@hidden
+make all
address@hidden example
+
+The mortran files are generated by the cmz directive preprocessor
+from files found in the package source directories. The mortran files
+end with @samp{.mtn} for the main files and @samp{.mti} for
+include files. They are output in the current directory.
+The mortran preprocessor then preprocess these mortran files and includes
+the sequences. The resulting fortran code is also in the current directory,
+in files with a @samp{.f} suffix.
+Some fortran files ending with @samp{.F} may also be
+created by the cmz directive preprocessor.
+The object files resulting from the compilation of all the
+fortran files (generated from mortran or directly from fortran files) are
+there too.
+
+In case you want to override the default sequences or a subroutine file
+you just have to create it in your working directory along with the
address@hidden @c and @file{dimetaphi.mti}.
+For example you could want to
+create or modify a @file{zsteer.mti} file (@pxref{End of time step,,
+Executing code at the end of each time step}), a @file{zcmd_law.mti} file
+(@pxref{Control laws}), a @file{monitor.f} file
+(@pxref{Turning the model into a subroutine}) to take advantage of
+features presented later in this manual.
+
+More in-depth discussion of using make to run Miniker is covered in
address@hidden use of Miniker with make}.
+For example it is also possible to create files that are to be
+preprocessed by the cmz directive
+preprocessor and separate source files and generated files.
+This advanced use is more precisely covered in
address@hidden with cmz directives}.
+
address@hidden
address@hidden Simulation and output
address@hidden Running a simulation and using the output
+
address@hidden running model
+
+Once compiled the model is ready to run, it only has to be executed. On
+standard output informations about the states, transfers, tangent linear
+system and other jacobian matrices are printed.
+For example the predator-prey model could be executed with:
+
address@hidden
+./predator > result.lis
address@hidden example
+
address@hidden output file
address@hidden dEta(.)
address@hidden @file{res.data}
address@hidden @file{dres.data}
address@hidden @file{tr.data}
address@hidden @file{aspha.data}
address@hidden @file{Model.hlp}
+
address@hidden In case of a model entered symbolically
address@hidden (@pxref{Symbolic model description})
+The correspondance
+between the symbolic variables and the basic vectors and functions
+are printed at run time:
+
address@hidden
+ ---------------- Informing on Phi definition -----------------
+ Var-name, Function-name, index in ff vector
+ ff_interact f_interact 1
+ ----------------------------------------------------
+
+ --------------- Informing on Eta definition ------------------
+ Var-name, Function-name, index in eta vector
+ eta_prey deta_prey 1
+ eta_pred deta_pred 2
address@hidden example
+
+A summary of the model equations are in @file{Model.hlp} file. For
+the same example:
+
address@hidden
+======================= set_Phi
+
+ 1 ff_interact f_interact eta_pray*eta_pred
+======================= set_Eta
+
+ 1 eta_pray deta_pray apar*eta_pray-apar*ff_interact
+ 2 eta_pred deta_pred -cpar*eta_pred+cpar*ff_interact
address@hidden example
address@hidden FIXME never talked about that. Certainly not here
+when other general functions are specified with @code{f_set}, it can appear
+also in the same help file when replaced by @code{fun_set}.
+
+As far as possible, all data printed in the listing are associated
+with a name related to a variable. Here is an extract:
+
address@hidden
+ Gamma :-8.19100E-02-1.42151E-01 3.87150E-02
+ eta_courant eta_T_czcx eta_T_sz
+ ------------------------------------------------
+ Omega : 0.00000E+00 0.00000E+00 0.00000E+00 0.00000E+00
+ courant_L T_czcx Psi_Tczc Psi_Tsz
+ ------------------------------------------------
address@hidden example
+for the two known vectors of the system, and:
address@hidden
+ >ker : Matrice de couplage 4 4 4 4
+courant_L Raw(1,j=1,4): 1.000 -9.9010E-03 0.000 0.000
+T_czcx Raw(2,j=1,4): -2.7972E-02 1.000 0.000 9.9900E-04
+Psi_Tczcx Raw(3,j=1,4): 0.1605 9.7359E-02 1.000 -5.7321E-03
+Psi_Tsz Raw(4,j=1,4): 0.000 -0.1376 5.7225E-03 1.000
+ Var-Name courant_L T_czcx Psi_Tczc Psi_Tsz
+ ----------------------------------------------------------
address@hidden example
+
+where the @code{couplage} (coupling matrix) is given that corresponds
+to the matrix coupling the four transfer components after @math{\delta\eta}
+has been eliminated from system. It is computed in the subprogram
address@hidden (for kernel) which solves the system.
+
+Basic results are output in a set of @samp{.data} files.
+The first line (or two lines) describes the column with a @samp{#}
+character used to mark the lines as comments (for @command{gnuplot}
+for example).
+In the @samp{.data} files, the data are simply separated with spaces.
+Each data file has the @code{time} variable values as first column.
address@hidden@file{dres.data} has another time related variable as second
column:
address@hidden @file{dres.data}
address@hidden dt
address@hidden, the time step that can vary in the course of a simulation.}.
+Following columns give the values of @code{eta(.)} in @file{res.data},
address@hidden(.)} in @file{dres.data} -- the step by step variation of
address@hidden(.)} -- and @code{ff(.)} in @file{tr.data}.
+
+Along the simulation the @acronym{TEF} Jacobian matrices are computed.
+A transfer variables elimination process also leads to the definition
+of the classical state advance matrix of the system
+(the corresponding array is @code{aspha(.,.)} in the code).
+This matrix is output in the file @file{aspha.data} that is used to
+post-run dynamics analyses. The matrix columns are written column wise on each
+record.
address@hidden of fastest modes,,Stability analysis of fastest modes}.
address@hidden TLS,,Generalized
+tangent linear system analysis}. It is not used in the solving process.
+
+Other @samp{.data} files will be described later.
+
address@hidden FIXME already said
address@hidden At the begining of a run, the help file @file{Model.hlp} is
generated for
address@hidden global checkiing of the model. In the example, it is:
+
address@hidden @example
address@hidden ======================= set_Phi
address@hidden 1 ff_interact f_interact eta_pray*eta_pred
address@hidden ======================= set_Eta
address@hidden 1 eta_pray deta_pray
apar*eta_pray-apar*ff_interact
address@hidden 2 eta_pred deta_pred
-cpar*eta_pred+cpar*ff_interact
address@hidden @end example
+
+
address@hidden Graphics
address@hidden Doing graphics
+
address@hidden graphics
address@hidden graphics with @command{gnuplot}
address@hidden graphics with @command{PAW}
+
address@hidden The format of the @samp{.data} files are coherent with GNU
graphics, that is
address@hidden the data are simply separated with spaces.
+Since the data are simply separated with spaces, and comment lines
+begin with @samp{#}, the
+files can be vizualised with many programs.
+With @command{gnuplot}, for example, to plot @code{eta(@var{n})},
+the @command{gnuplot} statement could be:
+
address@hidden
+plot "res.data" using 1:(@var{n}+1)
address@hidden example
+
+The similar one for @code{ff(@var{n})}:
address@hidden
+plot "tr.data" using 1:(@var{n}+1)
address@hidden example
+
+For people using @command{PAW}, the CERN graphical computer code,
+Miniker prepares
+kumacs that allow to read process the @samp{.data} files in the form of
address@hidden (see the @cite{PAW manual} for more information).
+In that cas, the flag @code{sel paw} has to be gievn in the
@file{selsequ.kumac}.
+The generated n-tuples are ready to use only
+for vector dimension of at most 10 (including the variable @code{time}).
+These kumacs are overwritten each time the model is run. Usaually, gnuplot has
+to be preferred, but when using surfaces and histograms, PAW is better.
+The @file{gains.f} (and @file{go.xqt} is provided as an example in the
+Miniker files.
+
address@hidden Controlling the run
address@hidden Controlling the run
+
address@hidden controlling the run
+
+It is possible to add code that will be executed at the end of each time
+step. It is also possible to specify which time step leads to a printout on
+standard output. For maximal control, the code running te model may be
+turned into a subroutine to be called from another fortran (or C)
+program, this possibility is covered in @ref{Calling the model code}.
+
address@hidden
+* End of time step::
+* Controlling the printout and data output::
address@hidden menu
+
address@hidden End of time step
address@hidden Executing code at the end of each time step
+
address@hidden @file{zsteer}
address@hidden @file{zsteer.inc}
+
+The code in the sequence @file{zsteer} is executed at the end of each time
+step. It is possible to change the time step length (variable @code{dt})
+verify that the non linearity are not too big, or perform
+discontinuous modifications of the states. One available variable @code{res}
+might be usefull for time step monitoring. At the end of the time step,
+as soon as @math{\varphi} has been computed, a numerical test is applied
+on a pseudo relative quadratic residual between
address@hidden(\eta(t-dt)+d\varphi} (@code{ ffl}), where @math{d\varphi}
+is given by the system resolution in @code{ker},and
address@hidden(\eta),\varphi)}, Fortran variable (@code{ff}):
+
address@hidden
+! ========================================================
+! test linearite ffl - ff
+! ========================================================
+if (istep.gt.1)
+< res=0.; <io=1,m; res = res +(ffl(io)-ff(io))**2/max(one,ff(io)*ff(io)); >;
+ if (res .gt. TOL_FFL)
+ < print*,'*** pb linearite : res > TOL_FFL a istep',istep,res,' > ',TOL_FFL;
+ do io=1,m < z_pr: io,ff(io),ff(io)-ffl(io); >;
+ >;
+>;
address@hidden verbatim
+
+This test hence applies only for non linearities in tranfer models.
Nevertheless,
address@hidden might be usefull to monitor the time step @code{dt} in
@code{ZSTEER}
+and eventually go backward one step (@code{goto :ReDoStep:}).
+This can more appropriatly be coded in the (empty in default case)
+sequence @code{zstep}, inserted just before time-advancing
+states and @code{time} variables in @file{principal}.
address@hidden ffl(.)
address@hidden @code{ffl} (linearity test)
address@hidden linearity test
+
+It is also possible to fix the value of the criterium @code{TOL_FFL} in
address@hidden different from its default value of @math{10^{-3}} --
+independent of the Fortran precision.
+
+
+Many other variables are available, including
address@hidden @code
address@hidden istep
+The step number;
address@hidden couplage(.)
+The @acronym{TEF} coupling matrix between transfers;
address@hidden H
+The Jacobian matrix corresponding with:
address@hidden \varphi(t) &= f(\eta(t),\varphi(t))\cr
address@hidden \frac{\partial g(\eta(t),\varphi(t))}{\partial \eta(t)}
address@hidden
+$$\partial_{\eta} g(\eta(t),\varphi(t));
+$$
address@hidden tex
+g_1(eta,phi);
address@hidden Bb
+The Jacobian matrix corresponding with:
address@hidden
+$$\partial_{\varphi} g(\eta(t),\varphi(t));
+$$
address@hidden tex
+g_2(eta,phi);
address@hidden Bt
+The Jacobian matrix corresponding with:
address@hidden
+$$\partial_{\eta} f(\eta(t),\varphi(t));
+$$
address@hidden tex
+f_1(eta,phi);
address@hidden D
+The Jacobian matrix corresponding with:
address@hidden
+$$\partial_{\varphi} f(\eta(t),\varphi(t));
+$$
address@hidden tex
+f_2(eta,phi);
+
address@hidden aspha
+The state advance matrix;
address@hidden dneta
address@hidden dphi
+the variable increments;
address@hidden vtable
+One should be aware of that the linearity test concerns the preceding step.
+We have yet no example of managing the time-step.
+
address@hidden
address@hidden Controlling the printout and data output
address@hidden Controlling the printout and data output
+
address@hidden printing
address@hidden zprint
address@hidden modzprint
+
+The printout on standard output is performed if the variable @code{zprint}
+of type @code{logical} is true. Therefore it is possible to control this
+printout by setting @code{zprint} false or true. For example the following
+code, in sequence @file{zsteer}, triggers printing for every
address@hidden time step and the two following time steps:
+
address@hidden
+ZPRINT = mod(istep+1,modzprint).eq.0;
+Zprint = zprint .or. mod(istep+1,modzprint).eq.1;
+Zprint = zprint .or. mod(istep+1,modzprint).eq.2;
address@hidden example
+
+The data output to @file{.data} files described in @ref{Simulation and output,,
+Running a simulation and using the output} is performed if the
address@hidden variable @code{zout} is true. For example the following
+code, in @file{zsteer}, triggers output to @file{.data} files every
address@hidden step.
+
address@hidden
+Zout = mod(istep,modzout).eq.0;
address@hidden example
+
address@hidden Advanced programming
address@hidden Advanced Miniker programming
+
address@hidden
+* Selecting features::
+* Calling the model code::
+* 1D gridded model::
+* Double precision::
+* Partial Derivatives::
+* Rule of programming non continuous models::
+* Parameters::
+* Observations and data::
+* Explicit model size::
+* Programming with cmz directives::
address@hidden menu
+
address@hidden Selecting features
address@hidden Overview of additional features setting
+
address@hidden feature setting
address@hidden select flag
address@hidden logical flags
address@hidden @file{selseq.kumac}
+
+It is possible to enable some features by selecting which code should
+be part of the principal program. Each of these optionnal features are
+associated with a @dfn{select flag}.
+For example
address@hidden the optimisation with minuit is associated with the select
address@hidden flag @samp{minuik},
+double precision is used instead of simple precision with
+the @samp{double} select flag,
+the model is a subroutine with the select flag @samp{monitor},
+the Kalman filter code is set with @samp{kalman} and the 1D gridded
+model capabilities are associated with @samp{grid1d}.
address@hidden Currently it is only possible
address@hidden to select features in cmz.
+To select a given feature the cmz statement @code{sel @var{select_flag}} should
+be written down in the @file{selseq.kumac} found in the model directory.
+With make either the corresponding variable should be set to 1 or it
+should be added to the @code{SEL} make variable, depending on the feature.
+
+Other features don't need different or additional code to be used.
+Most of the features are enabled by setting specific logical variables to
address@hidden This is the case for
address@hidden for the adjoint model, @code{zcommand} if the command is in a
file
+and @code{zlaw} if it is a function and @code{zkalman} for the Kalman filter.
+These select and logical flags are described in the corresponding sections.
+
+In cmz an alternative of writing select flags to @file{selseq.kumac} is to
+drive the compilation with @code{smod @var{sel_flag}}. In that case the
address@hidden is selected and the files and executable goes to a directory
+named @file{sel_flag}.
+
+The select flags are taken into account during cmz directives preprocessing.
+Therefore you have the possibility to use these flags to conditionnaly
+include pieces of code. In most cases you don't need to include code
conditionally
+yourself though, but if you want to, this is covered in
address@hidden with cmz directives}.
+
address@hidden Calling the model code
address@hidden Calling the model code
+
+When the model code is a subroutine, it can be called from another fortran
+program unit (or another program), and the model will be
+run each time the subroutine is called.
+This technique could be used, for example to perform optimization
+(@pxref{Adjoint model and optimisation,,Adjoint model and optimisation
+with Miniker}), or to run the model with different parameters.
+
address@hidden
+* Turning the model into a subroutine::
+* The model subroutine::
address@hidden menu
+
address@hidden Turning the model into a subroutine
address@hidden Turning the model into a subroutine
+
address@hidden This feature is allready enabled with @command{make}, and to
address@hidden override the default program a file called @file{monitor.f} has
to be created
address@hidden in the working directory. The default program simple calls the
model
address@hidden subroutine.
+
+With cmz, one has to do a
address@hidden
+sel monitor
address@hidden example
+in the @file{selseq.kumac} file and create the KEEP that call the
+model code. @xref{Selecting features, Overview of additional features
+setting}.
+
+With make @samp{monitor} should be added to the @code{SEL} variable in
+the @file{Makefile}, for example:
+
address@hidden
+SEL = monitor
address@hidden example
+
+A file that call the principal subroutine should also be written, using
+the prefered language of the user. The additional object files should
+then be linked with the Miniker objects. To that aim they may be added
+to the @code{miniker_user_objects} variable.
+
address@hidden The model subroutine
address@hidden Calling the model subroutine
+
+The model subroutine is called @samp{principal} and is called with the
+following arguments:
+
address@hidden Subroutine principal (Cost, ncall, integer_flag, file_suffix,
info, idxerror)
+Where @var{Cost} is a real number, @code{real} or @code{double precision},
+and is set by the @code{principal}
+subroutine. It holds the value of the cost function if such function has been
+defined (the use and setting of a cost function is covered later,
+see @ref{Cost function coding and adjoint modeling}).
address@hidden is an integer which corresponds with the number of
+call to @code{principal} done so far, it should be initialized to 0 and
+its value should not be changed, as it is changed in the @code{principal}
+subroutine.
address@hidden is an integer that can be set by the user to be accessed
+in the @code{principal} subroutine. For example its value could be used to
+set some flags in the @file{zinit} sequence.
address@hidden is a character string, that is suffixed to the output files
+names instead of @samp{.data}. If the first character is the null character
address@hidden(0)}, the default suffix, @samp{.data} is appended.
address@hidden and @var{idxerror} are integer used for error reporting.
address@hidden value is 0 if there was no error. It is negative for
+an alert, positive for a very serious error. The precise value determines
+where the error occured.
address@hidden is an integer holding more precise information about the
+error. It is usually the information value from lapack.
+The precise meaning of these error codes is in @ref{tab:error_codes}.
address@hidden deffn
+
address@hidden table, tab:error_codes
address@hidden {kalman analysis state matrix advance in phase space,
@math{(I-D)} inversion} {inversion} address@hidden
address@hidden Source of error or warning @tab @code{info} @tab @code{idxerror}
address@hidden @item @code{} @tab @file{.data} @tab @tab
address@hidden state matrix inversion in ker @tab inversion @tab 1
address@hidden time advance system resolution in ker @tab system @tab 2
address@hidden transfer propagator, @math{(I-D)} inversion @tab inversion @tab 3
address@hidden kalman analysis state matrix advance in phase space,
@math{(I-D)} inversion @tab inversion @tab 21
address@hidden kalman analysis variance covariance matrix non positive @tab
Choleski @tab 22
address@hidden kalman analysis error matrix inversion @tab inversion @tab 23
address@hidden kalman error matrix advance @tab system @tab 24
address@hidden transfers determination linearity problem for transfers @tab
@tab -1
address@hidden transerts determination Newton D_loop does not converge @tab
@tab -2
address@hidden multitable
address@hidden of error codes returned by principal.}
address@hidden float
+
+In general more information than the provided arguments has to be passed
+to the @code{principal} subroutine, in that case a @code{common} block,
+to be written in the @file{zinit} sequence can be used.
+
address@hidden
address@hidden 1D gridded model
address@hidden Describing 1D gridded model
+
+Specific macros have been built that allow generic description of 1D gridded
models.
+Because of the necessity of defining left and right limiting conditions, the
models
+are partitionned in three groups for cell and transfer components. In the
following example,
+a chain of masselottes linked by springs and dumps is bounded to a wall on the
left,
+and open at right. The @acronym{TEF} formulation of the problem is written in
the phase space (position-shift, velocity)
+for node @math{k}, with bounding conditions:
address@hidden
+$$\left\{\eqalign{\partial_t \eta _{k} ^{pos} &= \eta _{k} ^{vel} \cr
+\partial_t \eta _{k} ^{vel} &= ( \varphi_k ^{spr} -\varphi _{k+1} ^{spr} +
\varphi _{k} ^{dmp}-\varphi _{k+1} ^{dmp})\,/m_k \cr}\right.$$
+$$\left\{\eqalign{
+\varphi_k ^{spr} &= -k_k (\eta _{k} ^{pos}- \eta _{k-1} ^{pos})\cr
+\varphi_k ^{spr} &= -d_k (\eta _{k} ^{vel}- \eta _{k-1} ^{vel})
+\cr}\right.$$
+$$\left\{\eqalign{\eta ^{pos}_{0} &= 0\cr
+\eta ^{vel}_{0} &= 0\cr
+\varphi ^{spr}_{N+1} &= 0\cr
+\varphi ^{dmp}_{N+1} &= 0\cr}\right.$$
address@hidden tex
+
+States:@*
address@hidden @math{d position(t,k)/d t = velocity(t,k)@*
+d velocity (t,k)/d t =(spring(t,k) - spring(t,k+1)+ dump(t,k)-
dump(t,k+1))/m_k}
+
+Transfers:@*
address@hidden @math{spring(t,k) = -k_k (position(t,k)- position(t,k-1))@*
+dump(k,t) &= -d_k (velocity(t,k)- velocity(t,k-1))}
+
+Bounding conditions:@*
address@hidden @math{position(t,0) = address@hidden
+velocity(t,0) = address@hidden
+spring(t,N+1) = address@hidden
+dump(t,N+1) =0}
+
+
address@hidden down node
address@hidden up node
+
+where @math{m_k} is the mass of node @math{k}, @math{r_k} and @math{d_k}
+the rigidity of springs and dumping coefficients. There are @math{N} nodes
+in the grid, from 1 to @math{N}, and two nodes outside of the grid,
+a limiting node 0, and a limiting node @math{N+1}. The limiting node
+corresponding with node 0 is called the @dfn{down} node, while the limiting
+node corresponding with node @math{N+1} is called the @dfn{up} node.
+Other models not part of the 1D grid may be added if any.
+
+To enable 1D gridded models, one should set the select flag @samp{grid1d}.
+In cmz it is achieved setting the select flag in
address@hidden, like
+
address@hidden
+sel grid1d
address@hidden example
+
+With make, the @code{SEL} variable should contain @code{grid1d}. For example
+to select @code{grid1d} and @code{monitor}, it could be
address@hidden
+SEL = grid1d,monitor
address@hidden example
+
+
address@hidden
+* 1D gridded Model size::
+* 1D gridded model code::
address@hidden menu
+
address@hidden 1D gridded Model size
address@hidden Setting dimensions for 1D gridded model
+
address@hidden FIXME grid1d sans dimetaphi?
+In that case the number of nodes, the number of states and tranferts
+per node, and the number of limiting transfers and states are required.
+These dimensions has to be entered in the
address@hidden sequence. The parameters for cells are
address@hidden @code
address@hidden n_node
+Number of cell nodes in the 1D grid.
address@hidden n_dwn
+Number of limiting cells with index -1, @i{i.e.} number of cells in the
+limiting down node.
address@hidden n_up
+Number of limiting cells with index +1, @i{i.e.} number of cells in the
+limiting up node.
address@hidden n_mult
+Number of cells in each node (multiplicity).
address@hidden vtable
+
address@hidden m_node
address@hidden m_dwn
address@hidden m_up
address@hidden m_mult
+The parameters for transfers, are similarly
address@hidden, @code{m_dwn}, @code{m_up}, @code{m_mult}.
+The layout of their declaration should be respected as
+the precompiler matches the line. Also this procedure is tedious, it
+should be selected for debuging processes (use the flag @code{sel dimetaphi}
+in ``selsequ.kumac''. Otherwise, the dimensioning sequence will be automaticaly
+generated, which is smart but can lead to diffculty in interpreting syntax
errors.
+Once a model is correctly entred, turn off the sel flag and further
modifications
+will automatically generate the proper dimensions. The correctness of
dimensionning
+should nevertheless always be checked in @code{principal.f}, where you can also
+check that null valued parameters as @code{lp, mobs, nxp} will suppress parts
+of the code - this is signaled as Fortran comment cards.
+
+In our example, there are three grids of cell and
+transfer variables (@code{n_node=m_node=3}).
+There are two cells and two transfers in each node
+(@code{n_mult=2} and @code{m_mult=2}). There is no limiting condition
+for the states in the down node therefore @code{n_up=0}.
+There is no transfer for the first limiting node, and
+therefore @code{m_dwn=0}.
+There are two states in the limiting node 0, the down node,
address@hidden, and two transfers in the limiting last node the node up,
+and @code{m_up=2}:
+
address@hidden
+! ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+! nodes parameters, and Limiting Conditions (Low and High)
+! ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+ parameter (n_node=3,n_dwn=2,n_up=0,n_mult=2);
+ parameter (m_node=3,m_dwn=0,m_up=2,m_mult=2);
+! ________________________________________________________
address@hidden example
+
+
address@hidden 1D gridded model code
address@hidden 1D gridded Model coding
+
+The model code and parameters go in the @file{zinit} sequence.
+
address@hidden Parameters
+
+A value for the Miniker parameters and the model parameters should be given in
address@hidden, in our example we have
+
address@hidden
+!%%%%%%%%%%%%%%%%%%%%%%
+! Parameters
+!%%%%%%%%%%%%%%%%%%%%%%
+real rk(n_node),rd(n_node),rmassm1(n_node);
+
+data rk/n_node*1./;
+data rd/n_node*0.1/;
+data rmassm1/n_node*1./;
+ dt=.01;
+ nstep=5 000;
+ modzprint = 1000;
+ time=0.;
address@hidden example
+
address@hidden Limiting conditions
+
address@hidden limiting conditions
+
address@hidden The limiting states and transfer variables and the corresponding
equations are
address@hidden declared using
address@hidden the symbolic model description
address@hidden (@pxref{Symbolic model description}).
+There are four mortran blocks for @code{node} and @code{up} and @code{down},
both
+for states and transfers:
+
address@hidden set_dwn_eta
address@hidden set_dwn_phi
address@hidden set_up_eta
address@hidden set_up_phi
+
address@hidden @code
address@hidden set_dwn_eta
+down node cells
address@hidden set_up_eta
+up node cells
address@hidden set_dwn_phi
+down node transfers
address@hidden set_up_phi
+up node transfers
address@hidden table
+
+The following scheme illustrates the example:
address@hidden
+!%%%%%%%%%%%%%%%%%%%%%%%%%%================================================
+! Maillage convention inode
+!%%%%%%%%%%%%%%%%%%%%%%%%%% Open ended
+!(2 Down Phi Eta (n_node)
+! Eta) \| .-----. .-----. .-----. /
+! wall \|-\/\/\-| |-\/\/\-| | . . . -| |-\/\/\- |dummy
+! pos \|--***--| 1 |--***--| 2 | . . . -| n |--***-- |Phis
+! speed \| 1 |_____| 2 |_____| n |_____| n+1 \(2 Up Phi)
+!
address@hidden smallexample
+
+Two states are associated with the down node, they correspond to the position
+and speed of the wall. As the wall don't move these states are initialized to
+be 0, and the cells are stationnary cells, therefore these values remain 0.
+
address@hidden
+! Down cells (wall)
+! -----------------
+eta_pos_wall = 0; eta_speed_wall = 0.;
+
+set_dwn_eta
+< var: eta_pos_wall, fun: deta_pos_wall = 0.;
+ var: eta_speed_wall, fun: deta_speed_wall= 0.;
+>;
address@hidden example
+
+There are 2 limiting transfers in the up node. They correspond with an open
+end and are therefore set to 0.
+
address@hidden
+! limiting Transfers : dummy ones
+! -------------------------------
+set_Up_Phi
+< var:ff_dummy_1, fun: f_dummy_1=0.;
+ var:ff_dummy_2, fun: f_dummy_2=0.;
+>;
address@hidden example
+
address@hidden Starting points
+
+The cell node state values are initialized. They are in an array
+indexed by the @code{inode} variable. In the example the variable
+corresponding with position is @code{eta_move} and the variable corresponding
+with speed is @code{eta_speed}. Their initial values are set with the
+following mortran code
+
address@hidden
+!---------------
+! Initialisation
+!---------------
+;
+do inode=1,n_node <eta_move(inode)=0.01; eta_speed(inode)=0.0;>;
address@hidden example
+
+If any transfer needs to be given a first-guess value, this is also done
+using @code{inode} as the node index.
+
address@hidden Grid node equations
+
address@hidden set_node_Phi
address@hidden set_node_eta
address@hidden equations, grid
+
+Each node is associated with an index @code{inode}. It allows to refer to the
+preceding node, with @code{inode-1} and the following node @code{inode+1}.
+The node states are declared in @code{set_node_Eta} block and the transfers are
+in @code{set_node_Phi} blocks.
+
+In the example, the cells are declared with
+
address@hidden
+! node cells
+! ----------
+;
+set_node_Eta
+< var: eta_move(inode), fun: deta_move(inode) = eta_speed(inode);
+ var: eta_speed(inode),
+ fun: deta_speed(inode) = rmassm1(inode)
+ *( - ff_spring(inode+1) + ff_spring(inode)
+ - ff_dump(inode+1) + ff_dump(inode)
+ );
+>;
address@hidden example
+Note that the @code{inode} is dummy in the @code{var:} definition and can as
+well be written as: @code{var: eta_move(.)}.
+
+
+The transfers are (@code{ff_spring} corresponds with springs and
address@hidden with dumps):
+
address@hidden
+!%%%%%%%%%%%%%%%%%%%%%%
+! Transfer definition
+!%%%%%%%%%%%%%%%%%%%%%%
+! node transfers
+! --------------
+! convention de signe spring : comprime:= +
+set_node_Phi
+< var: ff_spring(.),
+ fun:
+ f_spring(inode)= -rk(inode)*(eta_move(inode) - eta_move(inode-1));
+ var: ff_dump(.),
+ fun:
+ f_dump(inode) = -rd(inode)*(eta_speed(inode) - eta_speed(inode-1));
+>;
address@hidden example
+
+The limiting states and transfers are associated with the states or transfers
+with index @code{inode+1} or @code{inode-1} appearing in node cell and
+transfer equations (@code{inode-1} for down limiting conditions and
address@hidden for up limiting conditions) in their order of appearance.
+In our example, in the @code{eta_speed} state node equation
address@hidden(inode+1)} appears before @code{ff_dump(inode+1)} and is
+therefore associated with @code{ff_dummy_1} while @code{ff_dump(inode+1)} is
+associated with the @code{ff_dummy_2} limiting transfer, as @code{ff_dummy_1}
+appears before @code{ff_dummy_2} in the limiting up transfers definitions.
+Verification of the grid index coherence should be eased with the following
+help printed in the listing header:
+
address@hidden
+
+
+
+
+ --------------- Informing on Dwn Eta definition ---------------
+ Var-name, Function-name, index in eta vector
+ eta_pos_wall deta_pos_wall 1 [
+ eta_speed_wall deta_speed_wall 2 [
+
+ -------------- Informing on Eta Nodes definition --------------
+ Var-name, Function, k2index of (inode: 0 [ 1,...n_node ] n_node+1)
+ eta_move deta_move 1 [ 3 ... 7 ] 9
+ eta_speed deta_speed 2 [ 4 ... 8 ] 10
+
+ ---------------- Informing on Up Phi definition -------------
+ Var-name, Function-name, index in ff vector
+ ff_dummy_1 f_dummy_1 ] 7
+ ff_dummy_2 f_dummy_2 ] 8
+ ff_move_sum f_move_sum ] 9
+ ff_speed_sum f_speed_sum ] 10
+ ----------------------------------------------------
+
+ -------------- Informing on Phi Nodes definition ---------------
+ Var-name, Function, k2index of (inode: 0 [ 1,...m_node ] m_node+1)
+ ff_spring f_spring -1 [ 1 ... 5 ] 7
+ ff_dump f_dump 0 [ 2 ... 6 ] 8
+ ----------------------------------------------------
address@hidden example
+
+All variable names and functions are free but has to be
+different.
+Any particular node-attached variable @math{k} is referred to as:
@samp{(inode:k)},
+where @math{k} has to be a Fortran expression allowed in arguments. The symbol
address@hidden is
+reserved. As usual other Fortran instructions can be written within the
+Mortran block @samp{< >} of each @code{set_} block.
+
address@hidden Double precision
address@hidden Double precision
+
+The default for real variables is the @code{real} Fortran type. It is possible
to
+use double precision instead. In that case all the occurences of @samp{real@ }
+in mortran code is substituted with @samp{double precision@ } at
+precompilation stage,
+and the Lapack subroutine names are replaced by the double precision names.
+Eventual users'declaration of @code{complex@ } Fortran variables is also
+changed to @code{double complex@ }.
+
+This feature is turned on by @code{sel double} in @file{selseq.kumac} with cmz
+and @code{double = 1} in the @file{Makefile} with make.
+
+In order for the model to run as well in double as in simple precision,
+some care should be taken to use the generic intrinsic functions, like
address@hidden and not @code{dsin}. No numerical constant should be passed
directly
+to subroutines or functions, but instead a variable with the right type should
+be used to hold the constant value, taking advantage of the implicit casts
+to the variable type.
+
address@hidden Partial Derivatives
address@hidden Partial Derivatives
+
+The partial derivative rules are included in a @code{Mortran} macro series
+in @file{Derive_mac} of Miniker files. When using an anusual function,
+one should verify that the corersponding rules are in that file.
+It is easy to understand and add new rules in analogy with the already
existing ones.
+
+For instance, suppose one wants to use the intrinsic Fortran function @code{
abs()}.
+Its derivatives uses the other function @code{sign()} this way:
+
address@hidden
+ &'(ABS(#))(/#)' = '((#1)(/#2)*SIGN(1.,#1))'
address@hidden example
+
+In such cases when one is adding a new rule, it is important to use the
generic function names
+only (i.e. @code{sin} not @code{dsin}), because when compilating Miniker in
the double precision
+version, or complex version, the generic names will correctly handle the
different variable
+types - which is not the case when coding with specific function names.
+
address@hidden
+* Derivating a power function::
address@hidden menu
+
address@hidden Derivating a power function
address@hidden Derivating a power function
+
+Partial derivative of a function in exponent is not secure in its Fortran form
address@hidden(x,y)**(f(y))}. It should be replaced by @code{power(g,f)} of
+the Miniker @file{mathlib},
+or by the explicit form @code{exp(f(y)*log(g(x,y)))}.
+
+Its derivative will have the following form:
+
+
address@hidden
+$$\eqalign{\partial_x f^g &= g f^{g-1}\partial_x f + f^g \log f\partial_x g\cr
+ &= f^{g-1}(g\partial_x f + f\partial_x g)\cr}$$
address@hidden tex
+
+and is in the macros list already defined in: @file{DERIVE_MAC}.
+
address@hidden Rule of programming non continuous models
address@hidden Rule of programming non continuous models
+
+Some models may originally be non continuous, as the ones using a Fortran
instruction @code{IF}.
+Some may use implicitly a step function on a variable. In such cases, the
model has to be
+set in a derivable form, and use a ``smooth step'' instead.
+ One should be aware of that this apparently mathematical treatment currently
+indeed leads to a physical question about the macroscopic form of a physical
law.
+At a macroscipic level, a step function is usually a nonsense.
address@hidden Heaviside function
+Taking
+the example of phase-change, a fluid volume does not change phase at once, and
a ``smooth
+change of state'' is a correct macroscopic model.
+
+Miniker provides with the smooth step function
address@hidden@footnote{This naming is a joke
+for ``Inert'' Heaviside function.} in the Miniker @file{mathlib}:
+
address@hidden
+ Delta = -1."K";
+ A_Ice = heavyside("in:" (T_K-Tf), Delta, "out:" dAIce_dT);
address@hidden example
+
+in this example, @code{Tf} is the ice fusion-temperature, @code{A_ice}
+gives the ice-fraction
+of the mesh-volume of water at temperature @code{T_k}.
+The smooth-step function is a quasi
+hyperbolic tangent function of @math{x/\Delta},
+normalised from 0 to 1, with a maximum slope
+of 2.5, see figure @ref{heavy}.
+
address@hidden Figure, heavy
address@hidden
address@hidden function and derivative}
address@hidden float
+
+For @code{Mortran} to be able to symbolicaly compute the partial derivarives,
the rule
+is in the table of macros as:
+
address@hidden
+&'(HEAVYSIDE(#,#,#))(/#)' = '((#1)(/#4)*HEAVYDELTA(#1,#2,#3))'
address@hidden example
+
+which uses the Foratn entry point @code{HeavyDelta} in the Fortrsan function
@code{heavyside}.
+
+Another type of problem arises when coding a
address@hidden(f(x),g(x))} Fortran instruction.
+In such a case one does not want a derivative and one will code:
+
address@hidden
+var = HeavySide(f(x)-g(x),Delta,dum)*g(x) +
(1.-HeavySide(f(x)-g(x),Delta,dum)*f(x);
address@hidden example
+
+or equivalently:
+
address@hidden
+var = HeavySide(f(x)-g(x),Delta,dum)*g(x) +
HeavySide(g(x)-f(x),-Delta,dum)*f(x);
address@hidden example
+
address@hidden: the value of the argument @var{Delta} is important because
+it will fix the maximum
+slope of the function that will appear as a coefficient in the
+Jacbian matrices.
+
address@hidden Parameters
address@hidden Parameters
+
+It is possible to specify some Fortran variables as specific model parameters.
+Model parameters
+may be used in sensitivity studies (@pxref{Sensitivity to a parameter})
+and in the adjoint model (@pxref{Sensitivity of cost function to parameters}).
+Nothing special is done with parameters with Kalman filtering.
+
+
address@hidden Free_parameter
+
+The parameters are fortran variables that should be initialized somewhere
+in @file{zinit}. For a variable to be considered as a parameter, it should
+be passed as an
+argument to the @code{Free_parameters} macro. For example if
address@hidden and @code{cpar} (from the predator example) are to be considered
+as parameters, @code{Free_parameters} should be called with:
+
address@hidden
+Free_parameter: apar, cpar;
address@hidden example
+
address@hidden Forward sensitivities are explained later (@pxref{Sensitivity to
a parameter}),
address@hidden the syntax only is described here.
+
+
+When used with grid1d models (@pxref{1D gridded model,,
+Describing 1D gridded model}) the @code{inode} number may appear in
+parenthesis:
+
address@hidden
+Free_parameter: rd(1), rk(2);
address@hidden example
+
address@hidden Observations and data
address@hidden Observations and data
+
+Some support for observations and interactions with data is available.
+The observations are functions of the model variables. They don't have
+any action on the model result, but they may (in theory) be observed
+and measured. The natural use of these observations is to be compared
+with data that correspond with the values from real measurements.
+They are used in the Kalman filter (@pxref{Kalman filter}).
+
+The (model) observation vector is noted @math{\omega}
address@hidden FIXME is seems untrue?
address@hidden in this section ($\mu$ elsewhere,
+and the observation function is noted @math{h}:
+
address@hidden
+$$
+\omega = h ( \eta , \varphi)
+$$
address@hidden tex
+
address@hidden @math{omega(t) = h(eta(t), phi(t))}
+
+
address@hidden
+* Observations::
+* Data::
address@hidden menu
+
address@hidden Observations
address@hidden Observations
+
address@hidden mobs
+
+The observation functions are set in a @code{set_probe} block in
+the @file{zinit} sequence.
+
address@hidden observation function
+
address@hidden FIXME doesn't exist anymore
address@hidden @defmac eqn: Obs_tef(@var{i}) = f(eta(.),ff(.))
address@hidden This macro defines the observation equation as usual in a
@code{set_block<}.
address@hidden @code{f} is a fortran
address@hidden expression which may be function of cell state variables,
address@hidden @samp{eta(1)address@hidden@samp{eta(np)} and transfers
address@hidden @samp{ff(1)address@hidden@samp{ff(mp)}, or of course their
symbolic names.
address@hidden @end defmac
+
+For example suppose that, in the predator-prey model, we only
+have access to the total population of preys and predators, we would have:
+
address@hidden
+set_probe
+< eqn: pop = eta_pred + eta_pray;
+>;
address@hidden example
+
address@hidden it is always turned on, now
address@hidden The corresponding code is used with @code{sel obs} in
@file{selseq.kumac}
address@hidden with cmz and @code{obs = 1} in @file{Makefile} with make. And
the feature
address@hidden is turned on and off at run time with the logical flag
@code{zobs} corresponding
address@hidden to an available data from measurement
+
address@hidden @vindex etaobs(.)
address@hidden @file{obs.data}
+
+The number of observations is put in the integer variable @code{mobs}.
+The observation vector corresponds with the part of the @code{ff(.)}
+array situated past the regular transferts, @code{ff(mp+.)}, and is output
+in the file @file{obs.data}.
+
address@hidden @vindex obetad(.,.)
address@hidden @vindex obephid(.,.)
address@hidden @vindex obspha(.,.)
+
address@hidden Data
address@hidden Data
+
address@hidden zgetobs
address@hidden vobs(.)
address@hidden @file{data.data}
+
+Currently this code is only used if the Kalman code is activated. This
+may be changed in the future.
+
+The convention for data is that whenever some data are available, the
+logical variable @code{zgetobs} should be set to @samp{.true.}. And the
address@hidden(.)} vector should be filled with the data values. This
+vector has the same dimension than the observation
+vector and each coordinate is meant to correspond with one
+coordinate of the observation vector.
+
+This feature is turned on by setting the logical variable @code{zdata}
+to @samp{.true.}, and the @code{zgetobs} flag is typically set in the
address@hidden sequence (@pxref{End of time step,,Executing code at
+the end of each time step}).
+Every instant data are available (@code{zgetobs} is true) the observations
+are written to the file @file{data.data}. With the Kalman filter more
+informations are output to the @file{data.data} file,
+see @ref{Kalman filter results}.
+
+
address@hidden Explicit model size
address@hidden Entering model size explicitely
+
+It is possible to enter the model dimensions explicitely, instead of
+generating them automatically, as it was done previously.
+This feature is turned on by @code{sel dimetaphi}
+in @file{selseq.kumac} with cmz
+and @code{dimetaphi} added to the @code{SEL} variable in
+the @file{Makefile} with make.
+
address@hidden
+* Size sequence::
+* Model with explicit size::
address@hidden menu
+
address@hidden Size sequence
address@hidden The explicit size sequence
+
address@hidden dimetaphi
address@hidden model size
address@hidden np
address@hidden mp
address@hidden maxstep
address@hidden @file{dimetaphi}
+
+The dimension of the model is entered in the sequence @file{dimetaphi},
+using the fortran @code{parameter np} for @code{eta(.)} and
address@hidden for @code{ff(.)}.
+For the Lotka-Volterra model, we have two cell components and only one
transfer.
+
address@hidden
+parameter (np=2,mp=1);
address@hidden example
+
+You should not change the layout of the parameter statement as the
+mortran preprocessor matches the line.
+
+You also have to provide other parameters even if you don't have any
+use for them. If you don't it will trigger fortran errors.
+It includes the @code{maxstep} parameter that can have any value but 0,
address@hidden and @code{mobs} that should be 0 in the example, and @code{nxp},
address@hidden and @code{nzp} that should also be 0.
+The layout is the following:
+
address@hidden
+parameter (np=2,mp=1);
+parameter (mobs=0);
+
+parameter (nxp=0,nyp=0,nzp=0);
+parameter (lp=0);
+parameter (maxstep=1);
address@hidden example
+
+If there are observations, (@pxref{Observations}), the
+size of the observation vector is set in the @file{dimetaphi} sequence
+by the @code{mobs} parameter. For example if there is one observation:
+
address@hidden
+parameter (mobs=1);
address@hidden example
+
+To specify parameters (@pxref{Parameters}), the number of such parameters
+has to be declared in @file{dimetaphi} with the parameter @code{lp}.
+Then, if there are two parameters, they are first declared with
+
address@hidden
+parameter (lp=2);
address@hidden example
+
address@hidden Model with explicit size
address@hidden Entering the model equations, with explicit sizes
+
address@hidden model equations
address@hidden Phi_tef(.)
address@hidden deta_tef(.)
address@hidden eta(.), explicit sizes
address@hidden ff(.), explicit sizes
+
+When sizes are explicit, another possibility exists for entering
+the model equations. The use of symbolic names, as described in
address@hidden equations} is still possible, and it also becomes possible to
+set directly the equations associated with the @code{eta(.)}
+and @code{ff(.)} vectors.
+
+In case the symbolic names are not used,
+the model equations for cells and transfers are entered using a mortran macro,
address@hidden@address@hidden, or equivalently @code{f_set}, is a
+general mortran macro associating a symbol with a fortran expression.
+Here, it is the name of the symbol (@code{eta}) that has a particular meaning
+for the building of the model.}, setting the @code{eta(.)} evolution with
address@hidden(.)}
+and the transfer definitions @code{ff(.)} with @code{Phi_tef(.)}.
+
address@hidden f_set Phi_tef(@var{i}) = f(eta(.),ff(.))
+This macro defines the transfer @var{i} static equation.
address@hidden is a fortran
+expression which may be function of cell state variables,
address@hidden(1)address@hidden@samp{eta(np)} and transfers
address@hidden(1)address@hidden@samp{ff(mp)}.
address@hidden defmac
+
+In the case of the predator-prey model, the transfer definition for
address@hidden is:
address@hidden
+f_set Phi_tef(1) = eta(1)*eta(2);
address@hidden example
+
address@hidden f_set deta_tef(@var{i}) = g(eta(@var{i}),ff(.))
+This macro defines the cell state component @var{i} time evolution model.
address@hidden is a expression which may be function of cell state variables,
address@hidden(1)address@hidden@samp{eta(np)} and transfers
address@hidden(1)address@hidden@samp{ff(mp)}.
address@hidden defmac
+
+The two cell equations of the predator-prey model are, with index 1 for the
+prey (@math{\eta_{prey}}) and index 2 for the predator (@math{\eta_{pred}}):
+
address@hidden
+f_set deta_tef(1) = apar*eta(1)-apar*ff(1);
+f_set deta_tef(2) = - cpar*eta(2) + cpar*ff(1);
address@hidden example
+
+The whole model is:
+
address@hidden
+!%%%%%%%%%%%%%%%%%%%%%%
+! Transfer definition
+!%%%%%%%%%%%%%%%%%%%%%%
+! rencontres (meeting)
+ f_set Phi_tef(1) = eta(1)*eta(2);
+
+!%%%%%%%%%%%%%%%%%%%%%%
+! Cell definition
+!%%%%%%%%%%%%%%%%%%%%%%
+! eta(1) : prey
+! eta(2) : predator
+
+ f_set deta_tef(1) = apar*eta(1)-apar*ff(1);
+ f_set deta_tef(2) = - cpar*eta(2) + cpar*ff(1);
address@hidden example
+
+The starting points for cells are entered like:
address@hidden
+! initial state
+! -------------
+ eta(1) = 1.;
+ eta(2) = 1.;
address@hidden example
+
+If there are observations, they are entered as special transferts with
+index above @code{mp}, for example:
+
address@hidden
+f_set Phi_tef(mp+1) = ff(1) ;
address@hidden example
+
address@hidden Programming with cmz directives
address@hidden Programming with cmz directives
+
address@hidden
+* Cmz directives used with Miniker::
+* Using cmz directives in Miniker::
address@hidden menu
+
address@hidden Cmz directives used with Miniker
address@hidden Cmz directives used with Miniker
+
+The main feature of cmz directive is to use code conditionnaly for a given
+select flag. For example when the double precision is selected
+(@pxref{Double precision}) the use of the conditionnal
address@hidden flag may be required in case there is a different subroutine
+name for different types. If, for example, the user use the subroutine
address@hidden for simple precision and @code{dmysub} for double
+precision the following code is an example of what could appear in the
+user code:
+
address@hidden
++IF,double
+ call dmysub(eta);
++ELSE
+ call smysub(eta);
++ENDIF
address@hidden verbatim
+
+For a complete reference on cmz directives see the appendix
address@hidden directives reference}.
+
address@hidden Using cmz directives in Miniker
address@hidden Using cmz directives in Miniker
+
+In cmz the KEEP and DECK have their cmz directives preprocessed as part
+of the source files extraction. And the +KEEP and +DECK
+directives are automatically
+set when creating the KEEP or DECK. With make, files with these directives
+has to be created within the files that are to be preprocessed by the
+cmz directives preprocessor.
+
+To be processed by make, a file that contains cmz directives
+should have a file suffix corresponding
+with the language of the resulting file and with the normal file suffix of
+that language. More precisely @samp{cm} should be added before the normal
+file suffix and after the @samp{.}. Therefore if the resulting file language
+is associated with a suffix @address@hidden, the file with cmz directives
+should have a @address@hidden suffix. The tradition is to have
+a different suffix for main files and include files.
+To add directories searched for @dfn{cmfiles} (files with cmz directives)
+they should be added to the @code{CMFDIRS} makefile variable, separated
+by @samp{:}.
+
+Rules for preprocessing of the files are defined in the file
address@hidden for the file types described in
address@hidden:cmfile_suffix}:
+
address@hidden table, tab:cmfile_suffix
address@hidden {fortran preprocessed} {include/keep} {cmfile suffix} {suffix}
{language}
address@hidden language @tab file type @tab cmfile suffix @tab suffix @tab
language
address@hidden fortran @tab main/deck @tab .cmf @tab .f @tab ftn
address@hidden fortran preprocessed @tab main/deck @tab .cmF @tab .F @tab f77
address@hidden fortran preprocessed @tab include/keep @tab .cminc @tab .inc
@tab f77
address@hidden mortran @tab main/deck @tab .cmmtn @tab .mtn @tab mtn
address@hidden mortran @tab include/keep @tab .cmmti @tab .mti @tab mtn
address@hidden multitable
address@hidden between file language, file type, file suffixes and
+language identifier in cmz directives. A main file is called a @dfn{deck}
+in cmz and an include file is called a @dfn{keep}.}
address@hidden float
+
address@hidden Dynamic system analysis
address@hidden Dynamic analysis of systems in Miniker
+
address@hidden
+* Sensitivities::
+* Adjoint model and optimisation::
+* Kalman filter::
+* Feedback gain::
+* Stability of fastest modes::
+* Generalized TLS::
address@hidden menu
+
address@hidden Sensitivities
address@hidden Automatic sensitivity computation
+
address@hidden sensitivities
+
+An obvious advantage of having acces to the Jacobian matrices along the
+system trajectory concerns automatic sensitivity analyses, as either:
address@hidden @bullet
address@hidden the sensitivity of all variables to perturbation in the initial
condition
+ of one state variable;
address@hidden the same sensitivities to an initial pulse (or step) on a
transfer;
address@hidden the same sensitivities to a series of pulses (or steps) on a
transfer;
address@hidden the same for a change in a parameter, eventually during the run;
address@hidden the sensitivity of the matrix of advance in state space to a
change
+ in a parameter.
address@hidden itemize
+
+This is declared in Zinit as:
+
address@hidden
+! -------------
+! Sensitivities
+! -------------
+Sensy_to_var
+< var: eta_pray, pert: INIT;
+ var: eta_pred, pert: INIT;
+>;
address@hidden example
+
+Each variable at origin of a perturbation is declared as @code{var:},
+and the type of perturbation in @code{pert:}. Here, INIT conditions are
+only allowed because the two variables are states variables. For transfers,
address@hidden: pulse} corresponds to an initial pulse, @code{pert: step_resp}
+and @code{pert: step_eff} to initial steps, the difference between
address@hidden (response form)
+and @code{_eff} (effect form) concerns the
+diagonal only of the sensitivity matrix
+(see Feedback gains in non-linear models).
+
+Non initial perturbation can also be asked for:
+
address@hidden
+ Sensy_to_var
+ <
+!* var: eta_courant_L, pert: init at 100;
+!* var: ff_T_czcx, pert: pulse at 100 every 20;
+!* var: ff_Psi_Tczcx, pert: step_eff;
+!* var: ff_Psi_Tczcx, pert: step_Resp at 10 every 100;
+! *** premiers tests identiques a lorhcl.ref
+ var: ff_courant_L , pert: step_eff;
+ var: ff_T_czcx , pert: step_eff;
+ var: ff_Psi_Tczcx , pert: step_eff;
+ var: ff_Psi_Tsz , pert: pulse at 100 every 50;
+ >;
address@hidden example
+
+In this example taken from @file{lorhcl}, a sensitivity can increase so as to
+trespass the Fortran capacity, so that each sensitivity vector (matrix column)
+can be reset at some time-increment @code{at III every JJJ;}
+
+It is noteworthy that these sensitivity analyses are not based
+on difference between two runs with different initial states or
+parameter values, but on the formal derivatives of the model. This method
+is not only numerically robust, but is also rigorously funded as based on
+the TLS of the address@hidden a short introduction to automatic
+sensitivity analysis, see the document:@*
address@hidden://lmd.jussieu.fr/zoom/doc/sensibilite.ps}, in French,
+or ask for the more complete research document to a member of the TEF-ZOOM
+collaboration}.
+
+If the @code{dimetaphi} sequence is built by the users, he should declare
+the number of perturbing variables as @code{nxp=}:
+
address@hidden
+ parameter (nxp=np,nyp=0,nzp=0);
address@hidden example
+here, all state variables are considered as perturbing variables.
+
address@hidden sensitivity, output
address@hidden output, sensitivity
address@hidden @file{sens.data}
address@hidden @file{sigma.data}
+
+The sensitivity vectors are output in the result files @file{sens.data} for
+cells and @file{sigma.data} for transfers. In those files the first column
+corresponds again with time, and the other columns are relative sensitivities
of the cell
+states (in @file{sens.data}) and transfers (in @file{sigma.data})
+with respect to the initial value of the perturbed state.
+
+In our predator-prey example, the second column of @file{sens.data} will
contain
+the derivative of @math{\eta_1(t)} with respect to @math{\eta_1(t=0)}.
+Drawing the
+second column of @file{sens.data} against the first one
+gives the time evolution of the sensitivity of @code{eta-pred}
+to a change in the initial value of @code{eta-pray}. One can check
+in that it is set to 1 at @math{t=0}:
+
address@hidden
+# Sensy_to: eta_pray 3 eta_pred 5
+# time \\ of: eta_pray eta_pred eta_pray eta_pred
+ 0.00000E+00 1.00000E+00 0.00000E+00 0.00000E+00 1.00000E+00
+ 1.00000E-02 9.90868E-01 1.11905E-02 -1.26414E-02 9.98859E-01
address@hidden example
+The two last columns are the state sensitivity to a change in initial
conditions
+of the number of predators.
+
+In the same way, the @var{j+1}th column of @file{sigma.data} will be the
+derivative of @math{\phi_{j}(t)} with respect to @math{\eta_i(t=0)}. Here:
address@hidden
+# Sensy_to: eta_pray eta_pred
+# time \\ of: ff_interact ff_interact
+ 0.00000E+00 1.60683E+00 8.47076E-01
+ 1.00000E-02 1.59980E+00 8.18164E-01
address@hidden example
+
+the unique transfer variable gives rise to two sensitivity columns.
+
+Sensitivity studies are usefull to assess the
+predictability properties of the corresponding system.
+
address@hidden
address@hidden * Initial state sensitivity::
address@hidden * Sensitivity to a pulse or a step on transfer::
address@hidden * Extended Sensitivity studies::
+* Sensitivity to a parameter::
+* Advance matrix sensitivity::
address@hidden menu
+
+
+
address@hidden Sensitivity to a parameter
address@hidden Sensitivity to a parameter
+
+A forward sensitivity to a parameter will be computed when specified as
+described in @ref{Parameters}. For example, suppose that
+the sensitivity to an initial change in the @code{apar} parameter of
+the predator model is of interest.
address@hidden In that case the number of
address@hidden parameters should be set to 1 in @file{dimetaphi}:
address@hidden
address@hidden @example
address@hidden parameter (lp=2);
address@hidden @end example
+
+The sensitivity calculs is turned on as a forward
+parameter specified on the @code{Free_parameter} list:
+
address@hidden
+Free_parameter: [fwd: apar, cpar];
address@hidden example
+
+The result are in @file{sensp.data} for cells and @file{sigmap.data}
+for transfers.
+
address@hidden
+# Sensy_to: pi_prandtl 3 4 pi_rayleigh_ 6
+# time \\ of: eta_courant_ eta_T_czcx eta_T_sz eta_courant_ eta_T
+ 0.00000E+00 0.00000E+00 0.00000E+00 0.00000E+00 0.00000E+00 0.000
+ 2.00000E-03 -4.77172E-03 -3.99170E-05 3.55971E-05 -9.94770E-05 -1.004
address@hidden example
+In the above example from @file{lorhcl} sensitivity of the three states with
respect
+to an initial change in two parameters are independantly given (first line
also numbers
+the column to easy gnuplot using).
+
address@hidden Advance matrix sensitivity
address@hidden Advance matrix sensitivity
+
+
+It is possible to look at the sensitivity of the matrix of advance in
+states space (the matrix @code{aspha}) with regard to a parameter.
+The parameter must be accounted for in the parameter number and be in the
+parameter list, flagged as the matrix @code{mx} parameter, like in
address@hidden
+Free_parameter: [mx: apar], cpar;
address@hidden example
+
address@hidden d_pi_aspha(.,.)
+
+This feature is associated with a selecting flag, @samp{dPi_aspha}. One gets
+the result in the matrix @code{d_pi_aspha(.,.)} of dimension
+(@code{np},@code{np}).
+
+This matrix may be used to compute other quantities, for example
+it may be used to compute the sensitivity of the eigenvalues of
+the state-advance matrix with regard to the @code{[fwd]} parameter.
+These additional computations have to be programmed by the user in
address@hidden with matrices declared and initialized in
address@hidden An example is given in the example @file{lorhcl}
+provided with the Miniker installation files, following a method proposed
+by Stephane Blanco.
+
address@hidden Adjoint model and optimisation
address@hidden Adjoint model and optimisation with Miniker
+
+In the following a possible use of Miniker for optimisation is discussed.
+More precisely the use of adjoint and control laws in Miniker are presented.
+Optimisation isn't the only application of these tools, but it is the most
+common one. In that case the adjoint may be used to determine the gradient of a
+functional to perturbations in the control laws, and an optimisation process
+can use this
+information to search for the optimum.
+Another application of the adjoint is to compute the sensitivity of a
+cost function to parameters (the ones declared in the @code{free_parameters:}'
list.
+Note that the cost function can be sensitive to probe's variables, even if
these are
+uncoupled with standard variables in the forward calculations; this is the case
+when minimizing a quadratic distance function between probes (from the model)
+and the corresponding measurements.
+
+The code is close transcription of the mathematical calculus described
address@hidden @url{http://www.lmd.jussieu.fr/ZOOM/doc/Adjoint.pdf} . It
essentialy reverse time and
+transpose the four Jacobian matrices: states and transfers are saved in array
dimensionned
+with @code{maxstep} Fortran parameter.
address@hidden
+* Overview of optimisation with Miniker::
+* Control laws::
+* Cost function coding and adjoint modeling::
+* Sensitivity of cost function to parameters::
address@hidden menu
+
address@hidden Overview of optimisation with Miniker
address@hidden Overview of optimisation with Miniker
+
address@hidden adjoint
address@hidden optimisation
+
+In the proposed method, Miniker is run twice, one time forward and then
+backward to determine the trajectory and the adjoint model. After that the
+control laws are modified by a program external to Miniker. The same steps
+are repeated until convergence. More pecisely,
+
address@hidden @strong
address@hidden forward
+The command law @math{h(t)} is given (by an explicit law or taken from a file).
+The trajectory is computed in a classical way, with the additionnal computation
+of the functional to be optimised, @math{J}, prescribed with specific
address@hidden macros. The states, transfers and control laws are stored.
address@hidden backward
+The adjoint variable is computed from the last time @math{T} backward. The
+time increment is re-read as it could have changed during the forward
+simulation. The system is solved by using the same technics as in the forward
+simulation, but with a negative time step.
address@hidden external phase
+Now the command should be corrected. This step isn't covered here, but, for
+example, minuit the optimisation tool from the CERN could be used.
+In order to ease such a use of Miniker, the principal program has to be
+compiled as a subroutine to be driven by an external program
+(@pxref{Calling the model code}).
address@hidden table
+
+The functionnal @math{J} to be optimised is defined as
+
address@hidden
+$$
+J = \psi[\eta(T),\varphi(T) ,h(T)] + \int_0 ^T
{l[\eta(\tau),\varphi(\tau),h(\tau)]}\, d\tau
+$$
address@hidden tex
address@hidden @math{J = psi(eta(T),phi(T),h(T)) + int_0^T
l(eta(tau),phi(tau),h(tau)) d tau}
+
address@hidden final cost
address@hidden integrand cost
+
+Where @math{\psi} is the final cost function, @math{l} is the integrand
+cost function and @math{h} represents the control laws variations.
+
+The general use of the adjoint model of a system is the determination of the
+gradient of this @math{J} functional to be optimised, with respect to
perturbations
+of the original conditions of the reference trajectory, that is, along its
address@hidden Tangent Linear System, i.e. the TLS circulating along a
trajectory.
+See the explanation in the document
address@hidden://www.lmd.jussieu.fr/Zoom/doc/Adjoint.pdf} (in French).}.
+
address@hidden Control laws
address@hidden Control laws
+
address@hidden zcommand
address@hidden command law
+
+Each control law is associated with one cell or transfer equation, meaning
that a command
+associated with an equation does not appear in any other equation.
+It is still possible
+to add commands acting anywhere by defining a transfer equal to that command.
+
+
+The control laws associated with states are in the @code{ux_com(.)} array,
+control laws associated with transfers are in the @code{uy_com(.)} array.
+The control laws may be prescribed even when there is no adjoint computed,
+nor any optimisation, and they are used during simulation, in which case they
will
+act as external sources. To enable
+the use of commands, the logical flag @code{Zcommand} should be @code{.true.}.
+
address@hidden @file{uxcom.data}
address@hidden @file{uycom.data}
+
+The command can be given either as:
address@hidden
address@hidden a table of numerical
+values in the files @file{uxcom.data} and @file{uycom.data}.
address@hidden a function
address@hidden zlaw
address@hidden @file{zcmd_law}
address@hidden @file{zcmd_law.inc}
+of the problem variables. To turn that feature on the logical flag
address@hidden should be set to @code{.true.} in @file{zinit}. The sequence
address@hidden should hold
+the code filling the @code{ux_com(.)} and @code{uy_com(.)} arrays, as the code
+from that sequence is used whenever the control laws are needed.
+In that case the files @file{uxcom.data} and @file{uycom.data} will
+be filled by the command values generated by the function along the trajectory.
address@hidden enumerate
+
+For example in the Lotka-Volterra model, the parameter @code{apar} could
+be a control variable.
+In that case, @code{apar} would be defined as the variable @code{ux_com(1)},
+and either entered as a law
+in the sequence @file{zcmd_law} , either written in the file @file{uxcom.data}
+step by step. In that case, there must be a perfect corresponodence between
time
+of the commands and time of the run.
+
address@hidden Cost function coding and adjoint modeling
address@hidden Cost function coding and adjoint modeling
+
address@hidden zback
address@hidden cout_Psi
address@hidden cout_l
+
+First of all the flag @code{zback} should be set to @code{.true.} in order to
+allow adjoint model computation:
+
address@hidden
+Zback=.true.;
address@hidden example
+
+The two functions @code{cout_Psi} corresponding with the final cost and
address@hidden corresponding with the integrand cost are set up with the
address@hidden macros.
+
address@hidden f_set cout_Psi = f(eta(.),ff(.),ux_com(.),uy_com(.))
+This macro defines the final cost function.
address@hidden is a fortran
+expression which may be function of cell state variables,
address@hidden(1)address@hidden@samp{eta(np)}, transfers
address@hidden(1)address@hidden@samp{ff(mp)},
+state control laws
address@hidden(1)address@hidden@samp{ux_com(np)}, and transfer control laws
address@hidden(1)address@hidden@samp{uy_com(mp)}.
address@hidden defmac
+
address@hidden f_set cout_l = f(eta(.),ff(.),ux_com(.),uy_com(.))
+This macro defines the integrand cost function.
address@hidden is a fortran
+expression which may be function of cell state variables,
address@hidden(1)address@hidden@samp{eta(np)}, transfers
address@hidden(1)address@hidden@samp{ff(mp)},
+state control laws
address@hidden(1)address@hidden@samp{ux_com(np)}, and transfer control laws
address@hidden(1)address@hidden@samp{uy_com(mp)}.
address@hidden defmac
+
+For example, the following code sets a cost function for the masselottes
+model:
+
address@hidden
+! Initialisation
+ F_set cout_Psi = eta_move(inode:1);
+!and f_set cout_l integrand in the functionnal
+ F_set cout_l = 0.;
address@hidden example
+
+In that example the functional is reduced to the final value
+of the first state component.
+Here, the adjoint vector will correspond to the final sensitivity
+(at @math{t=0}) of
+that component (here the first masselotte position) to a perturbation in
+all initial address@hidden detailed explanation of the adjoint model,
+see the document in
address@hidden://www.lmd.jussieu.fr/@/ZOOM/doc/Adjoint.pdf,pdf}
+or @uref{http://www.lmd.jussieu.fr/@/ZOOM/doc/Adjoint.pdf,.ps.gz}}.
+
address@hidden In the code, the variables @code{v_adj(.)} and @code{w_adj(.)}
address@hidden are respectively adjoint to @code{eta(.)} and @code{ff(.)}. They
are written in the
address@hidden two files: @file{vadj.data} and @file{wadj.data}.
+The following variables are set during the backward phase, and output
+in the associated files:
+
+
address@hidden address@hidden(.)}} address@hidden {time increment, hamiltonian,
cost function increment}
address@hidden var @tab file @tab explanation
address@hidden @item @code{} @tab @file{.data} @tab @tab
address@hidden @code{v_adj(.)} @tab @file{vadj.data} @tab adjoint to
@code{eta(.)}
address@hidden @code{w_adj(.)} @tab @file{wadj.data} @tab adjoint to
@code{ff(.)}
address@hidden @code{wadj(mp+.)} @tab @file{gradmuj.data} @tab adjoint to
@code{ff(mp+.)}
address@hidden @code{graduej(.)} @tab @file{gradxj.data} @tab adjoint to
@code{ux_com(.)}
address@hidden @code{gradufj(.)} @tab @file{gradyj.data} @tab adjoint to
@code{uy_com(.)}
address@hidden @code{hamilton} @tab @file{hamilton.data} @tab time increment,
hamiltonian, cost function increment
address@hidden multitable
+
address@hidden Sensitivity of cost function to parameters
address@hidden Sensitivity of cost function to parameters
+
address@hidden @file{gradpj.data}
+
+The sensitivity of the cost function to all the parameters given as
+arguments of @code{Free_parameters} is computed. For the
+predator model the sensitivity of a cost function consisting in
+the integral of the predator population with respect with
address@hidden an @code{cpar} is obtained with a number of parameters
+set to 2 in @file{dimetaphi}:
+
address@hidden
+parameter (lp=2);
address@hidden example
+
+And the cost function and @code{Free_parameters} list in @file{zinit}:
+
address@hidden
+f_set cout_Psi = eta(2);
+f_set cout_l = eta(2);
+Free_parameters: apar,cpar;
address@hidden example
+
address@hidden and @code{cpar} also have to be given a value.
+The result is output in @file{gradpj.data}.
+
address@hidden Kalman filter
address@hidden Kalman filter
+
address@hidden Kalman filter
address@hidden variance-covariance matrices, general
address@hidden observations, general
+
+The Kalman filter allows for data assimilation along the model run. In
+that case it is assumed that there is a real-world model with stochastic
+perturbations on the states, and that noisy observations are available.
+The situation implemented in Miniker corresponds to a continuous
+stochastic perturbation on the state, and discrete noisy observations.
+In the @acronym{TEF} this leads to:
+
address@hidden
+$$\eqalign{
+\partial_t \eta (t) &= g(\eta(t),\varphi(t)) + W(t) \mu\cr
+\varphi(t) &= f(\eta(t),\varphi(t))\cr
+\omega(t) &= h ( \eta(t) , \varphi(t)) + \nu\cr
+}$$
address@hidden tex
+
address@hidden @math{d eta(t)/d t = g(eta(t),phi(t)) + W(t) address@hidden
+phi(i) = f(eta(t),phi(t))@*
+omega(t) = h(eta(t), phi(t)) + nu }
+
+
address@hidden FIXME partout omega
address@hidden (notice that in this paragraph, $\omega$ stands for the probe
vector $\mu$ elsewhere,
address@hidden and $\mu$ is here a noise source.
+
+The observations @math{\omega} are available at discrete time steps
@math{t=s_i}. The
+stochastic perturbation on state, @math{\mu} is characterized by a
+variance-covariance matrix @math{Q} and the noise on the observation,
address@hidden has a variance-covariance matrix @math{R}. @math{W} relates
states
+with stochastic perturbations. At each time step the Kalman filter recomputes
+an estimation of the state and the variance-covariance matrix of the state.
+
+In the following we use the example of a linear model with perturbation
+on state and observation of state. The model has 3 states and 3 corresponding
+transfers (equal to the states), but the error on the state is of dimension
+2. The 3 states are observed. The corresponding equations read:
+
address@hidden
+$$\left\{\eqalign{
+\partial_t \eta_1 &= a_{11} \eta_1 + a_{12} \varphi_2 + a_{13} \varphi_3 +
W_{11} \mu_1 + W_{12} \mu_2\cr
+\partial_t \eta_2 &= a_{21} \varphi_1 + a_{22} \eta_2 + a_{23} \varphi_3 +
W_{21} \mu_1 + W_{22} \mu_2\cr
+\partial_t \eta_3 &= a_{31} \varphi_1 + a_{32} \varphi_2 + a_{33} \eta_3 +
W_{31} \mu_1 + W_{32} \mu_2
+}\right.$$
+$$\left\{\eqalign{
+\varphi _1 &= \eta _1\cr
+\varphi _2 &= \eta _2\cr
+\varphi _3 &= \eta _3
+}\right.$$
+$$\left\{\eqalign{
+\omega _1 &= \varphi _1 + \nu_1\cr
+\omega _2 &= \eta _2 + \nu_2 \cr
+\omega _3 &= \eta _3 + \nu_3
+}\right.$$
address@hidden tex
+
+
+Cells:@*
address@hidden @math{d eta_1/dt = a_11 eta_1 + a_12 phi_2 + a_13 phi_3 + W_11
mu_1 + W_12 address@hidden
+d eta_2/dt = a_21 phi_1 + a_22 eta_2 + a_23 phi_3 + W_21 mu_1 + W_22
address@hidden
+d eta_3/dt = a_31 phi_1 + a_32 phi_2 + a_33 eta_3 + W_31 mu_1 + W_32 mu_2}
+
+Transfers:@*
address@hidden @math{phi_1 = address@hidden
+phi_2 = address@hidden
+phi_3 = eta_3}
+
+Observations:@*
address@hidden @math{omega_1 = phi_1 + address@hidden
+omega_2 = eta_2 + address@hidden
+omega_3 = eta_3 + nu_3}
+
+
address@hidden
+* Coding the Kalman filter::
+* Kalman filter run and output::
+* Executing code after the analysis::
address@hidden menu
+
address@hidden Coding the Kalman filter
address@hidden Coding the Kalman filter
+
address@hidden zkalman
+
+First of all the Kalman filter code should be activated. The observations
+code is also required (@pxref{Observations}).
+If cmz is used the code
+should be selected with the select flag kalman
+in the @file{selseq.kumac}:
+
address@hidden
+sel kalman
address@hidden example
+
+With make the @code{kalman} variable should be set to 1:
+
address@hidden
+kalman = 1
address@hidden example
+
+The kalman code is actually used by setting the flag
address@hidden to @code{.true.}, for example in the @file{zinit}:
+
address@hidden
+zkalman = .True.;
address@hidden example
+
address@hidden This will set the @code{zobs} and @code{zdata} flags to
@code{.true.}
address@hidden (@pxref{Observations and data}).
+
+With the Kalman filter the dimension of estimated states, of the error
+on the state and of the
+observation, the @math{W} matrix, the observation function,
+the initial
+variance-covariance matrices on the state and the variance-covariance matrices
+of errors have to be given.
+
address@hidden
+* Kalman filter vectors dimensions::
+* Error and observation matrices::
address@hidden menu
+
address@hidden Kalman filter vectors dimensions
address@hidden Kalman filter vectors dimensions
+
address@hidden error vector dimension
address@hidden @file{dimetaphi}, Kalman filter
+
+These dimensions should be set in the @file{zinit} sequence.
+The size of the estimated states is given by the parameter @code{nkp}.
+You can set this to @code{np} if all the states are estimated, but in case
+there are some deterministic state variables, @code{nkp} may be less than
address@hidden In that case the first @code{nkp} elements of @code{eta(.)}
+will be estimated using the Kalman filter.
+
+The error on state dimension is associated with the parameter @code{nerrp}
+and the size of the observations vector is @code{mobs}
+(@pxref{Observations}). In our example the dimensions are set with:
+
address@hidden
+parameter (nkp=np);
+parameter (mobs=3);
+parameter (nerrp=2);
address@hidden example
+
+All the states are estimated,
+there are 3 observation functions and the error on the state vector is of
+dimension 2.
+
+If the sizes are set explicitely, the parameters should be set in
address@hidden
+
address@hidden Error and observation matrices
address@hidden Error and observation matrices
+
address@hidden variance-covariance matrices
address@hidden observations
address@hidden @file{zinit}, Kalman filter
+
address@hidden Initial variance-covariance matrix on the state
+
address@hidden initial variance-covariance on states
address@hidden covfor(.,.)
+
+The variance-covariance on the state matrix is @code{covfor(.,.)}. The initial
+values have to be given for this matrix, as in our example:
+
address@hidden
+covfor(1,1) = 1000.; covfor(1,2) = 10.; covfor(1,3) = 10.;
+covfor(2,1) = 10.; covfor(2,2) = 5000.; covfor(2,3) = 5.;
+covfor(3,1) = 10.; covfor(3,2) = 5.; covfor(3,3) = 2000.;
address@hidden example
+
+This matrix is updated by the filter at each time step because the states
+are pertubated by some noise, and when assimilation takes place as new
+information reduce the error.
+
address@hidden Observations and error on state matrix
+
address@hidden variance-covariance matrix on state
address@hidden mereta(.,.)
+
+The matrix that relates errors on states vector components to states,
+corresponding with @math{W} is @code{mereta(.,.)}. In our example it is
+set by:
+
address@hidden
+mereta(1,1) = 1.; mereta(1,2) = 0.;
+mereta(2,1) = 0.; mereta(2,2) = 1.;
+mereta(3,1) = 0.5; mereta(3,2) = 0.5;
address@hidden example
+
+The observation functions are set by a @code{f_set} macro with
address@hidden(.)} as described in @ref{Observations}.
+In our example the observation functions are set by:
+
address@hidden
+f_set Obs_tef(1) = ff(1) ;
+f_set Obs_tef(2) = eta(2);
+f_set Obs_tef(3) = eta(3);
address@hidden example
+
address@hidden Error variance-covariance matrices
+
address@hidden variance-covariance error
address@hidden covobs(.,.)
+
+The variance-covariance matrix on observation noise is @code{covobs(.,.)}
+set, in our example, by:
+
address@hidden
+covobs(1,1) = 0.3; covobs(1,2) = 0.; covobs(1,3) = 0.;
+covobs(2,1) = 0.; covobs(2,2) = 0.1; covobs(2,3) = 0.;
+covobs(3,1) = 0.; covobs(3,2) = 0.; covobs(3,3) = 0.2;
address@hidden example
+
address@hidden coveta(.,.)
+The variance-covariance matrix on state noise is @code{coveta(.,.)}
+set, in our example, by:
+
address@hidden
+coveta(1,1) = 0.2; coveta(1,2) = 0.001;
+coveta(2,1) = 0.001; coveta(2,2) = 0.1;
address@hidden example
+
+These matrices are not changed during the run of the model as part
+of the filtering process. They may be changed by the user in @file{zsteer}.
+
address@hidden Kalman filter run and output
address@hidden Kalman filter run and output
+
address@hidden
+* Feeding the observations::
+* Kalman filter results::
address@hidden menu
+
address@hidden Feeding the observations
address@hidden Feeding the observations to the model
+
address@hidden vobs(.)
address@hidden zgetobs
address@hidden @file{zsteer}, Kalman filter
+
+The observations must be made available to the model during the run. These
+observations are set in the @code{vobs(.)} array, and the assimilation
+(also called the analysis step of the filter) takes
+place if the logical variable @code{zgetobs} is @code{.true.}
+(@pxref{Data}).
+
+These steps are
+typically performed in the @file{zsteer} sequence. In this sequence there
should
+be some code such that when there are data ready to
+be assimilated, @code{zgetobs} is set to @code{.true.} and the data is
+stored in @code{vobs(.)}, ready for the next step processing.
+
address@hidden Kalman filter results
address@hidden Kalman filter results
+
address@hidden results, Kalman filter
address@hidden Kalman filter results
address@hidden output, Kalman filter
address@hidden Kalman filter output
address@hidden @file{data.data}
+
+The estimated states and transfers are still in the same @samp{.data} files,
address@hidden and @file{tr.data} and there is the additional file with
+observations, called @file{obs.data} (@pxref{Observations}).
+Each time @code{zgetobs} is @code{.true.} the data, and the optimally
+weighted innovations are output
+in the file associated with data, @file{data.data} (@pxref{Data}).
+
address@hidden Executing code after the analysis
address@hidden Executing code after the analysis
+
+The analysis takes place before the time step advance when @code{zgetobs}
+is @code{.true.}. It may be usefull to add some code after the analysis
+and before the time step advance. For example the analysis may lead to
+absurd values for some states or parameters, it could be usefull to correct
+them in that case. The sequence included after the analysis is called
address@hidden At this point, in addition to the usual variables
+the following variables could be usefull:
+
address@hidden @code
address@hidden etafor(.)
+The state before the analysis.
address@hidden kgain(.)
+The Kalman gain.
address@hidden innobs(.)
+The innovation vector (observations coherent with the states minus data
+values).
address@hidden covana(.,.)
+The variance-covariance error matrix after the analysis.
address@hidden vtable
+
+At each time step the derivative of the observation function with respect
+to transfer and cells variables are recomputed. The elimination of
+transfers is also performed to get the partial derivative of the observation
+function of the equivalent model, with states only, with respect to the
+states. In other words, the Kalman filter does not follow the TEF formalism,
because
+the advance of the var-covar matrix could not yet be set in the TEF form.
address@hidden There is a corresponding additional matrix:
+
address@hidden @code
address@hidden @item obetad(.,.)
address@hidden derivative of observation function with respect to transfers.
address@hidden @item obphid(.,.)
address@hidden derivative of observation function with respect to cell
variables.
address@hidden obspha(.,.)
+derivative of observation function in state space with respect to
+cell variables.
address@hidden vtable
+
+
address@hidden Feedback gain
address@hidden Feedback gain
+
+
address@hidden Borel sweep
address@hidden Feedback gain
+
+The feedback dynamic gain associated with a feedback loop
+can be expressed as the inverse Borel
+transform of the coefficient of the reduced scalar
+coupling matrix, @math{g(\tau)},
+associated with a transfer.
+A Borel sweep provides this @math{g(\tau)}. Therefore it is
+an interesting tool for the characterization of the feedback address@hidden
+More generally, the Borel sweep allows
+the numerical study of the dependency in @math{\tau} of the Borel transform
+of various coefficients in the system coupling matrix.}.
+
+As explained in the
+ZOOM web page document
address@hidden://www.lmd.jussieu.fr/@/ZOOM/doc/@/Feedback_Gain.pdf},
+this allows for the calculation of the
+dynamic gain and factor of any feedback that goes through a unique
+transfer variable. An example of the conclusions that can be drawn from such
+an analysis is provided in the same document.
+
+
+
+For linear systems -- whose GTLS are autonomous along the whole trajectory --
+the @math{\tau} function of the
+feedback gain is independent of the position on the system trajectory.
+But in general it is dependant, and one can analyse the function
address@hidden(\tau;t)} defined on a segment @math{t} of the trajectory.
+
+The document introducing the TEF-ZOOM technique explains how a Crank-Nicolson
+scheme for the time discretisation
+symbolically gives the solution of the Borel transform of the system. One can
+identify the @code{dt} variable with the Borel @math{\tau} within a
+factor @math{2}. Hence, to numerically study the @math{\tau} dependency of
+the transform of various coefficients in the system coupling matrix at one
+point in time, one can calculate the Borel transform of the TLS solutions
+by making a time-step sweep.
+
+The function @math{g(\tau;t)} is simply output for the feedback gain
+attached to a unique @code{ff(k)} transfer variable.
+All the relevant informations should be entered in the @file{zinit} sequence.
+
address@hidden
+* Specifying the Borel sweep::
+* Borel sweep results::
address@hidden menu
+
address@hidden Specifying the Borel sweep
address@hidden Specifying the Borel sweep
+
address@hidden ZBorel
+
+First of all the logical flag @code{ZBorel} should be raised:
+
address@hidden
+ZBorel=.true.;
address@hidden example
+
address@hidden index_ff_gain
+The index of the studied transfer is given in the @code{index_ff_gain}
+variable
address@hidden
+index_ff_gain=7;
address@hidden example
+
+At each time step a Borel sweep may be performed. The time steps of interest
+are
+specified with three variables, one for the first step, one for the last step
+and one for the number of steps between two Borel sweeps:
+
address@hidden @code
address@hidden istep_B_deb
+First time step for the Borel sweep.
address@hidden istep_B_fin
+Last time step for the Borel sweep.
address@hidden istep_B_inc
+Number of time steps between Borel sweeps.
address@hidden vtable
+
+In the following examples Borel sweeps are performed from the
+time step 1000 up to the time step 1200, with a sweep at each time step:
address@hidden
+istep_B_deb=1000;
+istep_B_fin=1200;
+istep_B_inc=1;
address@hidden example
+
+
+For each Borel sweep, the range of the @math{\tau} variable should be
+set. As this is a multiplicative variable the initial value, a multiplicative
+factor and the number of values are to be given.
+
address@hidden @code
address@hidden tau_B_ini
+Initial value for @math{\tau}.
address@hidden tau_B_mult
+Multiplicative factor for sweep in @math{tau}.
address@hidden itau_max
+Number of @math{\tau} values.
address@hidden vtable
+
+For example, in the following, at each time step, the Borel
+transform will be computed for @math{\tau} values
+starting at @math{0.2} and then multiplied a hundred times by
@math{\sqrt{\sqrt{2}}}
+
address@hidden
+tau_B_ini=0.2;
+tau_B_mult=sqrt(sqrt(2.));
+itau_max=100;
address@hidden example
+
+When the initial value of @math{\tau} is set to a negative value
+(@i{i.e.} @code{tau_B_ini=-0.2;}),
+the Borel sweep will first be applied with @code{itau_max} negative values
+for @code{-0.2}, @code{tau_B_mult*(-0.2)},..., then for the zero value,
+and finally for the symetric positive values, resulting in @code{2*itau_max+1}
+values for @math{\tau}.
+
+The whole example reads
+
address@hidden
+! -------------------
+! Feedback gain
+! Borel
+! -------------------
+ZBorel=.true.;
+if ZBorel
+< istep_B_deb=1000;
+ istep_B_fin=1200;
+ istep_B_inc=1;
+;
+ index_ff_gain=7;
+ tau_B_ini=0.2;
+ tau_B_mult=sqrt(sqrt(2.));
+ itau_max=100;
+ z_pr/Borel/:tau_B_mult,tau_B_ini*(tau_B_mult)**itau_max;
+>;
address@hidden example
+
address@hidden zborel for
+
+Instead of using the index of the transfer in @code{index_ff_gain} it is
+possible to specify the name of the address@hidden , whenever
address@hidden the symbolic model description is used (@pxref{Symbolic model
description}).
+In that case the transfer is specified
+by the @code{zborel for} macro. For example if the transfer selected for the
+feedback gain computation is @var{b_transfer}, it can be selected
+with:
+
address@hidden
+zborel for: @var{b_transfer};
address@hidden example
+
address@hidden Borel sweep results
address@hidden Borel sweep results
+
address@hidden Borel sweep results
address@hidden results, Borel sweep
address@hidden Borel sweep graphics
address@hidden graphics, Borel sweep
+
+The file @file{tau_Borel.data} gives the @math{\tau} values of the @var{tau}
sweep,
+and the file @file{gains.data} records the feedback gain function values of
address@hidden(\tau)}, with
+one line for each sweep along the trajectory. In the 1.01 version, a new
+feature is also provided giving the poles and residuals of the Borel
+transform in the file @file{vpgains.data}. Consult the subroutine
address@hidden
+for (not definitive) output description.
+
+One can easily obtain the surface contours of @math{g(t,\tau)} using
+the Fortran program provided as @file{gains.f} and its compilation shell
address@hidden,
+that builds 2D histograms for PAW, in which one uses the
address@hidden provided kumac.
+
address@hidden Stability of fastest modes
address@hidden Stability analysis of fastest modes
+
address@hidden SVD
address@hidden Singular Value Decomposition
address@hidden state matrix
address@hidden @file{sltc.exe}
+
+The preceding analyses are done along with a simulation. One has also the
+possibility of using in a more classical fashion the state advance matrix
address@hidden, after the end of the simulation. Code to perform the
address@hidden, Singular Value Decomposition} of the state matrix @math{A_{st}}
+and also of @math{A_{st} + A_{st}^\dagger} is provided with Miniker.
+The singular elements of these two matrices correspond to the most
+rapid modes of instability of the perturbed system.
+
+The Singular value decomposition of a matrix is noted
+
address@hidden
+$$
+ U w V^\dagger
+$$
address@hidden tex
+
address@hidden @math{U w V^t}
+
+
+An executable file, @file{sltc.exe} is generated and running this file will
+produce the corresponding results.
+
address@hidden
+* SVD with cmz::
+* SVD with make::
+* SVD run and output::
address@hidden menu
+
address@hidden SVD with cmz
address@hidden Singular Value Decomposition with cmz
+
address@hidden @command{smod}
+
+The cmz macro @code{smod SLTC} prepares a main program
+(@file{circul} of +PATCH SLTC), provided as a base for user's own analysis,
+in the directory @file{sltc/}.
+
address@hidden SVD with make
address@hidden Singular Value Decomposition with make
+
address@hidden @file{Makefile.sltc}
+
+To compile the singular value decomposition executable with @command{make} you
+can do
address@hidden
+make sltc.exe
address@hidden example
+
+If you want to have a separate directory for the SVD, you should copy
+the sequence @file{dimetaphi.inc} (or make a link to that file) to the
+directory. You should also copy the file @file{Makefile.sltc} from the
address@hidden/} directory in this directory, rename it @file{Makefile}
+and set the Miniker directory path in the
address@hidden variable. For
+example, if the Miniker directory is in @file{/u/src/mini_ker}:
+
address@hidden
+miniker_dir = /u/src/mini_ker
address@hidden example
+
address@hidden SVD run and output
address@hidden Singular Value Decomposition run and output
+
address@hidden SVD run
address@hidden run, SVD
address@hidden SVD output
address@hidden output, SVD
address@hidden @file{sltc.exe}
address@hidden @file{title.tex}, SVD
address@hidden @file{aspha.data}, SVD
+
+As it is, the @file{sltc.exe} executable generated by the compilation
+determines the SVD. This program requires @file{title.tex} (@pxref{Title
file}) to
+transmit a title for output and graphics, and @file{aspha.data}
+(@pxref{Simulation and output,,Running a simulation and using the output})
+to access the
+state matrix. To get access to these files (in case they are not in the current
+directory) it is possible to make a link to
+the corresponding files in the model directory. Once it is done
+the program may be run:
+
address@hidden
+./sltc.exe
address@hidden example
+
+The files @file{u.data}, @file{w.data}, and @file{v.data} holds the singular
elements
+for @math{A_{st}} (@math{U}, @math{w} and @math{V}),
+and @file{us.data}, @file{ws.data}, and @file{vs.data}
+holds the singular elements of @math{A_{st} + A_{st}^\dagger}.
+The corresponding macros @samp{.kumac} for address@hidden in
+the research paper about SLTC (Al1 2003) available on request.}
+are also generated.
+
address@hidden Generalized TLS
address@hidden Generalized linear tangent system analysis
+
address@hidden Generalized linear tangent system
address@hidden GTLS
address@hidden propagator
address@hidden Lyapunov exponents
address@hidden @file{sltcirc.exe}
+
+The state matrix @math{A_{st}} may also be used to compute the
+GTLS propagator (or state transition matrix applied to perturbation), after
the simulation.
+The algorithm is a finite product of
+5th order development of
address@hidden(t+\delta t,t)=\exp{A_{st} \delta t}}.
+Numerous element of analysis are given, in particular the determination
+of the Lyapunov exponents of the system.
+
+An executable file, @file{sltcirc.exe} is generated and running this file will
+produce the corresponding results.
+
address@hidden
+* GTLS with cmz::
+* GTLS with make::
+* GTLS run and output::
address@hidden menu
+
address@hidden GTLS with cmz
address@hidden Generalized tangent linear system with cmz
+
address@hidden @command{smod}
+
+The cmz macro @code{smod SLTCIRC} prepares a main program
+(@file{circule} of +PATCH SLTCIRC), in the directory @file{sltcirc/}.
+
address@hidden GTLS with make
address@hidden Generalized tangent linear system with make
+
address@hidden @file{Makefile.sltcirc}
+
+To compile the GTLS analysis executable with @command{make} you
+can do
address@hidden
+make sltcirc.exe
address@hidden example
+
+If you want to have a separate directory for the GTLS analysis, you should
copy
+the sequence @file{dimetaphi.inc} (or make a link to that file) to the
+directory. You should also copy the file @file{Makefile.sltcirc} from the
address@hidden/} directory in this directory and rename it @file{Makefile}
+and set the Miniker directory path in the @code{miniker_dir} variable.
+
address@hidden GTLS run and output
address@hidden Generalized tangent linear system analysis run and output
+
address@hidden GTLS run
address@hidden run, GTLS
address@hidden GTLS output
address@hidden output, GTLS
address@hidden @file{sltcirc.exe}
address@hidden @file{title.tex}, GTLS
address@hidden @file{dres.data}, GTLS
address@hidden @file{aspha.data}, GTLS
+
+The @file{sltcirc.exe} executable generated by the compilation
+computes the elements of analysis of the system. This program requires
address@hidden to
+transmit a title for output and graphics (@pxref{Title file}),
address@hidden to access the
+state matrix and @file{dres.data}, because time-step can be changed along the
+simulation
+(@pxref{Simulation and output,,Running a simulation and using the output})
address@hidden our research texts about propagator analyses in
+SLTC, and ``les Gains sur champs (Al1 2003-2004)''}. To get access to these
files
+(in case they are not in the current
+directory) it is possible to make a link to
+the corresponding files in the model directory. Once it is done
+the program may be run:
+
address@hidden
+./sltcirc.exe
address@hidden example
+
+The following table gives the correspondence between variable name,
+result file and ntuple number, with a short explanation:
+
address@hidden address@hidden(.,.)}} address@hidden {ntuple} {eigen factors of
@math{w} in the SVD of @math{\Phi}}
address@hidden var @tab file @tab ntuple @tab explanation
address@hidden @code{p(.,.)} @tab @file{phit.data} @tab 55 @tab propagator from
0 to @math{t}, @math{\Phi(t,0)}
address@hidden @code{up(.,.)} @tab @file{uphit.data} @tab 50 @tab Left singular
vectors @math{U} in the SVD of @math{\Phi}
address@hidden @code{wp(.)} @tab @file{wphit.data} @tab 51 @tab singulat values
@math{w} in the SVD of @math{\Phi}
address@hidden @code{vp(.,.)} @tab @file{vphit.data} @tab 52 @tab Right
Singular Vectors @math{V} in the SVD of @math{\Phi}
address@hidden @code{wr(.)} @tab @file{wr.data} @tab 53 @tab real part of
eigen values of @math{\Phi(t,0)}
address@hidden @code{wi(.)} @tab @file{wi.data} @tab 54 @tab imaginary part of
eigen values of @math{\Phi(t,0)}
address@hidden @code{lwp(.)} @tab @file{lwphit.data} @tab 67 @tab Lyapunov
exponents
address@hidden @item @code{lwr(.,.)} @tab @file{lwr.data} @tab 68 @tab
address@hidden @item @code{lwi(.,.)} @tab @file{lwi.data} @tab 69 @tab
address@hidden @item @code{} @tab @file{.data} @tab @tab
address@hidden multitable
+
+
address@hidden Advanced use of Miniker with make
address@hidden Advanced use of Miniker with make
+
address@hidden
+* Make variables::
+* Rules::
+* Linking rule::
address@hidden menu
+
address@hidden Make variables
address@hidden Make variables
+
address@hidden @file{Makefile.miniker}
+
+The @file{Makefile.miniker} Makefile provided in the
+distribution should be included as it defines a lot of important
+variables and rules.
+
+The following make variables can be set by the user:
+
address@hidden @code
address@hidden miniker_dir
+that variable should hold the Miniker sources directory. If you installed
+Miniker that variable should be set to @file{$(includedir)/mini_ker}.
+If you use the sources right from the sources directory it should be set to
+the sources package directory.
address@hidden MTNDIRS
+This variable can hold a @samp{:} delimited list of directories that will
+be searched for mortran include files.
address@hidden CMFDIRS
+This variable can hold a @samp{:} delimited list of directories that will
+be searched for cmz directive include files.
address@hidden SEL
+This variable holds a @samp{,} delimited list of select flags, for example
address@hidden, @code{grid1d}, @code{debug}.
address@hidden LDADD
+This variable can be used to add libraries flags and files. It is used in
+the default linking command/rule.
address@hidden miniker_user_objects
+This variable should hold a space separated list of additional object files
+to be linked with the model and helper object files.
address@hidden CAR2TXTFLAGS
+cmz directives preprocessor flag.
address@hidden kalman
+This variable should be set to 1 if you want to use the kalman filter
+(@pxref{Kalman filter}).
address@hidden double
+This variable should be set to 1 if you want to have a double precision
+code (@pxref{Double precision}).
address@hidden table
+
+The following variables are allready set and may be used
+(some are set by ./configure see @ref{Configuration}):
+
address@hidden @code
address@hidden miniker_principal_objects
+The list of object files needed for the model build, together with some
+helper object files often used but not strictly required for the linking.
address@hidden DEPDIR
+The name of a hidden directory containing the dependencies computed
+for the main mortran files.
address@hidden F77
address@hidden FC
address@hidden FFLAGS
address@hidden LDFLAGS
+Compiler and linker related variables set by ./configure.
address@hidden LIBS
+This variable should hold the link flags and files required to build
+Miniker, set by ./configure.
address@hidden CAR2TXT
address@hidden MORTRAN
address@hidden MTNFLAGS
address@hidden MTNDEPEND
+Preprocessor and preprocessor flags, set by ./configure.
address@hidden table
+
address@hidden Rules
address@hidden Rules
+
+The following rules are defined in the @file{Makefile.miniker} file.
address@hidden @code
address@hidden miniker-clean
+remove the fortran files generated from the mortran files. Remove
+the object files.
address@hidden miniker-mtn-clean
+remove the mortran files generated from the files with cmz directives.
address@hidden
+Various rules to preprocess files with cmz directives and mortran files and
+to compile fortran files.
address@hidden table
+
+If the user needs a mortran main file, he may take advantage of the rule
+used to compute the dependencies of a mortran file. If the file is called,
+say, @file{mtnfile.mtn} leading to @file{mtnfile.f}, the following include
+should lead to the automatic creation, updating and inclusion of a
+file describing the dependencies of @file{mtnfile.mtn} in the
address@hidden:
+
address@hidden
+include $(DEPDIR)/mtnfile.Pf
address@hidden example
+
address@hidden Linking rule
address@hidden Linking rule
+
+The rule used for the linking of the model file is not in the
address@hidden file but
+should be provided in the user @file{Makefile} for more flexibility.
+The default rule
+uses the variables @code{miniker_user_objects} for additional object files
+and @code{LDADD} for additionnal linking flags and files, those
+variables are there to be changed by the user.
+
+The object files required by the Miniker code are in the make variable
address@hidden, this variable is also used.
+The value of the variables @code{FC}
+for the Fortran compiler, @code{FFLAGS} for the Fortran compiler
+flags and @code{LDFLAGS} for the linker flags should be set to right
+values; @code{LIBS} should also be right and hold the link flags and link
+files required to compile the Miniker model. These variables are
+set by by @command{./configure} during configuration (@pxref{Configuration})
+and used in the default rule:
+
address@hidden
+$(model_file): $(miniker_user_objects) $(miniker_principal_objects)
+ $(FC) $(FFLAGS) $(LDFLAGS) $^ $(LDADD) $(LIBS) -o $@
address@hidden verbatim
+
+In case this isn't right it may be freely changed. You should certainly
+refer to the @ref{Top,,Top,make,GNU Make Manual} manual to understand what
+that rule exactly means and make your own.
+
+
address@hidden Concepts index
address@hidden Concepts index
+
address@hidden cp
+
address@hidden Variables macros and functions index
address@hidden Variables, macros and functions index
+
address@hidden vr
+
address@hidden Installation
address@hidden Installation
+
address@hidden
+* Programming environments::
+* Common requisites::
+* Miniker with cmz::
+* Miniker with make::
address@hidden menu
+
address@hidden Programming environments
address@hidden Programming environments
address@hidden Programming environments
+
+Miniker is not a traditionnal software in that it isn't a library
+or an interpreter but rather a set of source and macro file that
+combines with the user model code and enable
+to build a binary program corresponding with the model. It
+requires a build environment with a preprocessor, a compiler
+and facilities that automate these steps.
+
+Two different environment are proposed. One use
address@hidden (@url{http://wwwcmz.web.cern.ch/@/wwwcmz/index.html}),
+while the other is based on @command{make}. Other libraries
+are needed, the CERN Program Library (cernlib) and lapack.
+
address@hidden Common requisites
address@hidden Common requisites
+
address@hidden cernlib
address@hidden lapack
+
+Whatever method is used a fortran 77 compiler is required. The compilers
+that have been used so far are g77, gfortran and the sun solaris compiler.
+
+When usng CMZ, the CERN Program Library, available at
address@hidden://wwwasd.web.cern.ch/@/wwwasd/cernlib/}, has to be installed.
+With make, internal source files copied from the cernlib may be used instead
+but then some examples won't be available, since they rely on some
+mathematical functions provided by the CERN library.
+On windows, in case you want to use the compiler from the GNU compiler
+collection with cygwin or MINGW/MSYS you can use the binaries provided at
address@hidden://zyao.home.cern.ch/@/zyao/cernlib.html}.
+On Mac OS X, the cernlib provided by fink (package @code{cernlib-devel})
+can be used.
+
+You should also have LAPACK, available at
@url{http://www.netlib.org/@/lapack/}.
+LAPACK can also be installed as part of the CERN Library or as part of
+the @uref{ATLAS,http://math-atlas.sourceforge.net/} implementation.
+On most linux distributions a lapack package is available.
+On Mac OS X, the ATLAS implementation provided by fink or the frameworks
+from Xcode can be used.
+
+
address@hidden Miniker with cmz
address@hidden Miniker with cmz
+
address@hidden @file{mini_ker.cmz}
address@hidden @file{selseq.kumac}
+
+First of all you have to get the cmz file @file{mini_ker.cmz} and put it
+in a directory. In that same directory you should create a directory for
+each of your models. In the model directory you should copy the file
address@hidden available with Miniker, and create your own cmz
+file for your model, called for example @file{mymodel.cmz}. You should also
+have installed the kumac macro files
+handling mortan compilation, the associated shell scripts and the mortran
+preprocessor.
+
address@hidden Miniker with make
address@hidden Miniker with make
+
address@hidden
+* Additional requirements::
+* Configuration::
+* Installation with make::
address@hidden menu
+
address@hidden Additional requirements
address@hidden Additional requirements for Miniker with make
+
address@hidden @command{mortran}, with make
address@hidden requirements, with make
+
+The package has been tested with GNU @command{make} and solaris
address@hidden
+
+Suitable preprocessors should also be installed. Two preprocessors are
+required, one that preprocess the cmz directives, and a mortran
+preprocessor. A cmz directives processor written in @command{perl},
+is distributed in the @command{car2txt} package available at
address@hidden://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}.
A @command{mortran}
+package with a command able to preprocess a mortran file given on
+the command line with a syntax similar with the @command{cpp} command line
+syntax is also required.
+Such a mortran is available at
@url{http://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}.
+
address@hidden All the @command{make} commands are not suitable, for example
the distribution
address@hidden doesn't work with solaris @command{make}. GNU @command{make}
works, however,
address@hidden and should be available on most platforms, often called
@command{gmake}.
+
+
address@hidden Configuration
address@hidden Configuration
+
address@hidden configuration of source
+
+The package is available at
@url{http://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}.
It is
+available as a compresssed tar archive. On UNIX, with GNU @command{tar} it
+may be unpacked using
+
address@hidden
+$ tar xzvf mini_ker-4.2.tar.gz
address@hidden example
+
+The detection of the compiler, the preprocessors (car2txt and mortran),
+and the libraries are performed by the configure script. This script
+sets the
+apropriate variables in makefiles. It can be run with:
+
address@hidden
+$ cd mini_ker-4.2
+$ ./configure
address@hidden example
+
+If the output of @command{./configure} doesn't show any error it means that
+all the components are here. It is possible to give @command{./configure}
+switches and also specify environment variables (see also
address@hidden/configure --help}):
+
address@hidden @code
address@hidden --disable-cernlib
+Use the internal cernlib source files, even if a cernlib is detected.
address@hidden --with-static-cernlib
+This command line switch forces a static linking with the cernlib (or a
dynamic linking
+if set to no).
address@hidden --with-cernlib
+This command line switch can be used to specify the cernlib location
+(if not detected or you want to use a specific cernlib).
address@hidden --with-blas
address@hidden --with-lapack
+With this command switch, you can specify the location of the blas and lapack
+libraries.
+
+For example, on mac OS X this can be used to specify the blas and lapack from
+the Apple frameworks:
+
address@hidden
+./configure \
+--with-blas=/System/Library/Frameworks/vecLib.framework/versions/A/vecLib \
+--with-lapack=/System/Library/Frameworks/vecLib.framework/versions/A/vecLib
address@hidden example
+
address@hidden F77
address@hidden FC
address@hidden FFLAGS
address@hidden LDFLAGS
+Classical compiler, compiler flags and linker flags.
address@hidden MORTRAN
+This environment variable holds the mortran preprocessor command
+(default is @command{mortran}).
address@hidden MTNFLAGS
+This environment variable holds command line arguments for the mortran
+preprocessor. It is empty in the default case.
address@hidden MTN
+This environment variable may be used to specify the mortran executable
+name and/or path, it should be used by the @command{mortran} commmand.
+(default is empty, which leads to a mortran executable called @command{mtn}).
address@hidden MTNDEPEND
+This environment variable may be used to specify the mortran dependencies
+checker executable. It should be used by the @command{mortran} commmand.
+(default is empty, which leads to a mortran dependencies checker
+called @command{mtndepend}).
address@hidden table
+
+After a proper configuration, if @command{make} is run then the example
+models should be build. You have to perform the configuration only once.
+
address@hidden Installation with make
address@hidden Installation with make
address@hidden installation with make
+
+Miniker can be installed by running
address@hidden
+make install
address@hidden example
+
+
+It should copy the sources
+and the @file{Makefile.miniker} file in
+a @file{mini_ker} directory in the @code{$(includedir)} directory, and
+copy the templates in @file{$(datadir)/mini_ker}. The default for
address@hidden(includedir)} is @file{/usr/local/include} and the default for
address@hidden(datadir)} is @file{/usr/local/share}, these defaults may be
+changed by @command{./configure} switches @samp{--prefix},
address@hidden and @samp{--datadir}. See @command{./configure --help}
+and the @file{INSTALL} file for more informations. The helper script
address@hidden should also be installed.
+
+
+
+The installation is not required to use comfortably Miniker. Indeed
+the only thing that changes with the sources and the @file{Makefile.miniker}
+directory location is the @code{miniker_dir} variable in a
+project @code{Makefile}.
+
+
address@hidden Cmz directives reference
address@hidden Cmz directives reference
+
+The cmz directives are described together with the other
+features of cmz in the cmz manual at
address@hidden://wwwcmz.web.cern.ch/wwwcmz/}, the important ones are
+nevertheless recalled here,
+especially for those that use make and don't need the whole
+features of cmz.
+
+After the description of the generic features, we turn
+to the cmz directive of interest.
+There are three kinds of cmz directives that are of use
+within Miniker: one kind
+that introduce files, the other for conditionnal compilation and
+the third for sequence inclusion.
+
+
address@hidden
+* Cmz directives general syntax::
+* Conditional expressions::
+* File introduction directives::
+* Conditional directives::
+* File inclusion directive::
+* The self directive::
address@hidden menu
+
address@hidden Cmz directives general syntax
address@hidden Cmz directives general syntax
+
+The cmz directives always begin with a @samp{+} in the first column,
+optionnaly followed by any number of @samp{_} that may be used for
+indentation, then the directive label, case insensitive, followed
+by the directive arguments separated by @samp{,}. The arguments
+are also case insensitive.
+Optional spaces may be around directive arguments.
+An optionnal @samp{.} ends the directive
+arguments and begin a comment, everything that follows that @samp{.} is
+ignored.
+
address@hidden Conditional expressions
address@hidden Conditional expressions
+
+A directive argument common to all the directives is the conditionnal
+expression. A conditionnal expression may be true or false, it is a
+combination of select flags. the select flags are combined with
+logical operators. A
+select flag itself is true if it was selected. A select flag @var{selflag}
+is selected by using the @code{sel @var{selflag}} instruction in cmz. It is
+selected by passing the @code{-D @var{selflag}} command line switch to
+the call of the cmz directives preprocessor when using make.
+
+
+A @samp{-} negates
+the expression that follows. Parenthesis @samp{(} and @samp{)} are used
+for the grouping of subexpressions. @samp{|} and @samp{,} are for the
+boolean or: an expression with a or is true
+if the expression on the left or the expression on the right of the or
+is true.
address@hidden&} is for the boolean and: an expression with an and is true if
+the expression on the left and the expression on the right are true.
+
+The grouping is left to right when there is no parenthesis, with or and
address@hidden&} having the same precedence. Therefore
+
address@hidden
+a&b|c @equiv{} (a&b)|c
+a|b&c @equiv{} (a|b)&c
+a|b&c is not a|(b&c)
+a&b|c is not a&(b|c)
address@hidden example
+
address@hidden File introduction directives
address@hidden File introduction directives
+
+A file (or sequence) introduction directive appears at the beginning
+of the file. There are two different directives, one is @code{DECK}
+for normal files, the other is @code{KEEP} for include files (sequences).
+The first argument is the name of the file. The file name may not be larger
+than 32 characters and is converted to lower case in the general case.
+The optionnal following arguments may be
+of 2 type (and may be mixed, separated by @samp{,}):
+
address@hidden @asis
address@hidden conditional
+A conditionnal is introduced by @code{IF=} followed by a conditionnal
+expression described in
address@hidden expressions}. The
+file is preprocessed if the conditionnal expression is true.
address@hidden language specification
+A language specification is introduced by a @code{T=}. The most
+common languages are @samp{mtn} for the mortran, @samp{ftn} for
+fortran not preprocessed, @samp{f77} for preprocessed fortran,
address@hidden for the c language and @samp{txt} for text files.
+In general the language of the file determines the name of files
+the preprocessed file is extracted to, the comment style and
+the command for inclusions.
address@hidden table
+
+It is a common practice to have wrong language type in @code{KEEP}
+as the language may be determined from the @code{DECK} that include
+them with cmz, or from their file name with make. This is not recommended
+and considered a bad practice.
+
+Such a directive will always appear in cmz, as it is built-in. It
+is recommended to have one when using make too, even though it is not
+required in most cases. Indeed make uses the file name directly
+and finds the language and file type by looking at the file extension.
+make should then pass the language type with a
address@hidden @var{lang}} command
+line switch when calling the cmz directives preprocessor.
+With make, the convention is to have @samp{cm} added before the normal
+file suffix and after the @samp{.}. The table @ref{tab:cmfile_suffix}
+shows the matching between suffixes, file type and file language.
+
+For example, a file beginning with
+
address@hidden
++Deck, subroutine_foo, If=monitor&-simple, T=f77.
address@hidden verbatim
+
+is a main preprocessed fortran file that will only be generated if
address@hidden is selected and @samp{simple} is not selected. The
+file to be preprocessed by make should have the @samp{.cmF} suffix,
+and be called @file{subroutine_foo.cmF}.
+
+A file beginning with
+
address@hidden
++KEEP,inc_common,If=monitor|interface,T=mtn
address@hidden verbatim
+
+is an mortran include file that should be processed only if @samp{monitor}
+or @samp{interface} is selected. The file to be preprocessed by make
+should have the @samp{cmmti} suffix and be called @file{inc_common.cmmti}.
+The resulting file when make is used will be called @file{inc_common.mti}.
+
address@hidden Conditional directives
address@hidden Conditional directives
+
+Conditional directives may be used to conditionnaly skip blocks of
+code. There are 4 conditional directives: @code{if}, @code{elseif},
address@hidden and @code{endif}. @code{+if} begins a conditional directives
+sequence, with argument a conditional expression. If the expression is
+true the block of code following the @code{+if} is output in the
+resulting file, up to another conditional directive, if it is false
+the code block is skipped. If the
+expression is false and the following conditional directive is
address@hidden, the same procedure is followed with the argument of
address@hidden
+which is also a conditionnal expression. More than one @code{+elseif}
+may follow a @code{+if}. If a @code{+if} or @code{+elseif} expression
+is true the following
+code block is output and all
+the following @code{+elseif} code blocks are skipped. If all the @code{+if}
+and @code{+elseif} expressions are false and
+the following coditionnal
+directive is @code{+else} then the block following the
address@hidden is output. If a previous expression was true the
+code block following the @code{+else} is skipped. The last code block
+is closed by @code{+endif}.
+
+Conditionnal directives may be nested, a @code{+if} begins a deeper
+conditionnal sequences directives that is ended by the corresponding
address@hidden
+
+The simplest example is:
+
address@hidden
+ some code;
++IF,monitor
+ code output only if monitor is true;
++ENDIF
address@hidden verbatim
+
+If @samp{monitor} is selected, the @code{+if} block is output, it leads to
+
address@hidden
+ some code;
+ code output only if monitor is true;
address@hidden verbatim
+
+If @samp{monitor} isn't selected the @code{+if} block is skipped, it leads to
+
address@hidden
+ some code;
address@hidden verbatim
+
+An example with @code{+else} may be:
+
address@hidden
++IF,double
+ call dmysub(eta);
++ELSE
+ call smysub(eta);
++ENDIF
address@hidden verbatim
+
+If @samp{double} is selected the code output is @code{call dmysub(eta);},
+if @samp{double} isn't selected the code output is @code{call dmysub(eta);}.
+
+Here is a self explanatory example of use of @code{+elseif}:
+
address@hidden
++IF,monitor
+ code used if monitor is selected;
++ELSEIF,kalman
+ code used if kalman is selected and monitor is not;
++ELSE
+ code used if kalman and monitor are not selected;
++ENDIF
address@hidden verbatim
+
+And last an example of nested conditional directives:
+
address@hidden
++IF,monitor
+ code used if monitor is selected;
++_IF,kalman. deep if
+ code used if monitor and kalman are selected;
++_ELSE. deep else
+ code used if monitor is selected and kalman is not;
++_ENDIF. end the deep conditionnals sequence
++ELSE
+ code used if monitor is not selected;
++_IF,kalman
+ code used if monitor is not selected but kalman is;
++_ELSE
+ code used if monitor and kalman are not selected;
++_ENDIF
+ other code used if monitor is not selected;
++ENDIF
address@hidden verbatim
+
address@hidden File inclusion directive
address@hidden File inclusion directive
+
+The file (sequence) inclusion directive is @code{seq}. The argument of
address@hidden is an include files @samp{,} separated list. The include
+files are @code{Keep} in cmz. The following optional arguments may be
+mixed:
+
address@hidden @asis
address@hidden conditional
+A conditionnal is introduced by @code{IF=} followed by a conditionnal
+expression described in
address@hidden expressions}. The
+directive is ignored if the conditionnal expression is false.
address@hidden T=noinclude
+When this argument is present the text of the sequence will
+always be included in the file where the @code{+seq} appears.
address@hidden table
+
+When there is no @code{T=noinclude} argument, the @code{+seq}
+directive may be replaced with an inclusion command suitable
+for the language of the file being processed, if such
+command has been specified.
+
+For example if we have the following sequence
address@hidden
++KEEP,inc,lang=C
+typedef struct incstr {char* msg};
address@hidden verbatim
+
+And the following code in the file being processed:
+
address@hidden
++DECK,mainf,lang=C
++SEQ,inc
+int main (int argc, char* argv) { exit(0); }
address@hidden verbatim
+
+the processing of @file{mainf} should lead to the file
address@hidden, containing
+an include command for @file{inc}:
+
address@hidden
+#include "inc.h"
+int main (int argc, char* argv) { exit(0); }
address@hidden verbatim
+
+In case the @code{+seq} has the @code{T=noinclude}:
+
address@hidden
++DECK,mainf,lang=C
++SEQ,inc,T=noinclude
+int main (int argc, char* argv) { exit(0); }
address@hidden verbatim
+
+The processing of @file{mainf} should lead to the file @file{mainf.c}
+containing the text of @file{inc}:
+
address@hidden
+typedef struct incstr {char* msg};
+int main (int argc, char* argv) { exit(0); }
address@hidden verbatim
+
address@hidden The self directive
address@hidden The @samp{self} directive
+
+The @code{self} directive is an obsolete directive that may be used for
+conditionnal skipping of code. For a better approach see
address@hidden directives}.
+The optionnal argument of @code{+SELF} is @code{If=} followed by
+a conditionnal expression. If the conditionnal expression is true the
+code following the directive is output, if it is false the code
+is skipped up to any directive (including another @code{+SELF})
+except @code{+seq}.
+
+
address@hidden Copying This Manual
address@hidden Copying This Manual
+
address@hidden
+* GNU Free Documentation License:: License for copying this manual.
address@hidden menu
+
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
+
address@hidden FDL, GNU Free Documentation License
address@hidden Version 1.1, March 2000
+
address@hidden
+Copyright @copyright{} 2000 Free Software Foundation, Inc.
+59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
address@hidden display
+
address@hidden 0
address@hidden
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+written document @dfn{free} in the sense of freedom: to assure everyone
+the effective freedom to copy and redistribute it, with or without
+modifying it, either commercially or noncommercially. Secondarily,
+this License preserves for the author and publisher a way to get
+credit for their work, while not being considered responsible for
+modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
address@hidden
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work that contains a
+notice placed by the copyright holder saying it can be distributed
+under the terms of this License. The ``Document'', below, refers to any
+such manual or work. Any member of the public is a licensee, and is
+addressed as ``you''.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (For example, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, whose contents can be viewed and edited directly and
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is
+not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
address@hidden without markup, Texinfo input format, address@hidden input
format,
address@hidden or @acronym{XML} using a publicly available
address@hidden, and standard-conforming simple @acronym{HTML} designed
+for human modification. Opaque formats include PostScript,
address@hidden, proprietary formats that can be read and edited only by
+proprietary word processors, @acronym{SGML} or @acronym{XML} for which
+the @acronym{DTD} and/or processing tools are not generally available,
+and the machine-generated @acronym{HTML} produced by some word
+processors for output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
address@hidden
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
address@hidden
+COPYING IN QUANTITY
+
+If you publish printed copies of the Document numbering more than 100,
+and the Document's license notice requires Cover Texts, you must enclose
+the copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols. If you use the latter
+option, you must take reasonably prudent steps, when you begin
+distribution of Opaque copies in quantity, to ensure that this
+Transparent copy will remain thus accessible at the stated location
+until at least one year after the last time you distribute an Opaque
+copy (directly or through your agents or retailers) of that edition to
+the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
address@hidden
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
address@hidden A
address@hidden
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
address@hidden
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has less than five).
+
address@hidden
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
address@hidden
+Preserve all the copyright notices of the Document.
+
address@hidden
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
address@hidden
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
address@hidden
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
address@hidden
+Include an unaltered copy of this License.
+
address@hidden
+Preserve the section entitled ``History'', and its title, and add to
+it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
address@hidden
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
address@hidden
+In any section entitled ``Acknowledgments'' or ``Dedications'',
+preserve the section's title, and preserve in the section all the
+substance and tone of each of the contributor acknowledgments
+and/or dedications given therein.
+
address@hidden
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
address@hidden
+Delete any section entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
address@hidden
+Do not retitle any existing section as ``Endorsements''
+or to conflict in title with any Invariant Section.
address@hidden enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
address@hidden
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections entitled ``History''
+in the various original documents, forming one section entitled
+``History''; likewise combine any sections entitled ``Acknowledgments'',
+and any sections entitled ``Dedications''. You must delete all sections
+entitled ``Endorsements.''
+
address@hidden
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
address@hidden
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, does not as a whole count as a Modified Version
+of the Document, provided no compilation copyright is claimed for the
+compilation. Such a compilation is called an ``aggregate'', and this
+License does not apply to the other self-contained works thus compiled
+with the Document, on account of their being thus compiled, if they
+are not themselves derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one quarter
+of the entire aggregate, the Document's Cover Texts may be placed on
+covers that surround only the Document within the aggregate.
+Otherwise they must appear on covers around the whole aggregate.
+
address@hidden
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License provided that you also include the
+original English version of this License. In case of a disagreement
+between the translation and the original English version of this
+License, the original English version will prevail.
+
address@hidden
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
address@hidden
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
address@hidden://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
address@hidden enumerate
+
address@hidden
address@hidden ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
address@hidden
address@hidden
+ Copyright (C) @var{year} @var{your name}.
+ 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 the Invariant Sections being @var{list their titles}, with the
+ Front-Cover Texts being @var{list}, and with the Back-Cover Texts being
@var{list}.
+ A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
address@hidden group
address@hidden smallexample
+
+If you have no Invariant Sections, write ``with no Invariant Sections''
+instead of saying which ones are invariant. If you have no
+Front-Cover Texts, write ``no Front-Cover Texts'' instead of
+``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
address@hidden Local Variables:
address@hidden ispell-local-pdict: "ispell-dict"
address@hidden End:
+
+
address@hidden
Index: res_all/texi_texinfo/texinfo.texi.first
===================================================================
RCS file: res_all/texi_texinfo/texinfo.texi.first
diff -N res_all/texi_texinfo/texinfo.texi.first
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ res_all/texi_texinfo/texinfo.texi.first 2 Aug 2009 13:11:02 -0000
1.1
@@ -0,0 +1,18089 @@
+\input texinfo.tex @c -*-texinfo-*-
address@hidden Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $
address@hidden Ordinarily Texinfo files have the extension .texi. But
texinfo.texi
address@hidden clashes with texinfo.tex on 8.3 filesystems, so we use
texinfo.txi.
+
address@hidden Everything between the start/end of header lines will be passed
by
address@hidden Emacs's {texinfo,makeinfo}-format region commands. See the
`start of
address@hidden header' node for more info.
address@hidden %**start of header
+
address@hidden makeinfo and texinfo.tex ignore all text before @setfilename.
address@hidden
address@hidden Ordinarily the setfilename argument ends with .info. But
address@hidden texinfo.info-13 is too long for 14-character filesystems.
address@hidden texinfo
+
address@hidden Automake automatically updates version.texi to @set VERSION and
address@hidden @set UPDATED to appropriate values.
address@hidden UPDATED 28 March 2002
address@hidden UPDATED-MONTH March 2002
address@hidden EDITION 4.2
address@hidden VERSION 4.2
address@hidden GNU Texinfo 4.2
+
address@hidden Define a new index for options.
address@hidden op
address@hidden Put everything except function (command, in this case) names in
one
address@hidden index (arbitrarily chosen to be the concept index).
address@hidden op cp
address@hidden vr cp
address@hidden pg cp
+
address@hidden separate
address@hidden 2
address@hidden finalout
+
address@hidden %**end of header
+
+
address@hidden Texinfo documentation system
address@hidden
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. Update info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
+* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
+* makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source.
address@hidden direntry
+
address@hidden Before release, run C-u C-c C-u C-a (texinfo-all-menus-update
with a
address@hidden prefix arg). This updates the node pointers, which texinfmt.el
needs.
+
address@hidden Set smallbook if printing in smallbook format so the example of
the
address@hidden smallbook font is actually written using smallbook; in bigbook,
a kludge
address@hidden is used for TeX output. Do this through the -t option to
texi2dvi,
address@hidden so this same source can be used for other paper sizes as well.
address@hidden smallbook
address@hidden set smallbook
address@hidden @@clear smallbook
+
address@hidden If you like blank pages, add through texi2dvi -t.
address@hidden setchapternewpage odd
+
address@hidden Currently undocumented command, 5 December 1993:
address@hidden nwnode (Same as node, but no warnings; for `makeinfo'.)
+
+
address@hidden Texinfo
+
+
+
address@hidden
address@hidden
+
+
address@hidden Top
address@hidden Texinfo
+
address@hidden
+
+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.
+
+
address@hidden
+* Copying Conditions:: Your rights.
+* Overview:: Texinfo in brief.
+* Texinfo Mode:: How to use Texinfo mode.
+* Beginning a File:: What is at the beginning of a Texinfo file?
+* Ending a File:: What is at the end of a Texinfo file?
+* Structuring:: How to create chapters, sections, subsections,
+ appendices, and other parts.
+* Nodes:: How to write nodes.
+* Menus:: How to write menus.
+* Cross References:: How to write cross references.
+* Marking Text:: How to mark words and phrases as code,
+ keyboard input, meta-syntactic
+ variables, and the like.
+* Quotations and Examples:: How to write quotations, examples, etc.
+* Lists and Tables:: How to write lists and tables.
+* Indices:: How to create indices.
+* Insertions:: How to insert @@-signs, braces, etc.
+* Breaks:: How to force and prevent line and page breaks.
+* Definition Commands:: How to describe functions and the like
+ in a uniform manner.
+* Conditionals:: How to specify text for either @TeX{} or Info.
+* Internationalization::
+* Defining New Texinfo Commands::
+* Hardcopy:: How to convert a Texinfo file to a file
+ for printing and how to print that file.
+* Creating and Installing Info Files::
+* Command List:: All the Texinfo @@-commands.
+* Tips:: Hints on how to write a Texinfo document.
+* Sample Texinfo Files:: Complete examples, including full texts.
+* Include Files:: How to incorporate other Texinfo files.
+* Headings:: How to write page headings and footings.
+* Catching Mistakes:: How to find formatting mistakes.
+* Refilling Paragraphs:: All about paragraph refilling.
+* Command Syntax:: A description of @@-Command syntax.
+* Obtaining TeX:: How to Obtain @TeX{}.
+* Copying This Manual:: The GNU Free Documentation License.
+* Command and Variable Index:: A menu containing commands and variables.
+* Concept Index:: A menu covering many topics.
+
address@hidden
+ --- The Detailed Node Listing ---
+
+Overview of Texinfo
+
+* Reporting Bugs:: Submitting effective bug reports.
+* Using Texinfo:: Create printed or online output.
+* Info Files:: What is an Info file?
+* Printed Books:: Characteristics of a printed book or manual.
+* Formatting Commands:: @@-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.
+* Six Parts:: Usually, a Texinfo file has six parts.
+* Short Sample:: A short sample Texinfo file.
+* History:: Acknowledgements, contributors and genesis.
+
+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.
+
+Beginning a Texinfo File
+
+* Sample Beginning:: A sample beginning for a Texinfo file.
+* Texinfo File Header::
+* Document Permissions::
+* Titlepage & Copyright Page:: Creating the title and copyright pages.
+* The Top Node:: Creating the `Top' node and master menu.
+* Global Document Commands::
+* Software Copying Permissions:: Ensure that you and others continue to
+ have the right to use and share software.
+
+Texinfo File Header
+
+* First Line:: The first line of a Texinfo file.
+* Start of Header:: Formatting a region requires this.
+* setfilename:: Tell Info the name of the Info file.
+* settitle:: Create a title for the printed work.
+* End of Header:: Formatting a region requires this.
+
+Document Permissions
+
+* copying:: Declare the document's copying permissions.
+* insertcopying:: Where to insert the permissions.
+
+Title and Copyright Pages
+
+* titlepage:: Create a title for the printed document.
+* titlefont center sp:: The @code{@@titlefont}, @code{@@center},
+ and @code{@@sp} commands.
+* title subtitle author:: The @code{@@title}, @code{@@subtitle},
+ and @code{@@author} commands.
+* Copyright:: How to write the copyright notice and
+ include copying permissions.
+* end titlepage:: Turn on page headings after the title and
+ copyright pages.
+* headings on off:: An option for turning headings on and off
+ and double or single sided printing.
+
+The `Top' Node and Master Menu
+
+* Top Node Example::
+* Master Menu Parts::
+
+Global Document Commands
+
+* documentdescription:: Document summary for the HTML output.
+* setchapternewpage:: Start chapters on right-hand pages.
+* paragraphindent:: Specify paragraph indentation.
+* exampleindent:: Specify environment indentation.
+
+Ending a Texinfo File
+
+* Printing Indices & Menus:: How to print an index in hardcopy and
+ generate index menus in Info.
+* Contents:: How to create a table of contents.
+* File End:: How to mark the end of a file.
+
+Chapter Structuring
+
+* Tree Structuring:: A manual is like an upside down tree @dots{}
+* Structuring Command Types:: How to divide a manual into parts.
+* makeinfo top:: The @code{@@top} command, part of the `Top'
node.
+* chapter::
+* unnumbered & appendix::
+* majorheading & chapheading::
+* section::
+* unnumberedsec appendixsec heading::
+* subsection::
+* unnumberedsubsec appendixsubsec subheading::
+* subsubsection:: Commands for the lowest level sections.
+* Raise/lower sections:: How to change commands' hierarchical level.
+
+Nodes
+
+* Two Paths:: Different commands to structure
+ Info output and printed output.
+* Node Menu Illustration:: A diagram, and sample nodes and menus.
+* node:: Creating nodes, in detail.
+* makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
+* anchor:: Defining arbitrary cross-reference targets.
+
+The @code{@@node} Command
+
+* Node Names:: How to choose node and pointer names.
+* Writing a Node:: How to write an @code{@@node} line.
+* Node Line Tips:: Keep names short.
+* Node Line Requirements:: Keep names unique, without @@-commands.
+* First Node:: How to write a `Top' node.
+* makeinfo top command:: How to use the @code{@@top} command.
+
+Menus
+
+* Menu Location:: Put a menu in a short node.
+* Writing a Menu:: What is a menu?
+* Menu Parts:: A menu entry has three parts.
+* Less Cluttered Menu Entry:: Two part menu entry.
+* Menu Example:: Two and three part menu entries.
+* Other Info Files:: How to refer to a different Info file.
+
+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.
+* xref:: Begin a reference with `See' @dots{}
+* Top Node Naming:: How to refer to the beginning of another file.
+* ref:: A reference for the last part of a sentence.
+* pxref:: How to write a parenthetical cross reference.
+* inforef:: How to refer to an Info-only file.
+* uref:: How to refer to a uniform resource locator.
+
address@hidden@@xref}
+
+* Reference Syntax:: What a reference looks like and requires.
+* 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.
+
+Marking 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:: Indicating program code.
+* kbd:: Showing keyboard input.
+* key:: Specifying keys.
+* samp:: A literal sequence of characters.
+* verb:: A verbatim sequence of characters.
+* var:: Indicating metasyntactic variables.
+* env:: Indicating environment variables.
+* file:: Indicating file names.
+* command:: Indicating command names.
+* option:: Indicating option names.
+* dfn:: Specifying definitions.
+* cite:: Referring to books not in the Info system.
+* acronym:: Indicating acronyms.
+* url:: Indicating a World Wide Web reference.
+* email:: Indicating an electronic mail address.
+
+Emphasizing Text
+
+* 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.
+* quotation:: Writing a quotation.
+* example:: Writing an example in a fixed-width font.
+* verbatim:: Writing a verbatim example.
+* verbatiminclude:: Including a file verbatim.
+* lisp:: Illustrating Lisp code.
+* small:: Forms for @code{@@smallbook}.
+* display:: Writing an example in the current font.
+* format:: Writing an example without narrowed margins.
+* exdent:: Undo indentation on a line.
+* flushleft & flushright:: Pushing text flush left or flush right.
+* noindent:: Preventing paragraph indentation.
+* cartouche:: Drawing rounded rectangles around examples.
+
+Lists and Tables
+
+* Introducing Lists:: Texinfo formats lists for you.
+* itemize:: How to construct a simple list.
+* 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
+
+* table:: How to construct a two-column table.
+* ftable vtable:: Automatic indexing for two-column tables.
+* itemx:: How to put more entries in the first column.
+
+Multi-column Tables
+
+* Multitable Column Widths:: Defining multitable column widths.
+* Multitable Rows:: Defining multitable rows, with examples.
+
+Indices
+
+* Index Entries:: Choose different words for index entries.
+* Predefined Indices:: Use different indices for different kinds
+ of entry.
+* Indexing Commands:: How to make an index entry.
+* Combining Indices:: How to combine indices.
+* New Indices:: How to define your own indices.
+
+Combining Indices
+
+* syncodeindex:: How to merge two indices, using @code{@@code}
+ font for the merged-from index.
+* synindex:: How to merge two indices, using the
+ default font of the merged-to index.
+
+Special Insertions
+
+* Braces Atsigns:: How to insert braces, @samp{@@}.
+* Inserting Space:: How to insert the right amount of space
+ within a sentence.
+* Inserting Accents:: How to insert accents and special characters.
+* Dots Bullets:: How to insert dots and bullets.
+* TeX and copyright:: How to insert the @TeX{} logo
+ and the copyright symbol.
+* pounds:: How to insert the pounds currency symbol.
+* minus:: How to insert a minus sign.
+* math:: How to format a mathematical expression.
+* Glyphs:: How to indicate results of evaluation,
+ expansion of macros, errors, etc.
+* Footnotes:: How to include footnotes.
+* Images:: How to include graphics.
+
+Inserting @@ and Braces
+
+* Inserting An Atsign:: How to insert @samp{@@}.
+* Inserting Braces:: How to insert @address@hidden and
@address@hidden
+
+Inserting Space
+
+* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
+* Ending a Sentence:: Sometimes it does.
+* Multiple Spaces:: Inserting multiple spaces.
+* dmn:: How to format a dimension.
+
+Inserting Ellipsis and Bullets
+
+* dots:: How to insert dots @dots{}
+* bullet:: How to insert a bullet.
+
+Inserting @TeX{} and the Copyright Symbol
+
+* tex:: How to insert the @TeX{} logo.
+* copyright symbol:: How to use @code{@@address@hidden@}.
+
+Glyphs for Examples
+
+* Glyphs Summary::
+* result:: How to show the result of expression.
+* expansion:: How to indicate an expansion.
+* Print Glyph:: How to indicate printed output.
+* Error Glyph:: How to indicate an error message.
+* Equivalence:: How to indicate equivalence.
+* Point Glyph:: How to indicate the location of point.
+
+Glyphs Summary
+
+* result::
+* expansion::
+* Print Glyph::
+* Error Glyph::
+* Equivalence::
+* Point Glyph::
+
+Footnotes
+
+* Footnote Commands:: How to write a footnote in Texinfo.
+* Footnote Styles:: Controlling how footnotes appear in Info.
+
+Making and Preventing Breaks
+
+* Break Commands:: Cause and prevent splits.
+* Line Breaks:: How to force a single line to use two lines.
+* - and hyphenation:: How to tell @TeX{} about hyphenation points.
+* w:: How to prevent unwanted line breaks.
+* sp:: How to insert blank lines.
+* page:: How to force the start of a new page.
+* group:: How to prevent unwanted page breaks.
+* need:: Another way to prevent unwanted page breaks.
+
+Definition Commands
+
+* Def Cmd Template:: How to structure a description using a
+ definition command.
+* Optional Arguments:: How to handle optional and repeated arguments.
+* deffnx:: How to group two or more `first' lines.
+* Def Cmds in Detail:: All the definition commands.
+* Def Cmd Conventions:: Conventions for writing definitions.
+* Sample Function Definition::
+
+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.
+* Abstract Objects:: Commands for object-oriented programming.
+* Data Types:: The definition command for data types.
+
+Conditionally Visible Text
+
+* Conditional Commands:: Specifying text for HTML, Info, or @TeX{}.
+* Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}.
+* Raw Formatter Commands:: Using raw @TeX{} or HTML commands.
+* set clear value:: Designating which text to format (for
+ all output formats); and how to set a
+ flag to a string that you can insert.
+
address@hidden@@set}, @code{@@clear}, and @code{@@value}
+
+* set value:: Expand a flag variable to a string.
+* ifset ifclear:: Format a region if a flag is set.
+* value Example:: An easy way to update edition information.
+
+Internationalization
+
+* documentlanguage:: Declaring the current language.
+* documentencoding:: Declaring the input encoding.
+
+Defining New Texinfo Commands
+
+* Defining Macros:: Defining and undefining new commands.
+* Invoking Macros:: Using a macro, once you've defined it.
+* Macro Details:: Beyond basic macro usage.
+* alias:: Command aliases.
+* definfoenclose:: Customized highlighting.
+
+Formatting and Printing Hardcopy
+
+* Use TeX:: Use @TeX{} to format for hardcopy.
+* Format with tex/texindex:: How to format with explicit shell commands.
+* Format with texi2dvi:: A simpler way to format.
+* Print with 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.
+* smallbook:: How to print small format books and manuals.
+* A4 Paper:: How to print on A4 or A5 paper.
+* 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.
+
+Creating and Installing Info Files
+
+* Creating an Info File::
+* Installing an Info File::
+
+Creating an Info File
+
+* makeinfo advantages:: @code{makeinfo} provides better error checking.
+* Invoking makeinfo:: How to run @code{makeinfo} from a shell.
+* makeinfo options:: Specify fill-column and other options.
+* Pointer Validation:: How to check that pointers point somewhere.
+* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs.
+* 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.
+* makeinfo html:: Generating HTML output.
+
+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 install-info:: @code{install-info} options.
+
+Sample Texinfo Files
+
+* Short Sample Texinfo File::
+* GNU Sample Texts::
+
+Include Files
+
+* Using Include Files:: How to use the @code{@@include} command.
+* texinfo-multiple-files-update:: How to create and update nodes and
+ menus when using included files.
+* Include File Requirements:: What @code{texinfo-multiple-files-update}
expects.
+* 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.
+
+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.
+
+Formatting Mistakes
+
+* 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 texinfo-show-structure:: How to use @code{texinfo-show-structure}.
+* Using occur:: How to list all lines containing a pattern.
+* Running Info-Validate:: How to find badly referenced nodes.
+
+Finding Badly Referenced Nodes
+
+* Using 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.
+
+Copying This Manual
+
+* GNU Free Documentation License:: License for copying this manual.
+
address@hidden detailmenu
address@hidden menu
+
address@hidden Reward readers for getting to the end of the menu :).
address@hidden Contributed by Arnold Robbins.
address@hidden
+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
address@hidden quotation
+
+
address@hidden Copying Conditions
address@hidden Texinfo Copying Conditions
address@hidden Copying conditions
address@hidden Conditions for copying Texinfo
+
+The programs currently being distributed that relate to Texinfo include
address@hidden, @code{info}, @code{texindex}, and @file{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. This manual specifically is covered by
+the GNU Free Documentation License (@pxref{GNU Free Documentation
+License}).
+
+
address@hidden Overview
address@hidden Overview of Texinfo
address@hidden Overview of Texinfo
address@hidden Texinfo overview
+
address@hidden@footnote{The first syllable of ``Texinfo'' is pronounced
+like ``speck'', not ``hex''. This odd pronunciation is derived from,
+but is not the same as, the pronunciation of @TeX{}. In the word
address@hidden, the @samp{X} is actually the Greek letter ``chi'' rather than
+the English letter ``ex''. Pronounce @TeX{} as if the @samp{X} were the
+last sound in the name `Bach'; but pronounce Texinfo as if the @samp{x}
+were a `k'. Spell ``Texinfo'' with a capital ``T'' and the other
+letters in lower case.} is a documentation system that uses a single
+source file to produce both online information and printed output. This
+means that instead of writing two different documents, one for the
+online information and the other for a printed work, you need write only
+one document. Therefore, when the work is revised, you need revise only
+that one document.
+
address@hidden
+* Reporting Bugs:: Submitting effective bug reports.
+* Using Texinfo:: Create printed or online output.
+* Info Files:: What is an Info file?
+* Printed Books:: Characteristics of a printed book or manual.
+* Formatting Commands:: @@-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.
+* Six Parts:: Usually, a Texinfo file has six parts.
+* Short Sample:: A short sample Texinfo file.
+* History:: Acknowledgements, contributors and genesis.
address@hidden menu
+
+
address@hidden Reporting Bugs
address@hidden Reporting Bugs
+
address@hidden Bugs, reporting
address@hidden Suggestions for Texinfo, making
address@hidden Reporting bugs
+We welcome bug reports and suggestions for any aspect of the Texinfo system,
+programs, documentation, installation, anything. Please email them to
address@hidden@@gnu.org}. You can get the latest version of Texinfo
+from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide.
+
address@hidden Checklist for bug reports
+For bug reports, please include enough information for the maintainers
+to reproduce the problem. Generally speaking, that means:
+
address@hidden @bullet
address@hidden the version number of Texinfo and the program(s) or manual(s)
involved.
address@hidden hardware and operating system names and versions.
address@hidden the contents of any input files necessary to reproduce the bug.
address@hidden a description of the problem and samples of any erroneous output.
address@hidden any unusual options you gave to @command{configure}.
address@hidden anything else that you think would be helpful.
address@hidden 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.
+
address@hidden Patches, contributing
+Patches are most welcome; if possible, please make them with
address@hidden@w{diff -c}} (@pxref{Top,, Overview, diffutils, Comparing and
+Merging Files}) and include @file{ChangeLog} entries (@pxref{Change
+Log,,, emacs, The GNU Emacs Manual}).
+
+When sending patches, if possible please do not encode or split them in
+any way; it's much easier to deal with one plain text message, however
+large, than many small ones. @uref{ftp://ftp.gnu.org/gnu/sharutils/,
+GNU shar} is a convenient way of packaging multiple and/or binary files
+for email.
+
+
address@hidden Using Texinfo
address@hidden Using Texinfo
+
address@hidden Using Texinfo in general
address@hidden Texinfo, introduction to
address@hidden Introduction to Texinfo
+
+Using Texinfo, you can create a printed document with the normal
+features of a book, including chapters, sections, cross references, and
+indices. From the same Texinfo source file, you can create a
+menu-driven, online Info file with nodes, menus, cross references, and
+indices. You can also create from that same source file an HTML output
+file suitable for use with a web browser, or an XML file. @cite{The GNU
+Emacs Manual} is a good example of a Texinfo file, as is this manual.
+
+To make a printed document, you process a Texinfo source file with the
address@hidden typesetting program (but the Texinfo language is very different
+and much stricter than @TeX{}'s usual language, plain @TeX{}). This
+creates a DVI file that you can typeset and print as a book or report
+(@pxref{Hardcopy}).
+
address@hidden makeinfo
+To output an Info file, process your Texinfo source with the
address@hidden utility or Emacs's @code{texinfo-format-buffer} command.
+You can install the result in your Info tree (@pxref{Installing an Info
+File}).
+
+To output an HTML file, run @code{makeinfo --html} on your Texinfo
+source. You can (for example) install the result on your web site.
+
address@hidden Docbook, converting to Texinfo
address@hidden Conversion, from Docbook to Texinfo
+To output an XML file, run @code{makeinfo --xml} on your Texinfo source.
+To output DocBook (a particular form of XML), run @code{makeinfo
+--docbook}. If you want to convert from Docbook @emph{to} Texinfo,
+please see @uref{http://docbook2X.sourceforge.net/}.
+
address@hidden Output formats, supporting more
address@hidden SGML-tools output format
+If you are a programmer and would like to contribute to the GNU project
+by implementing additional output formats for Texinfo, that would be
+excellent. But please do not write a separate translator texi2foo for
+your favorite format foo! That is the hard way to do the job, and makes
+extra work in subsequent maintenance, since the Texinfo language is
+continually being enhanced and updated. Instead, the best approach is
+modify @code{makeinfo} to generate the new format, as it does now for
+Info, plain text, HTML, XML, and DocBook.
+
address@hidden works with virtually all printers; Info works with virtually all
+computer terminals; the HTML output works with virtually all web
+browsers. Thus Texinfo can be used by almost any computer user.
+
address@hidden Source file
+A Texinfo source file is a plain @sc{ascii} file containing text and
address@hidden@@-commands} (words preceded by an @samp{@@}) that tell the
+typesetting and formatting programs what to do. You may 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}.)
+
+Before writing a Texinfo source file, you should learn about nodes,
+menus, cross references, and the rest, for example by reading this
+manual.
+
+You can use Texinfo to create both online help and printed manuals;
+moreover, Texinfo is freely redistributable. For these reasons, Texinfo
+is the official documentation format of the GNU project. More
+information is available at the @uref{http://www.gnu.org/doc/, GNU
+documentation web page}.
+
address@hidden Man page output, not supported
+From time to time, proposals are made to generate traditional Unix man
+pages from Texinfo source. This is not likely to ever be supported,
+because man pages have a very strict conventional format. Merely
+enhancing @command{makeinfo} to output troff format would be
+insufficient. Generating a good man page therefore requires a
+completely different source than the typical Texinfo applications of
+writing a good user tutorial or a good reference manual. This makes
+generating man pages incompatible with the Texinfo design goal of not
+having to document the same information in different ways for different
+output formats. You might as well just write the man page directly.
+
address@hidden help2man
address@hidden O'Dea, Brendan
+Man pages still have their place, and if you wish to support them, the
+program @command{help2man} may be useful; it generates a traditional man
+page from the @samp{--help} output of a program. In fact, this is
+currently used to generate man pages for the Texinfo programs
+themselves. It is GNU software written by Brendan O'Dea, available from
address@hidden://ftp.gnu.org/gnu/help2man/}.
+
+
address@hidden Info Files
address@hidden Info files
address@hidden Info files
+
+An Info file is a Texinfo file formatted so that the Info documentation
+reading program can operate on it. (@code{makeinfo}
+and @code{texinfo-format-buffer} are two commands that convert a Texinfo file
+into an Info file.)
+
+Info files are divided into pieces called @dfn{nodes}, each of which
+contains the discussion of one topic. Each node has a name, and
+contains both text for the user to read and pointers to other nodes,
+which are identified by their names. The Info program displays one node
+at a time, and provides commands with which the user can move to other
+related nodes.
+
address@hidden, info, info}, for more information about using Info.
+
+Each node of an Info file may have any number of child nodes that
+describe subtopics of the node's topic. The names of child
+nodes are listed in a @dfn{menu} within the parent node; this
+allows you to use certain Info commands to move to one of the child
+nodes. Generally, an Info file is organized like a book. If a node
+is at the logical level of a chapter, its child nodes are at the level
+of sections; likewise, the child nodes of sections are at the level
+of subsections.
+
+All the children of any one parent are linked together in a
+bidirectional chain of `Next' and `Previous' pointers. The `Next'
+pointer provides a link to the next section, and the `Previous' pointer
+provides a link to the previous section. This means that all the nodes
+that are at the level of sections within a chapter are linked together.
+Normally the order in this chain is the same as the order of the
+children in the parent's menu. Each child node records the parent node
+name as its `Up' pointer. The last child has no `Next' pointer, and the
+first child has the parent both as its `Previous' and as its `Up'
address@hidden some documents, the first child has no `Previous'
+pointer. Occasionally, the last child has the node name of the next
+following higher level node as its `Next' pointer.}
+
+The book-like structuring of an Info file into nodes that correspond
+to chapters, sections, and the like is a matter of convention, not a
+requirement. The `Up', `Previous', and `Next' pointers of a node can
+point to any other nodes, and a menu can contain any other nodes.
+Thus, the node structure can be any directed graph. But it is usually
+more comprehensible to follow a structure that corresponds to the
+structure of chapters and sections in a printed book or address@hidden
+
+In addition to menus and to `Next', `Previous', and `Up' pointers, Info
+provides pointers of another kind, called references, that can be
+sprinkled throughout the text. This is usually the best way to
+represent links that do not fit a hierarchical address@hidden
+
+Usually, you will design a document so that its nodes match the
+structure of chapters and sections in the printed output. But
+occasionally there are times when this is not right for the material
+being discussed. Therefore, Texinfo uses separate commands to specify
+the node structure for the Info file and the section structure for the
+printed address@hidden
+
+Generally, you enter an Info file through a node that by convention is
+named `Top'. This node normally contains just a brief summary of the
+file's purpose, and a large menu through which the rest of the file is
+reached. From this node, you can either traverse the file
+systematically by going from node to node, or you can go to a specific
+node listed in the main menu, or you can search the index menus and then
+go directly to the node that has the information you want. Alternatively,
+with the standalone Info program, you can specify specific menu items on
+the command line (@pxref{Top,,, info, Info}).
+
+If you want to read through an Info file in sequence, as if it were a
+printed manual, you can hit @key{SPC} repeatedly, or you get the whole
+file with the advanced Info command @kbd{g *}. (@inforef{Expert,
+Advanced Info commands, info}.)@refill
+
address@hidden !!! dir file may be located in one of many places:
address@hidden /usr/local/emacs/info mentioned in info.c
DEFAULT_INFOPATH
address@hidden /usr/local/lib/emacs/info mentioned in info.c
DEFAULT_INFOPATH
address@hidden /usr/gnu/info mentioned in info.c
DEFAULT_INFOPATH
address@hidden /usr/local/info
address@hidden /usr/local/lib/info
+The @file{dir} file in the @file{info} directory serves as the
+departure point for the whole Info system. From it, you can reach the
+`Top' nodes of each of the documents in a complete Info address@hidden
+
address@hidden URI syntax for Info
+If you wish to refer to an Info file in a URI, you can use the
+(unofficial) syntax exemplified in the following. This works with
+Emacs/W3, for example:
address@hidden
+info:///usr/info/emacs#Dissociated%20Press
+info:emacs#Dissociated%20Press
+info://localhost/usr/info/emacs#Dissociated%20Press
address@hidden example
+
+The @command{info} program itself does not follow URI's of any kind.
+
+
address@hidden Printed Books
address@hidden Printed Books
address@hidden Printed book and manual characteristics
address@hidden Manual characteristics, printed
address@hidden Book characteristics, printed
address@hidden Texinfo printed book characteristics
address@hidden Characteristics, printed books or manuals
+
address@hidden Knuth, Donald
+A Texinfo file can be formatted and typeset as a printed book or manual.
+To do this, you need @TeX{}, a powerful, sophisticated typesetting
+program written by Donald address@hidden can also use the
address@hidden address@hidden, unsupported software}
address@hidden://tug.org/texi2roff.tar.gz, @code{texi2roff}} program if you
+do not have @TeX{}; since Texinfo is designed for use with @TeX{},
address@hidden is not described here. @code{texi2roff} is not part of
+the standard GNU distribution and is not maintained or up-to-date with
+all the Texinfo features described in this manual.}
+
+A Texinfo-based book is similar to any other typeset, printed work: it
+can have a title page, copyright page, table of contents, and preface,
+as well as chapters, numbered or unnumbered sections and subsections,
+page headers, cross references, footnotes, and address@hidden
+
+You can use Texinfo to write a book without ever having the intention
+of converting it into online information. You can use Texinfo for
+writing a printed novel, and even to write a printed memo, although
+this latter application is not recommended since electronic mail is so
+much address@hidden
+
address@hidden is a general purpose typesetting program. Texinfo provides a
+file @file{texinfo.tex} that contains information (definitions or
address@hidden) that @TeX{} uses when it typesets a Texinfo file.
+(@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands
+to @TeX{} commands, which @TeX{} can then process to create the typeset
+document.) @file{texinfo.tex} contains the specifications for printing
+a document. You can get the latest version of @file{texinfo.tex} from
address@hidden://ftp.gnu.org/gnu/texinfo.tex}.
+
+In the United States, documents are most often printed on 8.5 inch by 11
+inch pages (address@hidden by address@hidden); this is the default size. But
+you can also print for 7 inch by 9.25 inch pages (address@hidden by
address@hidden, the @code{@@smallbook} size; or on A4 or A5 size paper
+(@code{@@afourpaper}, @code{@@afivepaper}). (@xref{smallbook, ,
+Printing ``Small'' Books}. Also, see @ref{A4 Paper, ,Printing on A4
+Paper}.)
+
+By changing the parameters in @file{texinfo.tex}, you can change the
+size of the printed document. In addition, you can change the style in
+which the printed document is formatted; for example, you can change the
+sizes and fonts used, the amount of indentation for each paragraph, the
+degree to which words are hyphenated, and the like. By changing the
+specifications, you can make a book look dignified, old and serious, or
+light-hearted, young and cheery.
+
address@hidden is freely distributable. It is written in a superset 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.
+(@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information
+about @TeX{}.)@refill
+
address@hidden is very powerful and has a great many features. Because a
+Texinfo file must be able to present information both on a
+character-only terminal in Info form and in a typeset book, the
+formatting commands that Texinfo supports are necessarily limited.
+
+To get a copy of @TeX{}, see
address@hidden TeX, , How to Obtain @TeX{}}.
+
+
address@hidden Formatting Commands
address@hidden @@-commands
address@hidden @@-commands
address@hidden Formatting commands
+
+In a Texinfo file, the commands that tell @TeX{} how to typeset the
+printed manual and tell @code{makeinfo} and
address@hidden how to create an Info file are preceded
+by @samp{@@}; they are called @dfn{@@-commands}. For example,
address@hidden@@node} is the command to indicate a node and @code{@@chapter}
+is the command to indicate the start of a address@hidden
+
address@hidden
address@hidden note:} All the @@-commands, with the exception of the
address@hidden@@address@hidden@}} command, must be written entirely in lower
case.
address@hidden quotation
+
+The Texinfo @@-commands are a strictly limited set of constructs. The
+strict limits make it possible for Texinfo files to be understood both
+by @TeX{} and by the code that converts them into Info files. You can
+display Info files on any terminal that displays alphabetic and
+numeric characters. Similarly, you can print the output generated by
address@hidden on a wide variety of address@hidden
+
+Depending on what they do or what address@hidden word
address@hidden comes from the way it is used in mathematics and does not
+refer to a dispute between two people; it refers to the information
+presented to the command. According to the @cite{Oxford English
+Dictionary}, the word derives from the Latin for @dfn{to make clear,
+prove}; thus it came to mean `the evidence offered as proof', which is
+to say, `the information offered', which led to its mathematical
+meaning. In its other thread of derivation, the word came to mean `to
+assert in a manner against which others may make counter assertions',
+which led to the meaning of `argument' as a dispute.} they take, you
+need to write @@-commands on lines of their own or as part of
+sentences:
+
address@hidden @bullet
address@hidden
+Write a command such as @code{@@noindent} at the beginning of a line as
+the only text on the line. (@code{@@noindent} prevents the beginning of
+the next line from being indented as the beginning of a
+paragraph.)@refill
+
address@hidden
+Write a command such as @code{@@chapter} at the beginning of a line
+followed by the command's arguments, in this case the chapter title, on
+the rest of the line. (@code{@@chapter} creates chapter titles.)@refill
+
address@hidden
+Write a command such as @code{@@address@hidden@}} wherever you wish but usually
+within a sentence. (@code{@@address@hidden@}} creates dots @dots{})@refill
+
address@hidden
+Write a command such as @code{@@address@hidden@address@hidden wherever you
+wish (but usually within a sentence) with its argument,
address@hidden in this example, between the braces. (@code{@@code}
+marks text as being code.)@refill
+
address@hidden
+Write a command such as @code{@@example} on a line of its own; write the
+body-text on following lines; and write the matching @code{@@end}
+command, @code{@@end example} in this case, at the on a line of its own
+after the body-text. (@code{@@example} @dots{} @code{@@end example}
+indents and typesets body-text as an example.) It's usually ok to
+indent environment commands like this, but in complicated and
+hard-to-define circumstances the extra spaces cause extra space to
+appear in the output, so beware.
address@hidden itemize
+
address@hidden
address@hidden Braces, when to use
+As a general rule, a command requires braces if it mingles among other
+text; but it does not need braces if it starts a line of its own. The
+non-alphabetic commands, such as @code{@@:}, are exceptions to the rule;
+they do not need address@hidden
+
+As you gain experience with Texinfo, you will rapidly learn how to
+write the different commands: the different ways to write commands
+make it easier to write and read Texinfo files than if all commands
+followed exactly the same syntax. (For details about @@-command
+syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill
+
+
address@hidden Conventions
address@hidden General Syntactic Conventions
address@hidden General syntactic conventions
address@hidden Syntactic conventions
address@hidden Conventions, syntactic
+
+This section describes the general conventions used in all Texinfo documents.
+
address@hidden @bullet
address@hidden
+All printable @sc{ascii} characters except @samp{@@}, @address@hidden and
address@hidden@}} can appear in a Texinfo file and stand for themselves.
address@hidden@@} is the escape character which introduces commands, while
address@hidden@{} and @address@hidden are used to surround arguments to certain
+commands. To put one of these special characters into the document, put
+an @samp{@@} character in front of it, like this: @samp{@@@@},
address@hidden@@@{}, and @samp{@@@}}.
+
address@hidden
+It is customary in @TeX{} to use doubled single-quote characters to
+begin and end quotations: @address@hidden@address@hidden'@w{}'}}. This
+convention should be followed in Texinfo files. @TeX{} converts
+two single quotes to left- and right-hand doubled
+quotation marks,
address@hidden this comes out as "like this" in Info, of course, which is just
confusing.
+and Info converts doubled single-quote characters to @sc{ascii}
+double-quotes: @address@hidden@address@hidden'@w{}'}} becomes
@address@hidden"@dots{}"}}.
+
address@hidden
+Use three hyphens in a row, @samp{---}, for a dash---like this. In
address@hidden, a single or double hyphen produces a printed dash that is
+shorter than the usual typeset dash. Info reduces three hyphens to two
+for display on the screen.
+
address@hidden
+To prevent a paragraph from being indented in the printed manual, put
+the command @code{@@noindent} on a line by itself before the
+paragraph.
+
address@hidden
+If you mark off a region of the Texinfo file with the @code{@@iftex}
+and @address@hidden@@end iftex}} commands, that region will appear only in
+the printed copy; in that region, you can use certain commands
+borrowed from plain @TeX{} that you cannot use in Info. Conversely,
+text surrounded by @code{@@ifnottex} and @code{@@end ifnottex} will
+appear in all output formats @emph{except} @TeX{}.
+
+Each of the other output formats (@code{html}, @code{info},
address@hidden) have an analogous pair of commands. @xref{Conditionals}.
address@hidden itemize
+
address@hidden Tabs; don't use!
address@hidden
address@hidden:} Do not use tab characters in a Texinfo file (except in
+verbatim modes)! @TeX{} uses variable-width fonts, which means that it
+is impractical at best to define a tab to work in all circumstances.
+Consequently, @TeX{} treats tabs like single spaces, and that is not
+what they look like. Furthermore, @code{makeinfo} does nothing special
+with tabs, and thus a tab character in your input file may appear
+differently in the output, for example, in indented text.
+
address@hidden
+To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple
+spaces when you press the @key{TAB} key.
+
address@hidden
+Also, you can run @code{untabify} in Emacs to convert tabs in a region
+to multiple spaces.
address@hidden quotation
+
+
address@hidden Comments
address@hidden Comments
+
address@hidden Comments
address@hidden comment
address@hidden c @r{(comment)}
+
+You can write comments in a Texinfo file that will not appear in
+either the Info file or the printed manual by using the
address@hidden@@comment} command (which may be abbreviated to @code{@@c}).
+Such comments are for the person who revises the Texinfo file. All the
+text on a line that follows either @code{@@comment} or @code{@@c} is a
+comment; the rest of the line does not appear in either the Info file
+or the printed manual.
+
+Often, you can write the @code{@@comment} or @code{@@c} in the middle of
+a line, and only the text that follows after the @code{@@comment} or
address@hidden@@c} command does not appear; but some commands, such as
address@hidden@@settitle} and @code{@@setfilename}, work on a whole line. You
+cannot use @code{@@comment} or @code{@@c} in a line beginning with such
+a command.
+
address@hidden Ignored text
address@hidden Unprocessed text
address@hidden ignore
+You can write long stretches of text that will not appear in either
+the Info file or the printed manual by using the @code{@@ignore} and
address@hidden@@end ignore} commands. Write each of these commands on a line
+of its own, starting each command at the beginning of the line. Text
+between these two commands does not appear in the processed output.
+You can use @code{@@ignore} and @code{@@end ignore} for writing
+comments.
+
+Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or
address@hidden@@ifclear} conditions is ignored in the sense that it will not
+contribute to the formatted output. However, @TeX{} and makeinfo must
+still parse the ignored text, in order to understand when to @emph{stop}
+ignoring text from the source file; that means that you may still get
+error messages if you have invalid Texinfo commands within ignored text.
+
+
address@hidden Minimum
address@hidden What a Texinfo File Must Have
address@hidden Minimal Texinfo file (requirements)
address@hidden Must have in Texinfo file
address@hidden Required in Texinfo file
address@hidden Texinfo file minimum
+
+By convention, the namea of a Texinfo file ends with (in order of
+preference) one of the extensions @file{.texinfo}, @file{.texi},
address@hidden, or @file{.tex}. The longer extensions are preferred since
+they describe more clearly to a human reader the nature of the file.
+The shorter extensions are for operating systems that cannot handle long
+file names.
+
+In order to be made into a printed manual and an Info file, a Texinfo
+file @strong{must} begin with lines like this:
+
address@hidden
address@hidden
+\input texinfo
+@@setfilename @var{info-file-name}
+@@settitle @var{name-of-manual}
address@hidden group
address@hidden example
+
address@hidden
+The contents of the file follow this beginning, and then you
address@hidden end a Texinfo file with a line like this:
+
address@hidden
+@@bye
address@hidden example
+
address@hidden \input @r{(raw @TeX{} startup)}
address@hidden
+Here's an explanation:
+
address@hidden @bullet
address@hidden
+The @samp{\input texinfo} line tells @TeX{} to use the
address@hidden file, which tells @TeX{} how to translate the Texinfo
+@@-commands into @TeX{} typesetting commands. (Note the use of the
+backslash, @samp{\}; this is correct for @TeX{}.)
+
address@hidden
+The @code{@@setfilename} line provides a name for the Info file and
+tells @TeX{} to open auxiliary files. @strong{All text before
address@hidden@@setfilename} is ignored!}
+
address@hidden
+The @code{@@settitle} line specifies a title for the page headers (or
+footers) of the printed manual, and the default document description for
+the @samp{<head>} in HTML format. Strictly speaking, @code{@@settitle}
+is optional---if you don't mind your document being titled `Untitled'.
+
address@hidden
+The @code{@@bye} line at the end of the file on a line of its own tells
+the formatters that the file is ended and to stop formatting.
+
address@hidden itemize
+
+Typically, you will not use quite such a spare format, but will include
+mode setting and start-of-header and end-of-header lines at the
+beginning of a Texinfo file, like this:
+
address@hidden
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename @var{info-file-name}
+@@settitle @var{name-of-manual}
+@@c %**end of header
address@hidden group
address@hidden example
+
address@hidden
+In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into
+Texinfo mode when you edit the file.
+
+The @code{@@c} lines which surround the @code{@@setfilename} and
address@hidden@@settitle} lines are optional, but you need them in order to
+run @TeX{} or Info on just part of the file. (@xref{Start of Header}.)
+
+Furthermore, you will usually provide a Texinfo file with a title page,
+indices, and the like, all of which are explained in this manual. But
+the minimum, which can be useful for short documents, is just the three
+lines at the beginning and the one line at the end.
+
+
address@hidden Six Parts
address@hidden Six Parts of a Texinfo File
+
+Generally, a Texinfo file contains more than the minimal beginning and
+end described in the previous section---it usually contains the six
+parts listed below. These are described fully in the following sections.
+
address@hidden @r
address@hidden 1. Header
+The @dfn{Header} names the file, tells @TeX{} which definitions file to
+use, and other such housekeeping tasks.
+
address@hidden 2. Summary and Copyright
+The @dfn{Summary and Copyright} segment describes the document and
+contains the copyright notice and copying permissions. This is done
+with the @code{@@copying} command.
+
address@hidden 3. Title and Copyright
+The @dfn{Title and Copyright} segment contains the title and copyright
+pages for the printed manual. The segment must be enclosed between
address@hidden@@titlepage} and @code{@@end titlepage} commands. The title and
+copyright page appear only in the printed manual.
+
address@hidden 4. `Top' Node and Master Menu
+The `Top' node starts off the online output; it does not appear in the
+printed manual. We recommend including the copying permissions here as
+well as the segments above. And it contains at least a top-level menu
+listing the chapters, and possibly a @dfn{Master Menu} listing all the
+nodes in the entire document.
+
address@hidden 5. Body
+The @dfn{Body} of the document is typically structured like a
+traditional book or encyclopedia, but it may be free form.
+
address@hidden 6. End
+The @dfn{End} segment contains commands for printing indices and
+generating the table of contents, and the @code{@@bye} command on a line
+of its own.
address@hidden table
+
+
address@hidden Short Sample
address@hidden A Short Sample Texinfo File
address@hidden Sample Texinfo file, with comments
+
+Here is a very short but complete Texinfo file, in the six conventional
+parts enumerated in the previous section, so you can see how Texinfo
+source appears in practice. The first three parts of the file, from
address@hidden texinfo} through to @samp{@@end titlepage}, look more
+intimidating than they are: most of the material is standard
+boilerplate; when writing a manual, you simply change the names as
+appropriate.
+
address@hidden a File}, for full documentation on the commands listed
+here. @xref{GNU Sample Texts}, for the full texts to be used in GNU manuals.
+
+In the following, the sample text is @emph{indented}; comments on it are
+not. The complete file, without interspersed comments, is shown in
address@hidden Sample Texinfo File}.
+
address@hidden Part 1: Header
+
address@hidden
+The header does not appear in either the Info file or the
+printed output. It sets various parameters, including the
+name of the Info file and the title used in the header.
+
address@hidden
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename sample.info
+@@settitle Sample Manual 1.0
+@@c %**end of header
address@hidden group
address@hidden example
+
address@hidden Part 2: Summary Description and Copyright
+
address@hidden
+A real manual includes more text here, according to the license under
+which it is distributed. @xref{GNU Sample Texts}.
+
address@hidden
address@hidden
+@@copying
+This is a short example of a complete Texinfo file, version 1.0.
+
+Copyright @@address@hidden@} 2002 Free Software Foundation, Inc.
+@@end copying
address@hidden group
address@hidden example
+
address@hidden Part 3: Titlepage, Contents, Copyright
+
address@hidden
+The titlepage segment does not appear in the online output, only in the
+printed manual. We use the @code{@@insertcopying} command to
+include the permission text from the previous section, instead of
+writing it out again; it is output on the back of the title page. The
address@hidden@@contents} command generates a table of contents.
+
address@hidden
address@hidden
+@@titlepage
+@@title Sample Title
address@hidden group
+
address@hidden
+@@c The following two commands start the copyright page.
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
+@@end titlepage
address@hidden group
+
+@@c Output the table of contents at the beginning.
+@@contents
address@hidden example
+
address@hidden Part 4: `Top' Node and Master Menu
+
address@hidden
+The `Top' node contains the master menu for the Info file. Since a
+printed manual uses a table of contents rather than a menu, the master
+menu appears only in online output. We also include the copying text
+again for the benefit of online readers. And since the copying text
+begins with a brief description of the manual, no other text is needed.
+
address@hidden
address@hidden
+@@ifnottex
+@@node Top
+@@end ifnottex
address@hidden group
address@hidden example
+
address@hidden
address@hidden
+@@insertcopying
+
+@@menu
+* First Chapter:: The first chapter is the
+ only chapter in this sample.
+* Index:: Complete index.
+@@end menu
address@hidden group
address@hidden example
+
+
address@hidden Part 5: The Body of the Document
+
address@hidden
+The body segment contains all the text of the document, but not the
+indices or table of contents. This example illustrates a node and a
+chapter containing an enumerated list.
+
address@hidden
address@hidden
+@@node First Chapter
+@@chapter First Chapter
+
+@@cindex chapter, first
address@hidden group
+
address@hidden
+This is the first chapter.
+@@cindex index entry, another
address@hidden group
+
address@hidden
+Here is a numbered list.
+
+@@enumerate
+@@item
+This is the first item.
+
+@@item
+This is the second item.
+@@end enumerate
address@hidden group
address@hidden example
+
+
address@hidden Part 6: The End of the Document
+
address@hidden
+The end segment contains commands for generating an index in a node and
+unnumbered chapter of its own, and the @code{@@bye} command that marks
+the end of the document.
+
address@hidden
address@hidden
+@@node Index
+@@unnumbered Index
address@hidden group
+
address@hidden
+@@printindex cp
+
+@@bye
address@hidden group
address@hidden example
+
+
address@hidden Some Results
+
+Here is what the contents of the first chapter of the sample look like:
+
address@hidden 1
address@hidden 700
address@hidden
+This is the first chapter.
+
+Here is a numbered list.
+
address@hidden
address@hidden
+This is the first item.
+
address@hidden
+This is the second item.
address@hidden enumerate
address@hidden quotation
+
+
address@hidden History
address@hidden History
+
address@hidden Stallman, Richard M.
address@hidden Chassell, Robert J.
address@hidden Fox, Brian
address@hidden Berry, Karl
+Richard M.@: Stallman invented the Texinfo format, wrote the initial
+processors, and created Edition 1.0 of this manual. @w{Robert J.@:}
+Chassell greatly revised and extended the manual, starting with Edition
+1.1. Brian Fox was responsible for the standalone Texinfo distribution
+until version 3.8, and wrote the standalone @command{makeinfo} and
address@hidden programs. Karl Berry has continued maintenance since
+Texinfo 3.8 (manual edition 2.22).
+
address@hidden Pinard, Fran@,{c}ois
address@hidden Zuhn, David D.
address@hidden Weisshaus, Melissa
address@hidden Zaretskii, Eli
address@hidden Schwab, Andreas
address@hidden Weinberg, Zack
+Our thanks go out to all who helped improve this work, particularly the
+indefatigable Eli Zaretskii and Andreas Schwab, who have provided
+patches beyond counting. Fran@,{c}ois Pinard and @w{David D.@: Zuhn},
+tirelessly recorded and reported mistakes and obscurities. Zack
+Weinberg did the impossible by implementing the macro syntax in
address@hidden Special thanks go to Melissa Weisshaus for her
+frequent reviews of nearly similar editions. Dozens of others have
+contributed patches and suggestions, they are gratefully acknowledged in
+the @file{ChangeLog} file. Our mistakes are our own.
+
address@hidden Scribe
address@hidden Reid, Brian
address@hidden History of Texinfo
address@hidden Texinfo history
+A bit of history: in the 1970's at CMU, Brian Reid developed a program
+and format named Scribe to mark up documents for printing. It used the
address@hidden@@} character to introduce commands, as Texinfo does. Much more
+consequentially, it strived to describe document contents rather than
+formatting, an idea wholeheartedly adopted by Texinfo.
+
address@hidden Bolio
address@hidden address@hidden
+Meanwhile, people at MIT developed another, not too dissimilar format
+called Bolio. This then was converted to using @TeX{} as its typesetting
+language: address@hidden The earliest address@hidden version seems to have
been
+0.02 on October 31, 1984.
+
address@hidden could only be used as a markup language for documents to be
+printed, not for online documents. Richard Stallman (RMS) worked on
+both Bolio and address@hidden He also developed a nifty on-line help format
+called Info, and then combined address@hidden and Info to create Texinfo, a
+mark up language for text that is intended to be read both online and
+as printed hard copy.
+
+
address@hidden Texinfo Mode
address@hidden Using Texinfo Mode
address@hidden Texinfo mode
address@hidden Mode, using Texinfo
address@hidden GNU Emacs
address@hidden Emacs
+
+You may edit a Texinfo file with any text editor you choose. A Texinfo
+file is no different from any other @sc{ascii} file. However, GNU Emacs
+comes with a special mode, called Texinfo mode, that provides Emacs
+commands and tools to help ease your work.
+
+This chapter describes features of GNU Emacs' Texinfo mode but not any
+features of the Texinfo formatting language. So if you are reading this
+manual straight through from the beginning, you may want to skim through
+this chapter briefly and come back to it after reading succeeding
+chapters which describe the Texinfo formatting language in detail.
+
address@hidden
+* 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.
address@hidden menu
+
address@hidden Texinfo Mode Overview, Emacs Editing, Texinfo Mode, Texinfo Mode
address@hidden Texinfo Mode Overview
+
+Texinfo mode provides special features for working with Texinfo
+files.
+You can:@refill
+
address@hidden @bullet
address@hidden
+Insert frequently used @@-commands. @refill
+
address@hidden
+Automatically create @code{@@node} lines.
+
address@hidden
+Show the structure of a Texinfo source address@hidden
+
address@hidden
+Automatically create or update the `Next',
+`Previous', and `Up' pointers of a node.
+
address@hidden
+Automatically create or update address@hidden
+
address@hidden
+Automatically create a master address@hidden
+
address@hidden
+Format a part or all of a file for address@hidden
+
address@hidden
+Typeset and print part or all of a address@hidden
address@hidden itemize
+
+Perhaps the two most helpful features are those for inserting frequently
+used @@-commands and for creating node pointers and address@hidden
+
address@hidden Emacs Editing, Inserting, Texinfo Mode Overview, Texinfo Mode
address@hidden The Usual GNU Emacs Editing Commands
+
+In most cases, the usual Text mode commands work the same in Texinfo
+mode as they do in Text mode. Texinfo mode adds new editing commands
+and tools to GNU Emacs' general purpose editing features. The major
+difference concerns filling. In Texinfo mode, the paragraph
+separation variable and syntax table are redefined so that Texinfo
+commands that should be on lines of their own are not inadvertently
+included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph})
+command will refill a paragraph but not mix an indexing command on a
+line adjacent to it into the address@hidden
+
+In addition, Texinfo mode sets the @code{page-delimiter} variable to
+the value of @code{texinfo-chapter-level-regexp}; by default, this is
+a regular expression matching the commands for chapters and their
+equivalents, such as appendices. With this value for the page
+delimiter, you can jump from chapter title to chapter title with the
address@hidden ]} (@code{forward-page}) and @kbd{C-x [}
+(@code{backward-page}) commands and narrow to a chapter with the
address@hidden p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs,
+The GNU Emacs Manual}, for details about the page commands.)@refill
+
+You may name a Texinfo file however you wish, but the convention is to
+end a Texinfo file name with one of the extensions
address@hidden, @file{.texi}, @file{.txi}, or @file{.tex}. A longer
+extension is preferred, since it is explicit, but a shorter extension
+may be necessary for operating systems that limit the length of file
+names. GNU Emacs automatically enters Texinfo mode when you visit a
+file with a @file{.texinfo}, @file{.texi} or @file{.txi}
+extension. Also, Emacs switches to Texinfo mode
+when you visit a
+file that has @samp{-*-texinfo-*-} in its first line. If ever you are
+in another mode and wish to switch to Texinfo mode, type @code{M-x
address@hidden
+
+Like all other Emacs features, you can customize or enhance Texinfo
+mode as you wish. In particular, the keybindings are very easy to
+change. The keybindings described here are the default or standard
address@hidden
+
address@hidden Inserting, Showing the Structure, Emacs Editing, Texinfo Mode
address@hidden node-name, next, previous, up
address@hidden Inserting Frequently Used Commands
address@hidden Inserting frequently used commands
address@hidden Frequently used commands, inserting
address@hidden Commands, inserting them
+
+Texinfo mode provides commands to insert various frequently used
+@@-commands into the buffer. You can use these commands to save
address@hidden
+
+The insert commands are invoked by typing @kbd{C-c} twice and then the
+first letter of the @@-command:@refill
+
address@hidden @kbd
address@hidden C-c C-c c
address@hidden M-x texinfo-insert-@@code
address@hidden texinfo-insert-@@code
+Insert @code{@@address@hidden@}} and put the
+cursor between the address@hidden
+
address@hidden C-c C-c d
address@hidden M-x texinfo-insert-@@dfn
address@hidden texinfo-insert-@@dfn
+Insert @code{@@address@hidden@}} and put the
+cursor between the address@hidden
+
address@hidden C-c C-c e
address@hidden M-x texinfo-insert-@@end
address@hidden texinfo-insert-@@end
+Insert @code{@@end} and attempt to insert the correct following word,
+such as @samp{example} or @samp{table}. (This command does not handle
+nested lists correctly, but inserts the word appropriate to the
+immediately preceding list.)@refill
+
address@hidden C-c C-c i
address@hidden M-x texinfo-insert-@@item
address@hidden texinfo-insert-@@item
+Insert @code{@@item} and put the
+cursor at the beginning of the next address@hidden
+
address@hidden C-c C-c k
address@hidden M-x texinfo-insert-@@kbd
address@hidden texinfo-insert-@@kbd
+Insert @code{@@address@hidden@}} and put the
+cursor between the address@hidden
+
address@hidden C-c C-c n
address@hidden M-x texinfo-insert-@@node
address@hidden texinfo-insert-@@node
+Insert @code{@@node} and a comment line
+listing the sequence for the `Next',
+`Previous', and `Up' nodes.
+Leave point after the @code{@@address@hidden
+
address@hidden C-c C-c o
address@hidden M-x texinfo-insert-@@noindent
address@hidden texinfo-insert-@@noindent
+Insert @code{@@noindent} and put the
+cursor at the beginning of the next address@hidden
+
address@hidden C-c C-c s
address@hidden M-x texinfo-insert-@@samp
address@hidden texinfo-insert-@@samp
+Insert @code{@@address@hidden@}} and put the
+cursor between the address@hidden
+
address@hidden C-c C-c t
address@hidden M-x texinfo-insert-@@table
address@hidden texinfo-insert-@@table
+Insert @code{@@table} followed by a @key{SPC}
+and leave the cursor after the @address@hidden
+
address@hidden C-c C-c v
address@hidden M-x texinfo-insert-@@var
address@hidden texinfo-insert-@@var
+Insert @code{@@address@hidden@}} and put the
+cursor between the address@hidden
+
address@hidden C-c C-c x
address@hidden M-x texinfo-insert-@@example
address@hidden texinfo-insert-@@example
+Insert @code{@@example} and put the
+cursor at the beginning of the next address@hidden
+
address@hidden address@hidden was the binding for texinfo-insert-braces;
address@hidden in Emacs 19, backward-paragraph will take this binding.
address@hidden C-c C-c @{
address@hidden M-x texinfo-insert-braces
address@hidden texinfo-insert-braces
+Insert @address@hidden@}} and put the cursor between the address@hidden
+
address@hidden C-c C-c @}
address@hidden C-c C-c ]
address@hidden M-x up-list
address@hidden up-list
+Move from between a pair of braces forward past the closing brace.
+Typing @kbd{C-c C-c ]} is easier than typing @kbd{C-c C-c @}}, which
+is, however, more mnemonic; hence the two keybindings. (Also, you can
+move out from between braces by typing @kbd{C-f}.)@refill
address@hidden table
+
+To put a command such as @address@hidden@@address@hidden@address@hidden around
an
address@hidden word, position the cursor in front of the word and type
address@hidden 1 C-c C-c c}. This makes it easy to edit existing plain text.
+The value of the prefix argument tells Emacs how many words following
+point to include between address@hidden for one word, @samp{2} for
+two words, and so on. Use a negative argument to enclose the previous
+word or words. If you do not specify a prefix argument, Emacs inserts
+the @@-command string and positions the cursor between the braces. This
+feature works only for those @@-commands that operate on a word or words
+within one line, such as @code{@@kbd} and @code{@@address@hidden
+
+This set of insert commands was created after analyzing the frequency
+with which different @@-commands are 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 @address@hidden
+
address@hidden texinfo-start-menu-description
address@hidden Menu description, start
address@hidden Description for menu, start
address@hidden C-c C-d} (@code{texinfo-start-menu-description}) is an insert
+command that works differently from the other insert commands. It
+inserts a node's section or chapter title in the space for the
+description in a menu entry line. (A menu entry has three parts, the
+entry name, the node name, and the description. Only the node name is
+required, but a description helps explain what the node is about.
address@hidden Parts, , The Parts of a Menu}.)@refill
+
+To use @code{texinfo-start-menu-description}, position point in a menu
+entry line and type @kbd{C-c C-c C-d}. The command looks for and copies
+the title that goes with the node name, and inserts the title as a
+description; it positions point at beginning of the inserted text so you
+can edit it. The function does not insert the title if the menu entry
+line already contains a address@hidden
+
+This command is only an aid to writing descriptions; it does not do the
+whole job. You must edit the inserted text since a title tends to use
+the same words as a node name but a useful description uses different
address@hidden
+
address@hidden Showing the Structure, Updating Nodes and Menus, Inserting,
Texinfo Mode
address@hidden node-name, next, previous, up
address@hidden Showing the Section Structure of a File
address@hidden Showing the section structure of a file
address@hidden Section structure of a file, showing it
address@hidden Structure of a file, showing it
address@hidden Outline of file structure, showing it
address@hidden Contents-like outline of file structure
address@hidden File section structure, showing it
address@hidden Texinfo file section structure, showing it
+
+You can show the section structure of a Texinfo file by using the
address@hidden C-s} command (@code{texinfo-show-structure}). This command
+shows the section structure of a Texinfo file by listing the lines
+that begin with the @@-commands for @code{@@chapter},
address@hidden@@section}, and the like. It constructs what amounts
+to a table of contents. These lines are displayed in another buffer
+called the @samp{*Occur*} buffer. In that buffer, 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 address@hidden
+
address@hidden @kbd
address@hidden C-c C-s
address@hidden M-x texinfo-show-structure
address@hidden texinfo-show-structure
+Show the @code{@@chapter}, @code{@@section}, and such lines of a
+Texinfo address@hidden
+
address@hidden C-c C-c
address@hidden M-x occur-mode-goto-occurrence
address@hidden occur-mode-goto-occurrence
+Go to the line in the Texinfo file corresponding to the line under the
+cursor in the @file{*Occur*} address@hidden
address@hidden table
+
+If you call @code{texinfo-show-structure} with a prefix argument by
+typing @address@hidden C-c C-s}}, it will list not only those lines with the
+@@-commands for @code{@@chapter}, @code{@@section}, and the like, but
+also the @code{@@node} lines. You can use @code{texinfo-show-structure}
+with a prefix argument to check whether the `Next', `Previous', and `Up'
+pointers of an @code{@@node} line are correct.
+
+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 by using the
address@hidden n n} (@code{narrow-to-region}) command and
address@hidden will work on only that region. To see
+the whole buffer again, use @address@hidden n w}} (@code{widen}).
+(@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more
+information about the narrowing commands.)@refill
+
address@hidden page-delimiter
address@hidden Page delimiter in Texinfo mode
+In addition to providing the @code{texinfo-show-structure} command,
+Texinfo mode sets the value of the page delimiter variable to match
+the chapter-level @@-commands. This enables you to use the @kbd{C-x
+]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page})
+commands to move forward and backward by chapter, and to use the
address@hidden p} (@code{narrow-to-page}) command to narrow to a chapter.
address@hidden, , , emacs, The GNU Emacs Manual}, for more information
+about the page address@hidden
+
address@hidden Updating Nodes and Menus, Info Formatting, Showing the
Structure, Texinfo Mode
address@hidden node-name, next, previous, up
address@hidden Updating Nodes and Menus
address@hidden Updating nodes and menus
address@hidden Create nodes, menus automatically
address@hidden Insert nodes, menus automatically
address@hidden Automatically insert nodes, menus
+
+Texinfo mode provides commands for automatically creating or updating
+menus and node pointers. The commands are called ``update'' commands
+because their most frequent use is for updating a Texinfo file after you
+have worked on it; but you can use them to insert the `Next',
+`Previous', and `Up' pointers into an @code{@@node} line that has none
+and to create menus in a file that has none.
+
+If you do not use the updating commands, you need to write menus and
+node pointers by hand, which is a tedious address@hidden
+
address@hidden
+* 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.
address@hidden menu
+
address@hidden Updating Commands, Updating Requirements, Updating Nodes and
Menus, Updating Nodes and Menus
address@hidden The Updating Commands
+
+You can use the updating commands to:@refill
+
address@hidden @bullet
address@hidden
+insert or update the `Next', `Previous', and `Up' pointers of a
+node,@refill
+
address@hidden
+insert or update the menu for a section, address@hidden
+
address@hidden
+create a master menu for a Texinfo source address@hidden
address@hidden itemize
+
+You can also use the commands to update all the nodes and menus in a
+region or in a whole Texinfo address@hidden
+
+The updating commands work only with conventional Texinfo files, which
+are structured hierarchically like books. In such files, a structuring
+command line must follow closely after each @code{@@node} line, except
+for the `Top' @code{@@node} line. (A @dfn{structuring command line} is
+a line beginning with @code{@@chapter}, @code{@@section}, or other
+similar command.)
+
+You can write the structuring command line on the line that follows
+immediately after an @code{@@node} line or else on the line that
+follows after a single @code{@@comment} line or a single
address@hidden@@ifinfo} line. You cannot interpose more than one line between
+the @code{@@node} line and the structuring command line; and you may
+interpose only an @code{@@comment} line or an @code{@@ifinfo} line.
+
+Commands which work on a whole buffer require that the `Top' node be
+followed by a node with an @code{@@chapter} or equivalent-level command.
+The menu updating commands will not create a main or master menu for a
+Texinfo file that has only @code{@@chapter}-level nodes! The menu
+updating commands only create menus @emph{within} nodes for lower level
+nodes. To create a menu of chapters, you must provide a `Top'
+node.
+
+The menu updating commands remove menu entries that refer to other Info
+files since they do not refer to nodes within the current buffer. This
+is a deficiency. Rather than use menu entries, you can use cross
+references to refer to other Info files. None of the updating commands
+affect cross address@hidden
+
+Texinfo mode has five updating commands that are used most often: two
+are for updating the node pointers or menu of a single node (or a
+region); two are for updating every node pointer and menu in a file;
+and one, the @code{texinfo-master-menu} command, is for creating a
+master menu for a complete file, and optionally, for updating every
+node and menu in the whole Texinfo address@hidden
+
+The @code{texinfo-master-menu} command is the primary command:@refill
+
address@hidden @kbd
address@hidden C-c C-u m
address@hidden M-x texinfo-master-menu
address@hidden texinfo-master-menu
+Create or update a master menu that includes all the other menus
+(incorporating the descriptions from pre-existing menus, if
+any)address@hidden
+
+With an argument (prefix argument, @kbd{C-u,} if interactive), first create or
+update all the nodes and all the regular menus in the buffer before
+constructing the master menu. (@xref{The Top Node, , The Top Node and
+Master Menu}, for more about a master menu.)@refill
+
+For @code{texinfo-master-menu} to work, the Texinfo file must have a
+`Top' node and at least one subsequent address@hidden
+
+After extensively editing a Texinfo file, you can type the following:
+
address@hidden
+C-u M-x texinfo-master-menu
address@hidden or
+C-u C-c C-u m
address@hidden example
+
address@hidden
+This updates all the nodes and menus completely and all at address@hidden
address@hidden table
+
+The other major updating commands do smaller jobs and are designed for
+the person who updates nodes and menus as he or she writes a Texinfo
address@hidden
+
address@hidden 1000
+The commands are:@refill
+
address@hidden @kbd
address@hidden C-c C-u C-n
address@hidden M-x texinfo-update-node
address@hidden texinfo-update-node
+Insert the `Next', `Previous', and `Up' pointers for the node that point is
+within (i.e., for the @code{@@node} line preceding point). If the
address@hidden@@node} line has pre-existing `Next', `Previous', or `Up'
+pointers in it, the old pointers are removed and new ones inserted.
+With an argument (prefix argument, @kbd{C-u}, if interactive), this command
+updates all @code{@@node} lines in the region (which is the text
+between point and mark)address@hidden
+
address@hidden C-c C-u C-m
address@hidden M-x texinfo-make-menu
address@hidden texinfo-make-menu
+Create or update the menu in the node that point is within.
+With an argument (@kbd{C-u} as prefix argument, if
+interactive), the command makes or updates menus for the
+nodes which are either within or a part of the
address@hidden
+
+Whenever @code{texinfo-make-menu} updates an existing menu, the
+descriptions from that menu are incorporated into the new menu. This
+is done by copying descriptions from the existing menu to the entries
+in the new menu that have the same node names. If the node names are
+different, the descriptions are not copied to the new address@hidden
+
address@hidden C-c C-u C-e
address@hidden M-x texinfo-every-node-update
address@hidden texinfo-every-node-update
+Insert or update the `Next', `Previous', and `Up' pointers for every
+node in the address@hidden
+
address@hidden C-c C-u C-a
address@hidden M-x texinfo-all-menus-update
address@hidden texinfo-all-menus-update
+Create or update all the menus in the buffer. With an argument
+(@kbd{C-u} as prefix argument, if interactive), first insert
+or update all the node
+pointers before working on the address@hidden
+
+If a master menu exists, the @code{texinfo-all-menus-update} command
+updates it; but the command does not create a new master menu if none
+already exists. (Use the @code{texinfo-master-menu} command for
+that.)@refill
+
+When working on a document that does not merit a master menu, you can
+type the following:
+
address@hidden
+C-u C-c C-u C-a
address@hidden or
+C-u M-x texinfo-all-menus-update
address@hidden example
+
address@hidden
+This updates all the nodes and address@hidden
address@hidden table
+
+The @code{texinfo-column-for-description} variable specifies the
+column to which menu descriptions are indented. By default, the value
+is 32 although it is often useful to reduce it to as low as 24. You
+can set the variable with the @kbd{M-x edit-options} command
+(@pxref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs
+Manual}) or with the @kbd{M-x set-variable} command (@pxref{Examining,
+, Examining and Setting Variables, emacs, The GNU Emacs
+Manual})address@hidden
+
+Also, the @code{texinfo-indent-menu-description} command may be used to
+indent existing menu descriptions to a specified column. Finally, if
+you wish, you can use the @code{texinfo-insert-node-lines} command to
+insert missing @code{@@node} lines into a file. (@xref{Other Updating
+Commands}, for more information.)@refill
+
address@hidden Updating Requirements
address@hidden Updating Requirements
address@hidden Updating requirements
address@hidden Requirements for updating commands
+
+To use the updating commands, you must organize the Texinfo file
+hierarchically with chapters, sections, subsections, and the like.
+When you construct the hierarchy of the manual, do not `jump down'
+more than one level at a time: you can follow the `Top' node with a
+chapter, but not with a section; you can follow a chapter with a
+section, but not with a subsection. However, you may `jump up' any
+number of levels at one time---for example, from a subsection to a
address@hidden
+
+Each @code{@@node} line, with the exception of the line for the `Top'
+node, must be followed by a line with a structuring command such as
address@hidden@@chapter}, @code{@@section}, or
address@hidden@@address@hidden
+
+Each @code{@@node} line/structuring-command line combination
+must look either like this:
+
address@hidden
address@hidden
+@@node Comments, Minimum, Conventions, Overview
+@@comment node-name, next, previous, up
+@@section Comments
address@hidden group
address@hidden example
+
+or like this (without the @code{@@comment} line):
+
address@hidden
address@hidden
+@@node Comments, Minimum, Conventions, Overview
+@@section Comments
address@hidden group
address@hidden example
+
+or like this (without the explicit node pointers):
+
address@hidden
address@hidden
+@@node Comments
+@@section Comments
address@hidden group
address@hidden example
+
address@hidden
+In this example, `Comments' is the name of both the node and the
+section. The next node is called `Minimum' and the previous node is
+called `Conventions'. The `Comments' section is within the `Overview'
+node, which is specified by the `Up' pointer. (Instead of an
address@hidden@@comment} line, you may also write an @code{@@ifinfo} line.)
+
+If a file has a `Top' node, it must be called @samp{top} or @samp{Top}
+and be the first node in the file.
+
+The menu updating commands create a menu of sections within a chapter,
+a menu of subsections within a section, and so on. This means that
+you must have a `Top' node if you want a menu of address@hidden
+
+Incidentally, the @code{makeinfo} command will create an Info file for a
+hierarchically organized Texinfo file that lacks `Next', `Previous' and
+`Up' pointers. Thus, if you can be sure that your Texinfo file will be
+formatted with @code{makeinfo}, you have no need for the update node
+commands. (@xref{Creating an Info File}, for more information about
address@hidden) However, both @code{makeinfo} and the
address@hidden@dots{}} commands require that you insert menus in
+the file.
+
+
address@hidden Other Updating Commands
address@hidden Other Updating Commands
+
+In addition to the five major updating commands, Texinfo mode
+possesses several less frequently used updating commands:@refill
+
address@hidden @kbd
address@hidden M-x texinfo-insert-node-lines
address@hidden texinfo-insert-node-lines
+Insert @code{@@node} lines before the @code{@@chapter},
address@hidden@@section}, and other sectioning commands wherever they are
+missing throughout a region in a Texinfo address@hidden
+
+With an argument (@kbd{C-u} as prefix argument, if interactive), the
address@hidden command not only inserts
address@hidden@@node} lines but also inserts the chapter or section titles as
+the names of the corresponding nodes. In addition, it inserts the
+titles as node names in pre-existing @code{@@node} lines that lack
+names. Since node names should be more concise than section or
+chapter titles, you must manually edit node names so address@hidden
+
+For example, the following marks a whole buffer as a region and inserts
address@hidden@@node} lines and titles throughout:@refill
+
address@hidden
+C-x h C-u M-x texinfo-insert-node-lines
address@hidden example
+
+This command inserts titles as node names in @code{@@node} lines; the
address@hidden command (@pxref{Inserting,
+Inserting Frequently Used Commands}) inserts titles as descriptions in
+menu entries, a different action. However, in both cases, you need to
+edit the inserted text.
+
address@hidden M-x texinfo-multiple-files-update
address@hidden texinfo-multiple-files-update @r{(in brief)}
+Update nodes and menus in a document built from several separate files.
+With @kbd{C-u} as a prefix argument, create and insert a master menu in
+the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first
+update all the menus and all the `Next', `Previous', and `Up' pointers
+of all the included files before creating and inserting a master menu in
+the outer file. The @code{texinfo-multiple-files-update} command is
+described in the appendix on @code{@@include} files.
address@hidden@refill
+
address@hidden M-x texinfo-indent-menu-description
address@hidden texinfo-indent-menu-description
+Indent every description in the menu following point to the specified
+column. You can use this command to give yourself more space for
+descriptions. With an argument (@kbd{C-u} as prefix argument, if
+interactive), the @code{texinfo-indent-menu-description} command indents
+every description in every menu in the region. However, this command
+does not indent the second and subsequent lines of a multi-line
address@hidden
+
address@hidden M-x texinfo-sequential-node-update
address@hidden texinfo-sequential-node-update
+Insert the names of the nodes immediately following and preceding the
+current node as the `Next' or `Previous' pointers regardless of those
+nodes' hierarchical level. This means that the `Next' node of a
+subsection may well be the next chapter. Sequentially ordered nodes are
+useful for novels and other documents that you read through
+sequentially. (However, in Info, the @kbd{g *} command lets
+you look through the file sequentially, so sequentially ordered nodes
+are not strictly necessary.) With an argument (prefix argument, if
+interactive), the @code{texinfo-sequential-node-update} command
+sequentially updates all the nodes in the address@hidden
address@hidden table
+
address@hidden Info Formatting, Printing, Updating Nodes and Menus, Texinfo Mode
address@hidden node-name, next, previous, up
address@hidden Formatting for Info
address@hidden Formatting for Info
address@hidden Running an Info formatter
address@hidden Info formatting
+
+Texinfo mode provides several commands for formatting part or all of a
+Texinfo file for Info. Often, when you are writing a document, you
+want to format only part of a file---that is, a address@hidden
+
+You can use either the @code{texinfo-format-region} or the
address@hidden command to format a region:@refill
+
address@hidden @kbd
address@hidden texinfo-format-region
address@hidden C-c C-e C-r
address@hidden M-x texinfo-format-region
address@hidden C-c C-m C-r
address@hidden M-x makeinfo-region
+Format the current region for address@hidden
address@hidden table
+
+You can use either the @code{texinfo-format-buffer} or the
address@hidden command to format a whole buffer:@refill
+
address@hidden @kbd
address@hidden texinfo-format-buffer
address@hidden C-c C-e C-b
address@hidden M-x texinfo-format-buffer
address@hidden C-c C-m C-b
address@hidden M-x makeinfo-buffer
+Format the current buffer for address@hidden
address@hidden table
+
address@hidden 1000
+For example, after writing a Texinfo file, you can type the following:
+
address@hidden
+C-u C-c C-u m
address@hidden or
+C-u M-x texinfo-master-menu
address@hidden example
+
address@hidden
+This updates all the nodes and menus. Then type the following to create
+an Info file:
+
address@hidden
+C-c C-m C-b
address@hidden or
+M-x makeinfo-buffer
address@hidden example
+
+For @TeX{} or the Info formatting commands to work, the file @emph{must}
+include a line that has @code{@@setfilename} in its header.
+
address@hidden an Info File}, for details about Info address@hidden
+
address@hidden Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode
address@hidden node-name, next, previous, up
address@hidden Formatting and Printing
address@hidden Formatting for printing
address@hidden Printing a region or buffer
address@hidden Region formatting and printing
address@hidden Buffer formatting and printing
address@hidden Part of file formatting and printing
+
+Typesetting and printing a Texinfo file is a multi-step process in which
+you first create a file for printing (called a DVI file), and then
+print the file. Optionally, you may also create indices. To do this,
+you must run the @code{texindex} command after first running the
address@hidden typesetting command; and then you must run the @code{tex}
+command again. Or else run the @code{texi2dvi} command which
+automatically creates indices as needed (@pxref{Format with texi2dvi}).
+
+Often, when you are writing a document, you want to typeset and print
+only part of a file to see what it will look like. You can use the
address@hidden and related commands for this purpose. Use
+the @code{texinfo-tex-buffer} command to format all of a
address@hidden
+
address@hidden @kbd
address@hidden C-c C-t C-b
address@hidden M-x texinfo-tex-buffer
address@hidden texinfo-tex-buffer
+Run @code{texi2dvi} on the buffer. In addition to running @TeX{} on the
+buffer, this command automatically creates or updates indices as
address@hidden
+
address@hidden C-c C-t C-r
address@hidden M-x texinfo-tex-region
address@hidden texinfo-tex-region
+Run @TeX{} on the address@hidden
+
address@hidden C-c C-t C-i
address@hidden M-x texinfo-texindex
+Run @code{texindex} to sort the indices of a Texinfo file formatted with
address@hidden The @code{texinfo-tex-region} command does
+not run @code{texindex} automatically; it only runs the @code{tex}
+typesetting command. You must run the @code{texinfo-tex-region} command
+a second time after sorting the raw index files with the @code{texindex}
+command. (Usually, you do not format an index when you format a region,
+only when you format a buffer. Now that the @code{texi2dvi} command
+exists, there is little or no need for this command.)@refill
+
address@hidden C-c C-t C-p
address@hidden M-x texinfo-tex-print
address@hidden texinfo-tex-print
+Print the file (or the part of the file) previously formatted with
address@hidden or @address@hidden
address@hidden table
+
+For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the
+file @emph{must} start with a @samp{\input texinfo} line and must
+include an @code{@@settitle} line. The file must end with @code{@@bye}
+on a line by itself. (When you use @code{texinfo-tex-region}, you must
+surround the @code{@@settitle} line with start-of-header and
+end-of-header lines.)@refill
+
address@hidden, for a description of the other @TeX{} related
+commands, such as @address@hidden
+
address@hidden Texinfo Mode Summary, , Printing, Texinfo Mode
address@hidden node-name, next, previous, up
address@hidden Texinfo Mode Summary
+
+In Texinfo mode, each set of commands has default keybindings that
+begin with the same keys. All the commands that are custom-created
+for Texinfo mode begin with @kbd{C-c}. The keys are somewhat
address@hidden
+
address@hidden Insert Commands
+
+The insert commands are invoked by typing @kbd{C-c} twice and then the
+first letter of the @@-command to be inserted. (It might make more
+sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but
address@hidden C-c} is quick to type.)@refill
+
address@hidden
+C-c C-c c @r{Insert} @samp{@@code}.
+C-c C-c d @r{Insert} @samp{@@dfn}.
+C-c C-c e @r{Insert} @samp{@@end}.
+C-c C-c i @r{Insert} @samp{@@item}.
+C-c C-c n @r{Insert} @samp{@@node}.
+C-c C-c s @r{Insert} @samp{@@samp}.
+C-c C-c v @r{Insert} @samp{@@var}.
+C-c C-c @{ @r{Insert braces.}
+C-c C-c ]
+C-c C-c @} @r{Move out of enclosing braces.}
+
address@hidden
+C-c C-c C-d @r{Insert a node's section title}
+ @r{in the space for the description}
+ @r{in a menu entry line.}
address@hidden group
address@hidden example
+
address@hidden Show Structure
+
+The @code{texinfo-show-structure} command is often used within a
+narrowed address@hidden
+
address@hidden
+C-c C-s @r{List all the headings.}
address@hidden example
+
address@hidden The Master Update Command
+
+The @code{texinfo-master-menu} command creates a master menu; and can
+be used to update every node and menu in a file as address@hidden
+
address@hidden Probably should use @tables in this section.
address@hidden
address@hidden
+C-c C-u m
+M-x texinfo-master-menu
+ @r{Create or update a master menu.}
address@hidden group
+
address@hidden
+C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first}
+ @r{create or update all nodes and regular}
+ @r{menus, and then create a master menu.}
address@hidden group
address@hidden example
+
address@hidden Update Pointers
+
+The update pointer commands are invoked by typing @kbd{C-c C-u} and
+then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for
address@hidden@refill
+
address@hidden
+C-c C-u C-n @r{Update a node.}
+C-c C-u C-e @r{Update every node in the buffer.}
address@hidden example
+
address@hidden Update Menus
+
+Invoke the update menu commands by typing @kbd{C-c C-u}
+and then either @kbd{C-m} for @code{texinfo-make-menu} or
address@hidden for @code{texinfo-all-menus-update}. To update
+both nodes and menus at the same time, precede @kbd{C-c C-u
+C-a} with @address@hidden
+
address@hidden
+C-c C-u C-m @r{Make or update a menu.}
+
address@hidden
+C-c C-u C-a @r{Make or update all}
+ @r{menus in a buffer.}
address@hidden group
+
address@hidden
+C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,}
+ @r{first create or update all nodes and}
+ @r{then create or update all menus.}
address@hidden group
address@hidden example
+
address@hidden Format for Info
+
+The Info formatting commands that are written in Emacs Lisp are
+invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region
+or @kbd{C-b} for the whole address@hidden
+
+The Info formatting commands that are written in C and based on the
address@hidden program are invoked by typing @kbd{C-c C-m} and then
+either @kbd{C-r} for a region or @kbd{C-b} for the whole address@hidden
+
address@hidden 800
address@hidden
+Use the @address@hidden commands:
+
address@hidden
address@hidden
+C-c C-e C-r @r{Format the region.}
+C-c C-e C-b @r{Format the buffer.}
address@hidden group
address@hidden example
+
address@hidden 750
address@hidden
+Use @code{makeinfo}:
+
address@hidden
+C-c C-m C-r @r{Format the region.}
+C-c C-m C-b @r{Format the buffer.}
+C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.}
+C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.}
address@hidden example
+
address@hidden Typeset and Print
+
+The @TeX{} typesetting and printing commands are invoked by typing
address@hidden C-t} and then another control command: @kbd{C-r} for
address@hidden, @kbd{C-b} for @code{texinfo-tex-buffer},
+and so address@hidden
+
address@hidden
+C-c C-t C-r @r{Run @TeX{} on the region.}
+C-c C-t C-b @r{Run} @code{texi2dvi} @r{on the buffer.}
+C-c C-t C-i @r{Run} @code{texindex}.
+C-c C-t C-p @r{Print the DVI file.}
+C-c C-t C-q @r{Show the print queue.}
+C-c C-t C-d @r{Delete a job from the print queue.}
+C-c C-t C-k @r{Kill the current @TeX{} formatting job.}
+C-c C-t C-x @r{Quit a currently stopped @TeX{} formatting job.}
+C-c C-t C-l @r{Recenter the output buffer.}
address@hidden example
+
address@hidden Other Updating Commands
+
+The remaining updating commands do not have standard keybindings because
+they are rarely used.
+
address@hidden
address@hidden
+M-x texinfo-insert-node-lines
+ @r{Insert missing @code{@@node} lines in region.}
+ @r{With @kbd{C-u} as a prefix argument,}
+ @r{use section titles as node names.}
address@hidden group
+
address@hidden
+M-x texinfo-multiple-files-update
+ @r{Update a multi-file document.}
+ @r{With @kbd{C-u 2} as a prefix argument,}
+ @r{create or update all nodes and menus}
+ @r{in all included files first.}
address@hidden group
+
address@hidden
+M-x texinfo-indent-menu-description
+ @r{Indent descriptions.}
address@hidden group
+
address@hidden
+M-x texinfo-sequential-node-update
+ @r{Insert node pointers in strict sequence.}
address@hidden group
address@hidden example
+
+
address@hidden Beginning a File
address@hidden Beginning a Texinfo File
address@hidden Beginning a Texinfo file
address@hidden Texinfo file beginning
address@hidden File beginning
+
+Certain pieces of information must be provided at the beginning of a
+Texinfo file, such as the name for the output file(s), the title of the
+document, and the Top node.
+
+This chapter expands on the minimal complete Texinfo source file
+previously given (@pxref{Six Parts}).
+
address@hidden
+* 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.
+* The Top Node:: Creating the `Top' node and master menu.
+* Global Document Commands:: Affecting formatting throughout.
+* Software Copying Permissions:: Ensure that you and others continue to
+ have the right to use and share software.
address@hidden menu
+
+
address@hidden Sample Beginning
address@hidden Sample Texinfo File Beginning
+
address@hidden Example beginning of Texinfo file
+
+The following sample shows what is needed. The elements given here are
+explained in more detail in the following sections. Other commands are
+often included at the beginning of Texinfo files, but the ones here are
+the most critical.
+
address@hidden Sample Texts}, for the full texts to be used in GNU manuals.
+
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename @var{infoname}.info
+@@settitle @var{name-of-manual} @var{version}
+@@c %**end of header
+
+@@copying
+This manual is for @var{program}, version @var{version}.
+
+Copyright @@address@hidden@} @var{years} @var{copyright-owner}.
+
address@hidden
+@@quotation
+Permission is granted to @dots{}
+@@end quotation
+@@end copying
address@hidden group
+
address@hidden
+@@titlepage
+@@title @var{name-of-manual-when-printed}
+@@subtitle @var{subtitle-if-any}
+@@subtitle @var{second-subtitle}
+@@author @var{author}
address@hidden group
+
address@hidden
+@@c The following two commands
+@@c start the copyright page.
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
address@hidden group
+
+Published by @dots{}
+@@end titlepage
+
+@@c So the toc is printed in the right place.
+@@contents
+
+@@ifnottex
+@@node Top
+@@top @var{title}
+
+@@insertcopying
+@@end ifnottex
+
address@hidden
+@@menu
+* First Chapter:: Getting started @dots{}
+* Second Chapter:: @dots{}
+ @dots{}
+* Copying:: Your rights and freedoms.
+@@end menu
address@hidden group
+
address@hidden
+@@node First Chapter
+@@chapter First Chapter
+
+@@cindex first chapter
+@@cindex chapter, first
address@hidden
address@hidden group
address@hidden example
+
+
address@hidden Texinfo File Header
address@hidden Texinfo File Header
address@hidden Header for Texinfo files
address@hidden Texinfo file header
+
+Texinfo files start with at least three lines that provide Info and
address@hidden with necessary information. These are the @code{\input texinfo}
+line, the @code{@@settitle} line, and the @code{@@setfilename} line.
+
+Also, if you want to format just part of the Texinfo file, you must
+write the @code{@@settitle} and @code{@@setfilename} lines between
+start-of-header and end-of-header lines. The start- and end-of-header
+lines are optional, but they do no harm, so you might as well always
+include them.
+
+Any command that affects document formatting as a whole makes sense to
+include in the header. @code{@@synindex} (@pxref{synindex}), for
+instance, is another command often included in the header. @xref{GNU
+Sample Texts}, for complete sample texts.
+
+Thus, the beginning of a Texinfo file generally looks like this:
+
address@hidden
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename sample.info
+@@settitle Sample Manual 1.0
+@@c %**end of header
address@hidden group
address@hidden example
+
address@hidden
+* First Line:: The first line of a Texinfo file.
+* Start of Header:: Formatting a region requires this.
+* setfilename:: Tell Info the name of the Info file.
+* settitle:: Create a title for the printed work.
+* End of Header:: Formatting a region requires this.
address@hidden menu
+
+
address@hidden First Line
address@hidden The First Line of a Texinfo File
address@hidden First line of a Texinfo file
address@hidden Beginning line of a Texinfo file
address@hidden Header 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:
+
address@hidden
+\input texinfo @@c -*-texinfo-*-
address@hidden example
+
address@hidden
+This line serves two functions:
+
address@hidden
address@hidden
+When the file is processed by @TeX{}, the @samp{\input texinfo} command
+tells @TeX{} to load the macros needed for processing a Texinfo file.
+These are in a file called @file{texinfo.tex}, which should have been
+installed on your system along with either the @TeX{} or Texinfo
+software. @TeX{} uses the backslash, @samp{\}, to mark the beginning of
+a command, exactly as Texinfo uses @samp{@@}. The @file{texinfo.tex}
+file causes the switch from @samp{\} to @samp{@@}; before the switch
+occurs, @TeX{} requires @samp{\}, which is why it appears at the
+beginning of the file.
+
address@hidden
+When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode
+specification tells Emacs to use Texinfo mode.
address@hidden enumerate
+
+
address@hidden Start of Header
address@hidden Start of Header
address@hidden Start of header line
+
+A start-of-header line is a Texinfo comment that looks like this:
+
address@hidden
+@@c %**start of header
address@hidden example
+
+Write the start-of-header line on the second line of a Texinfo file.
+Follow the start-of-header line with @code{@@setfilename} and
address@hidden@@settitle} lines and, optionally, with other commands that
+globally affect the document formatting, such as @code{@@synindex} or
address@hidden@@footnotestyle}; and then by an end-of-header line (@pxref{End of
+Header}).
+
+The start- and end-of-header lines allow you to format only part of a
+Texinfo file for Info or printing. @xref{texinfo-format commands}.
+
+The odd string of characters, @samp{%**}, is to ensure that no other
+comment is accidentally taken for a start-of-header line. You can
+change it if you wish by setting the @code{tex-start-of-header} and/or
address@hidden Emacs variables. @xref{Texinfo Mode Printing}.
+
+
address@hidden setfilename
address@hidden @code{@@setfilename}: Set the output file name
address@hidden setfilename
address@hidden Texinfo requires @code{@@setfilename}
+
+In order to serve as the primary input file for either @code{makeinfo}
+or @TeX{}, a Texinfo file must contain a line that looks like this:
+
address@hidden
+@@setfilename @var{info-file-name}
address@hidden example
+
+Write the @code{@@setfilename} command at the beginning of a line and
+follow it on the same line by the Info file name. Do not write anything
+else on the line; anything on the line after the command is considered
+part of the file name, including what would otherwise be a
+comment.
+
address@hidden Ignored before @code{@@setfilename}
address@hidden @samp{\input} source line ignored
+The Info formatting commands ignore everything written before the
address@hidden@@setfilename} line, which is why the very first line of
+the file (the @code{\input} line) does not show up in the output.
+
+The @code{@@setfilename} line specifies the name of the output file to
+be generated. This name must be different from the name of the Texinfo
+file. There are two conventions for choosing the name: you can either
+remove the extension (such as @samp{.texi}) entirely from the input file
+name, or, preferably, replace it with the @samp{.info} extension.
+
address@hidden Length of file names
address@hidden File name collision
address@hidden Info file name, choosing
+Although an explicit @samp{.info} extension is preferable, some
+operating systems cannot handle long file names. You can run into a
+problem even when the file name you specify is itself short enough.
+This occurs because the Info formatters split a long Info file into
+short indirect subfiles, and name them by appending @samp{-1},
address@hidden, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original
+file name. (@xref{Tag and Split Files}.) The subfile name
address@hidden, for example, is too long for old systems with a
+14-character limit on filenames; so the Info file name for this document
+is @file{texinfo} rather than @file{texinfo.info}. When @code{makeinfo}
+is running on operating systems such as MS-DOS which impose severe
+limits on file names, it may remove some characters from the original
+file name to leave enough space for the subfile suffix, thus producing
+files named @file{texin-10}, @file{gcc.i12}, etc.
+
+When producing HTML output, @code{makeinfo} will replace any extension
+with @samp{html}, or add @samp{.html} if the given name has no
+extension.
+
address@hidden texinfo.cnf
+The @code{@@setfilename} line produces no output when you typeset a
+manual with @TeX{}, but it is nevertheless essential: it opens the
+index, cross-reference, and other auxiliary files used by Texinfo, and
+also reads @file{texinfo.cnf} if that file is present on your system
+(@pxref{Preparing for TeX,, Preparing for @TeX{}}).
+
+
address@hidden settitle
address@hidden @code{@@settitle}: Set the document title
address@hidden settitle
+
+In order to be made into a printed manual, a Texinfo file must contain
+a line that looks like this:
+
address@hidden
+@@settitle @var{title}
address@hidden example
+
+Write the @code{@@settitle} command at the beginning of a line and
+follow it on the same line by the title. This tells @TeX{} the title to
+use in a header or footer. Do not write anything else on the line;
+anything on the line after the command is considered part of the title,
+including what would otherwise be a comment.
+
+The @code{@@settitle} command should precede everything that generates
+actual output in @TeX{}.
+
address@hidden <title> HTML tag
+In the HTML file produced by @command{makeinfo}, @var{title} also serves
+as the document @samp{<title>} and the default document description in
+the @samp{<head>} part; see @ref{documentdescription}, for how to change
+that.
+
+The title in the @code{@@settitle} command does not affect the title as
+it appears on the title page. Thus, the two do not need not match
+exactly. A practice we recommend is to include the version or edition
+number of the manual in the @code{@@settitle} title; on the title page,
+the version number generally appears as a @code{@@subtitle} so it would
+be omitted from the @code{@@title}. (@xref{titlepage}.)
+
+Conventionally, when @TeX{} formats a Texinfo file for double-sided
+output, the title is printed in the left-hand (even-numbered) page
+headings and the current chapter title is printed in the right-hand
+(odd-numbered) page headings. (@TeX{} learns the title of each chapter
+from each @code{@@chapter} command.) By default, no page footer is
+printed.
+
+Even if you are printing in a single-sided style, @TeX{} looks for an
address@hidden@@settitle} command line, in case you include the manual title
+in the heading.
+
address@hidden prints page headings only for that text that comes after the
address@hidden@@end titlepage} command in the Texinfo file, or that comes
+after an @code{@@headings} command that turns on headings.
+(@xref{headings on off, , The @code{@@headings} Command}, for more
+information.)
+
+You may, if you wish, create your own, customized headings and footings.
address@hidden, for a detailed discussion of this.
+
+
address@hidden End of Header
address@hidden End of Header
address@hidden End of header line
+
+Follow the header lines with an @w{end-of-header} line, which is a
+Texinfo comment that looks like this:
+
address@hidden
+@@c %**end of header
address@hidden example
+
address@hidden of Header}.
+
+
address@hidden Document Permissions
address@hidden Document Permissions
address@hidden Document Permissions
address@hidden Copying Permissions
+
+The copyright notice and copying permissions for a document need to
+appear in several places in the various Texinfo output formats.
+Therefore, Texinfo provides a command (@code{@@copying}) to declare
+this text once, and another command (@code{@@insertcopying}) to
+insert the text at appropriate points.
+
address@hidden
+* copying:: Declare the document's copying permissions.
+* insertcopying:: Where to insert the permissions.
address@hidden menu
+
+
address@hidden copying
address@hidden @code{@@copying}: Declare copying permissions
address@hidden copying
+
+The @code{@@copying} command should be given very early in the document;
+right after the header material (@pxref{Texinfo File Header}) is the
+recommended location. It conventionally consists of a sentence or two
+about what the program is, the legal copyright line, and the copying
+permissions. Here is a skeletal example:
+
address@hidden
+@@copying
+This manual is for @var{program} (version @var{version}),
+which @dots{}
+
+Copyright @@address@hidden@} @var{years} @var{copyright-owner}.
+
+@@quotation
+Permission is granted to @dots{}
+@@end quotation
+@@end copying
address@hidden example
+
+The @code{@@quotation} has no legal significance; it's there to improve
+readability in some contexts.
+
address@hidden Sample Texts}, for the full text to be used in GNU manuals.
address@hidden Free Documentation License}, for the license itself under
+which GNU and other free manuals are distributed.
+
+The text of @code{@@copying} is output as a comment at the beginning of
+Info, HTML, and XML output files. It is @emph{not} output implicitly in
+plain text or @TeX{}; it's up to you to use @code{@@insertcopying} to
+emit the copying information. See the next section for details.
+
address@hidden copyright
+In output formats that support it (print and HTML), the
address@hidden@@address@hidden@}} command generates a @samp{c} inside a circle.
In
+Info and plain text, it generates @samp{(C)}. The copyright notice
+itself has the following legally defined sequence:
+
address@hidden
+Copyright @copyright{} @var{years} @var{copyright-owner}.
address@hidden example
+
address@hidden Copyright word, always in English
+The word `Copyright' must always be written in English, even if the
+manual is otherwise in another language. This is due to international
+law.
+
address@hidden Years, in copyright line
+The list of years should include all years in which a version was
+completed (even if it was released in a subsequent year). Ranges are
+not allowed, each year must be written out individually, separated by
+commas.
+
address@hidden Copyright owner for FSF works
+The copyright owner (or owners) is whoever holds legal copyright on the
+work. In the case of works assigned to the FSF, the owner is `Free
+Software Foundation, Inc.'.
+
address@hidden Notices,,,maintain,GNU Maintenance Instructions}, for
+additional information.
+
+
address@hidden insertcopying
address@hidden @code{@@insertcopying}: Include permissions text
address@hidden insertcopying
address@hidden Copying text, including
address@hidden Permissions text, including
address@hidden Including permissions text
+
+The @code{@@insertcopying} command is simply written on a line by
+itself, like this:
+
address@hidden
+@@insertcopying
address@hidden example
+
+It inserts the text previously defined by @code{@@copying}. Legally, it
+must be used on the copyright page in the printed manual
+(@pxref{Copyright}).
+
+Although it's not a legal requirement, we also strongly recommend using
address@hidden@@insertcopying} in the Top node of your manual (@pxref{The Top
+Node}). Here's why:
+
+The @code{@@copying} command itself causes the permissions text to
+appear in an Info file @emph{before} the first node. The text is also
+copied into the beginning of each split Info output file, as is legally
+necessary. This location implies a human reading the manual using Info
+does @emph{not} see this text (except when using the advanced Info
+command @kbd{g *}). Therefore, an explicit @code{@@insertcopying}
+in the Top node makes it apparent to readers that the manual is free.
+
+Similarly, the @code{@@copying} text is automatically included at the
+beginning of each HTML output file, as an HTML comment. Again, this
+text is not visible (unless the reader views the HTML source). And
+therefore again, the @code{@@insertcopying} in the Top node is valuable
+because it makes the copying permissions visible and thus promotes
+freedom.
+
+The permissions text defined by @code{@@copying} also appears
+automatically at the beginning of the XML output file.
+
+
address@hidden Titlepage & Copyright Page
address@hidden Title and Copyright Pages
+
+In hard copy output, the manual's name and author are usually printed on
+a title page. Copyright information is usually printed on the back of
+the title 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 several slightly
+obscure @TeX{} typesetting commands that cannot 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 appears in the printed manual.
+
address@hidden Title page, for plain text
address@hidden Copyright page, for plain text
+You may wish to include titlepage-like information for plain text
+output. Simply place any such leading material between
address@hidden@@ifplaintext} and @code{@@end ifplaintext}; @command{makeinfo}
+includes this when writing plain text (@samp{--no-headers}), along with
+an @code{@@insertcopying}.
+
address@hidden
+* titlepage:: Create a title for the printed document.
+* titlefont center sp:: The @code{@@titlefont}, @code{@@center},
+ and @code{@@sp} commands.
+* title subtitle author:: The @code{@@title}, @code{@@subtitle},
+ and @code{@@author} commands.
+* Copyright:: How to write the copyright notice and
+ include copying permissions.
+* end titlepage:: Turn on page headings after the title and
+ copyright pages.
+* headings on off:: An option for turning headings on and off
+ and double or single sided printing.
address@hidden menu
+
+
address@hidden titlepage
address@hidden @code{@@titlepage}
address@hidden Title page
address@hidden titlepage
+
+Start the material for the title page and following copyright page
+with @code{@@titlepage} on a line by itself and end it with
address@hidden@@end titlepage} on a line by itself.
+
+The @code{@@end titlepage} command starts a new page and turns on page
+numbering. (@xref{Headings, , Page Headings}, for details about how to
+generate page headings.) All the material that you want to appear on
+unnumbered pages should be put between the @code{@@titlepage} and
address@hidden@@end titlepage} commands. You can force the table of contents to
+appear there with the @code{@@setcontentsaftertitlepage} command
+(@pxref{Contents}).
+
address@hidden address@hidden, within @code{@@titlepage}}
+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 thereby create more than one unnumbered page. This is how
+the copyright page is produced. (The @code{@@titlepage} command might
+perhaps have been better named the @code{@@titleandadditionalpages}
+command, but that would have been rather long!)
+
+When you write a manual about a computer program, you should write the
+version of the program to which the manual applies on the title page.
+If the manual changes more frequently than the program or is independent
+of it, you should also include an edition address@hidden have found
+that it is helpful to refer to versions of independent manuals as
+`editions' and versions of programs as `versions'; otherwise, we find we
+are liable to confuse each other in conversation by referring to both
+the documentation and the software with the same words.} for the manual.
+This helps readers keep track of which manual is for which version of
+the program. (The `Top' node should also contain this information; see
address@hidden Top Node}.)
+
+Texinfo provides two main methods for creating a title page. One method
+uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands
+to generate a title page in which the words on the page are
+centered.
+
+The second method uses the @code{@@title}, @code{@@subtitle}, and
address@hidden@@author} commands to create a title page with black rules under
+the title and author lines and the subtitle text set flush to the
+right hand side of the page. With this method, you do not specify any
+of the actual formatting of the title page. You specify the text
+you want, and Texinfo does the formatting.
+
+You may use either method, or you may combine them; see the examples in
+the sections below.
+
address@hidden shorttitlepage
address@hidden Bastard title page
address@hidden Title page, bastard
+For extremely simple applications, and for the bastard title page in
+traditional book front matter, Texinfo also provides a command
address@hidden@@shorttitlepage} which takes the rest of the line as the title.
+The argument is typeset on a page by itself and followed by a blank
+page.
+
+
address@hidden titlefont center sp
address@hidden @code{@@titlefont}, @code{@@center}, and @code{@@sp}
address@hidden titlefont
address@hidden center
address@hidden sp @r{(titlepage line spacing)}
+
+You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center}
+commands to create a title page for a printed document. (This is the
+first of the two methods for creating a title page in Texinfo.)
+
+Use the @code{@@titlefont} command to select a large font suitable for
+the title itself. You can use @code{@@titlefont} more than once if you
+have an especially long title.
+
address@hidden 700
+For example:
+
address@hidden
+@@address@hidden@}
address@hidden example
+
+Use the @code{@@center} command at the beginning of a line to center
+the remaining text on that line. Thus,
+
address@hidden
+@@center @@address@hidden@}
address@hidden example
+
address@hidden
+centers the title, which in this example is ``Texinfo'' printed
+in the title font.
+
+Use the @code{@@sp} command to insert vertical space. For example:
+
address@hidden
+@@sp 2
address@hidden example
+
address@hidden
+This inserts two blank lines on the printed page. (@xref{sp, ,
address@hidden@@sp}}, for more information about the @code{@@sp}
+command.)
+
+A template for this method looks like this:
+
address@hidden
address@hidden
+@@titlepage
+@@sp 10
+@@center @@address@hidden@address@hidden
+@@sp 2
+@@center @var{subtitle-if-any}
+@@sp 2
+@@center @var{author}
address@hidden
+@@end titlepage
address@hidden group
address@hidden example
+
+The spacing of the example fits an 8.5 by 11 inch manual.
+
+
address@hidden title subtitle author
address@hidden @code{@@title}, @code{@@subtitle}, and @code{@@author}
address@hidden title
address@hidden subtitle
address@hidden author
+
+You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author}
+commands to create a title page in which the vertical and horizontal
+spacing is done for you automatically. This contrasts with the method
+described in the previous section, in which the @code{@@sp} command is
+needed to adjust vertical spacing.
+
+Write the @code{@@title}, @code{@@subtitle}, or @code{@@author}
+commands at the beginning of a line followed by the title, subtitle,
+or author.
+
+The @code{@@title} command produces a line in which the title is set
+flush to the left-hand side of the page in a larger than normal font.
+The title is underlined with a black rule. Only a single line is
+allowed; the @code{@@*} command may not be used to break the title into
+two lines. To handle very long titles, you may find it profitable to
+use both @code{@@title} and @code{@@titlefont}; see the final example in
+this section.
+
+The @code{@@subtitle} command sets subtitles in a normal-sized font
+flush to the right-hand side of the page.
+
+The @code{@@author} command sets the names of the author or authors in
+a middle-sized font flush to the left-hand side of the page on a line
+near the bottom of the title page. The names are underlined with a
+black rule that is thinner than the rule that underlines the title.
+(The black rule only occurs if the @code{@@author} command line is
+followed by an @code{@@page} command line.)
+
+There are two ways to use the @code{@@author} command: you can write
+the name or names on the remaining part of the line that starts with
+an @code{@@author} command:
+
address@hidden
+@@author by Jane Smith and John Doe
address@hidden example
+
address@hidden
+or you can write the names one above each other by using two (or more)
address@hidden@@author} commands:
+
address@hidden
address@hidden
+@@author Jane Smith
+@@author John Doe
address@hidden group
address@hidden example
+
address@hidden
+(Only the bottom name is underlined with a black rule.)
+
address@hidden 950
+A template for this method looks like this:
+
address@hidden
address@hidden
+@@titlepage
+@@title @var{name-of-manual-when-printed}
+@@subtitle @var{subtitle-if-any}
+@@subtitle @var{second-subtitle}
+@@author @var{author}
+@@page
address@hidden
+@@end titlepage
address@hidden group
address@hidden example
+
+You may also combine the @code{@@titlefont} method described in the
+previous section and @code{@@title} method described in this one. This
+may be useful if you have a very long title. Here is a real-life example:
+
address@hidden
address@hidden
+@@titlepage
+@@address@hidden address@hidden
+@@sp 1
+@@title for MS-Windows and MS-DOS
+@@subtitle Edition @@address@hidden@} for Release @@address@hidden@}
+@@author by Daniel Hagerty, Melissa Weisshaus
+@@author and Eli Zaretskii
address@hidden group
address@hidden example
+
address@hidden
+(The use of @code{@@value} here is explained in @ref{value Example}.
+
+
address@hidden Copyright
address@hidden Copyright Page
address@hidden Copyright page
address@hidden Printed permissions
address@hidden Permissions, printed
+
+By international treaty, the copyright notice for a book must be either
+on the title page or on the back of the title page. When the copyright
+notice is on the back of the title page, that page is customarily not
+numbered. Therefore, in Texinfo, the information on the copyright page
+should be within @code{@@titlepage} and @code{@@end titlepage}
+commands.
+
address@hidden vskip @address@hidden vertical skip}
address@hidden filll @address@hidden dimension}
+Use the @code{@@page} command to cause a page break. To push the
+copyright notice and the other text on the copyright page towards the
+bottom of the page, use the following incantantion after @code{@@page}:
+
address@hidden
+@@vskip 0pt plus 1filll
address@hidden example
+
address@hidden
+This is a @TeX{} command that is not supported by the Info formatting
+commands. The @code{@@vskip} command inserts whitespace. The @samp{0pt
+plus 1filll} means to put in zero points of mandatory whitespace, and as
+much optional whitespace as needed to push the following text to the
+bottom of the page. Note the use of three @samp{l}s in the word
address@hidden; this is correct.
+
+To insert the copyright text itself, write @code{@@insertcopying}
+next (@pxref{Document Permissions}):
+
address@hidden
+@@insertcopying
address@hidden example
+
+Follow the copying text by the publisher, ISBN numbers, cover art
+credits, and other such information.
+
+Here is an example putting all this together:
+
address@hidden
+@@titlepage
address@hidden
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
+
+Published by @dots{}
+
+Cover art by @dots{}
+@@end titlepage
address@hidden example
+
+
address@hidden end titlepage
address@hidden Heading Generation
address@hidden end titlepage
address@hidden Headings, page, begin to appear
address@hidden Titlepage end starts headings
address@hidden End titlepage starts headings
+
+The @code{@@end titlepage} command must be written on a line by itself.
+It not only marks the end of the title and copyright pages, but also
+causes @TeX{} to start generating page headings and page numbers.
+
+To repeat what is said elsewhere, Texinfo has two standard page heading
+formats, one for documents which are printed on one side of each sheet of paper
+(single-sided printing), and the other for documents which are printed on both
+sides of each sheet (double-sided printing).
+You can specify these formats in different ways:
+
address@hidden @bullet
address@hidden
+The conventional way is to write an @code{@@setchapternewpage} command
+before the title page commands, and then have the @code{@@end
+titlepage} command start generating page headings in the manner desired.
+(@xref{setchapternewpage}.)
+
address@hidden
+Alternatively, you can use the @code{@@headings} command to prevent page
+headings from being generated or to start them for either single or
+double-sided printing. (Write an @code{@@headings} command immediately
+after the @code{@@end titlepage} command. @xref{headings on off, , The
address@hidden@@headings} Command}, for more information.)@refill
+
address@hidden
+Or, you may specify your own page heading and footing format.
address@hidden, , Page Headings}, for detailed
+information about page headings and footings.
address@hidden itemize
+
+Most documents are formatted with the standard single-sided or
+double-sided format, using @code{@@setchapternewpage odd} for
+double-sided printing and no @code{@@setchapternewpage} command for
+single-sided printing.
+
+
address@hidden headings on off
address@hidden The @code{@@headings} Command
address@hidden headings
+
+The @code{@@headings} command is rarely used. It specifies what kind of
+page headings and footings to print on each page. Usually, this is
+controlled by the @code{@@setchapternewpage} command. You need the
address@hidden@@headings} command only if the @code{@@setchapternewpage} command
+does not do what you want, or if you want to turn off pre-defined page
+headings prior to defining your own. Write an @code{@@headings} command
+immediately after the @code{@@end titlepage} address@hidden
+
+You can use @code{@@headings} as follows:@refill
+
address@hidden @code
address@hidden @@headings off
+Turn off printing of page address@hidden
+
address@hidden @@headings single
+Turn on page headings appropriate for single-sided printing.
address@hidden
+
address@hidden @@headings double
address@hidden @@headings on
+Turn on page headings appropriate for double-sided printing. The two
+commands, @code{@@headings on} and @code{@@headings double}, are
address@hidden
+
address@hidden @@headings singleafter
address@hidden @@headings doubleafter
+Turn on @code{single} or @code{double} headings, respectively, after the
+current page is output.
+
address@hidden @@headings on
+Turn on page headings: @code{single} if @samp{@@setchapternewpage
+on}, @code{double} otherwise.
address@hidden table
+
+For example, suppose you write @code{@@setchapternewpage off} before the
address@hidden@@titlepage} command to tell @TeX{} to start a new chapter on the
+same page as the end of the last chapter. This command also causes
address@hidden to typeset page headers for single-sided printing. To cause
address@hidden to typeset for double sided printing, write @code{@@headings
+double} after the @code{@@end titlepage} command.
+
+You can stop @TeX{} from generating any page headings at all by
+writing @code{@@headings off} on a line of its own immediately after the
+line containing the @code{@@end titlepage} command, like this:@refill
+
address@hidden
+@@end titlepage
+@@headings off
address@hidden example
+
address@hidden
+The @code{@@headings off} command overrides the @code{@@end titlepage}
+command, which would otherwise cause @TeX{} to print page
address@hidden
+
+You can also specify your own style of page heading and footing.
address@hidden, , Page Headings}, for more address@hidden
+
+
address@hidden The Top Node
address@hidden The `Top' Node and Master Menu
address@hidden Top node
address@hidden Node, `Top'
+
+The `Top' node is the node in which a reader enters an Info manual. As
+such, it should begin with the @code{@@insertcopying} command
+(@pxref{Document Permissions}) to provide a brief description of the
+manual (including the version number) and copying permissions, and end
+with a master menu for the whole manual. Of course you should include
+any other general information you feel a reader would find helpful.
+
address@hidden top
+It is also conventional to write an @code{@@top} sectioning command line
+containing the title of the document immediately after the @code{@@node
+Top} line (@pxref{makeinfo top command, , The @code{@@top} Sectioning
+Command}).
+
+The contents of the `Top' node should appear only in the online output;
+none of it should appear in printed output, so enclose it between
address@hidden@@ifnottex} and @code{@@end ifnottex} commands. (@TeX{} does not
+print either an @code{@@node} line or a menu; they appear only in Info;
+strictly speaking, you are not required to enclose these parts between
address@hidden@@ifnottex} and @code{@@end ifnottext}, but it is simplest to do
+so. @xref{Conditionals, , Conditionally Visible Text}.)
+
address@hidden
+* Top Node Example::
+* Master Menu Parts::
address@hidden menu
+
+
address@hidden Top Node Example
address@hidden Top Node Example
+
address@hidden Top node example
+
+Here is an example of a Top node.
+
address@hidden
address@hidden
+@@ifnottex
+@@node Top
+@@top Sample Title
+
+@@insertcopying
address@hidden group
+
+Additional general information.
+
address@hidden
+@@menu
+* First Chapter::
+* Second Chapter::
address@hidden
+* Index::
address@hidden group
+@@end menu
address@hidden example
+
+
address@hidden Master Menu Parts
address@hidden Parts of a Master Menu
address@hidden Master menu
address@hidden Menu, master
address@hidden Parts of a master menu
+
+A @dfn{master menu} is a detailed main menu listing all the nodes in a
+file.
+
+A master menu is enclosed in @code{@@menu} and @code{@@end menu}
+commands and does not appear in the printed document.
+
+Generally, a master menu is divided into parts.
+
address@hidden @bullet
address@hidden
+The first part contains the major nodes in the Texinfo file: the nodes
+for the chapters, chapter-like sections, and the appendices.
+
address@hidden
+The second part contains nodes for the indices.
+
address@hidden
+The third and subsequent parts contain a listing of the other, lower
+level nodes, often ordered by chapter. This way, rather than go
+through an intermediary menu, an inquirer can go directly to a
+particular node when searching for specific information. These menu
+items are not required; add them if you think they are a
+convenience. If you do use them, put @code{@@detailmenu} before the
+first one, and @code{@@end detailmenu} after the last; otherwise,
address@hidden will get confused.
address@hidden itemize
+
+Each section in the menu can be introduced by a descriptive line. So
+long as the line does not begin with an asterisk, it will not be
+treated as a menu entry. (@xref{Writing a Menu}, for more
+information.)
+
+For example, the master menu for this manual looks like the following
+(but has many more entries):
+
address@hidden
address@hidden
+@@menu
+* Copying Conditions:: Your rights.
+* Overview:: Texinfo in brief.
address@hidden
address@hidden group
address@hidden
+* Command and Variable Index::
+* Concept Index::
address@hidden group
+
address@hidden
+@@detailmenu
+ --- The Detailed Node Listing ---
+
+Overview of Texinfo
+
+* Reporting Bugs:: @dots{}
address@hidden
address@hidden group
+
address@hidden
+Beginning a Texinfo File
+
+* Sample Beginning:: @dots{}
address@hidden
+@@end detailmenu
+@@end menu
address@hidden group
address@hidden example
+
+
address@hidden Global Document Commands
address@hidden Global Document Commands
address@hidden Global Document Commands
+
+Besides the basic commands mentioned in the previous sections, here are
+additional commands which affect the document as a whole. They are
+generally all given before the Top node, if they are given at all.
+
address@hidden
+* documentdescription:: Document summary for the HTML output.
+* setchapternewpage:: Start chapters on right-hand pages.
+* paragraphindent:: Specify paragraph indentation.
+* exampleindent:: Specify environment indentation.
address@hidden menu
+
+
address@hidden documentdescription
address@hidden @code{@@documentdescription}: Summary text
address@hidden Document description
address@hidden Description of document
address@hidden Summary of document
address@hidden Abstract of document
address@hidden <meta> HTML tag, and document description
address@hidden documentdescription
+
+When producing HTML output for a document, @command{makeinfo} writes a
address@hidden<meta>} element in the @samp{<head>} to give some idea of the
+content of the document. By default, this @dfn{description} is the title
+of the document, taken from the @code{@@settitle} command
+(@pxref{settitle}). To change this, use the @code{@@documentdescription}
+environment, as in:
+
address@hidden
+@@documentdescription
+descriptive text.
+@@end documentdescription
address@hidden example
+
address@hidden
+This will produce the following output in the @samp{<head>} of the HTML:
+
address@hidden
+<meta name=description content="descriptive text.">
address@hidden example
+
address@hidden@@documentdescription} must be specified before the first node of
+the document.
+
+
address@hidden setchapternewpage
address@hidden @code{@@setchapternewpage}:
address@hidden Starting chapters
address@hidden Pages, starting odd
address@hidden setchapternewpage
+
+In an officially bound book, text is usually printed on both sides of
+the paper, chapters start on right-hand pages, and right-hand pages have
+odd numbers. But in short reports, text often is printed only on one
+side of the paper. Also in short reports, chapters sometimes do not
+start on new pages, but are printed on the same page as the end of the
+preceding chapter, after a small amount of vertical whitespace.
+
+You can use the @code{@@setchapternewpage} command with various
+arguments to specify how @TeX{} should start chapters and whether it
+should format headers for printing on one or both sides of the paper
+(single-sided or double-sided printing).
+
+Write the @code{@@setchapternewpage} command at the beginning of a
+line followed by its argument.
+
+For example, you would write the following to cause each chapter to
+start on a fresh odd-numbered page:
+
address@hidden
+@@setchapternewpage odd
address@hidden example
+
+You can specify one of three alternatives with the
address@hidden@@setchapternewpage} command:
+
address@hidden @asis
+
address@hidden @code{@@setchapternewpage off}
+Cause @TeX{} to typeset a new chapter on the same page as the last
+chapter, after skipping some vertical whitespace. Also, cause @TeX{} to
+format page headers for single-sided printing.
+
address@hidden @code{@@setchapternewpage on}
+Cause @TeX{} to start new chapters on new pages and to format page
+headers for single-sided printing. This is the form most often used for
+short reports or personal printing. This is the default.
+
address@hidden @code{@@setchapternewpage odd}
+Cause @TeX{} to start new chapters on new, odd-numbered pages
+(right-handed pages) and to typeset for double-sided printing. This is
+the form most often used for books and manuals.
address@hidden table
+
+Texinfo does not have an @code{@@setchapternewpage even} command,
+because there is no printing tradition of starting chapters or books on
+an even-numbered page.
+
+If you don't like the default headers that @code{@@setchapternewpage}
+sets, you can explicit control them with the @code{@@headings} command.
address@hidden on off, , The @code{@@headings} Command}.
+
+At the beginning of a manual or book, pages are not numbered---for
+example, the title and copyright pages of a book are not numbered. By
+convention, table of contents and frontmatter pages are numbered with
+roman numerals and not in sequence with the rest of the document.
+
+Since an Info file does not have pages, the @code{@@setchapternewpage}
+command has no effect on it.
+
+We recommend not including any @code{@@setchapternewpage} command in
+your manual sources at all, since the desired output is not intrinsic to
+the document. For a particular hard copy run, if you don't want the
+default option (no blank pages, same headers on all pages) use the
address@hidden option to @command{texi2dvi} to specify the output
+you want.
+
+
address@hidden paragraphindent
address@hidden Paragraph Indenting
address@hidden Indenting paragraphs, control of
address@hidden Paragraph indentation control
address@hidden paragraphindent
+
+The Texinfo processors may insert whitespace at the beginning of the
+first line of each paragraph, thereby indenting that paragraph. You can
+use the @code{@@paragraphindent} command to specify this indentation.
+Write an @code{@@paragraphindent} command at the beginning of a line
+followed by either @samp{asis} or a number:
+
address@hidden
+@@paragraphindent @var{indent}
address@hidden example
+
+The indentation is according to the value of @var{indent}:
+
address@hidden @asis
address@hidden @code{asis}
+Do not change the existing indentation (not implemented in @TeX{}).
+
address@hidden @code{none}
address@hidden 0
+Omit all indentation.
+
address@hidden @var{n}
+Indent by @var{n} space characters in Info output, by @var{n} ems in
address@hidden
+
address@hidden table
+
+The default value of @var{indent} is 3. @code{@@paragraphindent} is
+ignored for HTML output.
+
+It is best to write the @code{@@paragraphindent} command before the
+end-of-header line at the beginning of a Texinfo file, so the region
+formatting commands indent paragraphs as specified. @xref{Start of
+Header}.
+
+A peculiarity of the @code{texinfo-format-buffer} and
address@hidden commands is that they do not indent (nor
+fill) paragraphs that contain @code{@@w} or @code{@@*} commands.
address@hidden Paragraphs}, for further information.
+
+
address@hidden exampleindent
address@hidden @code{@@exampleindent}: Environment Indenting
address@hidden Indenting environments
address@hidden Environment indentation
address@hidden Example indentation
address@hidden exampleindent
+
+The Texinfo processors indent each line of @code{@@example} and similar
+environments. You can use the @code{@@exampleindent} command to specify
+this indentation. Write an @code{@@exampleindent} command at the
+beginning of a line followed by either @samp{asis} or a number:
+
address@hidden
+@@exampleindent @var{indent}
address@hidden example
+
+The indentation is according to the value of @var{indent}:
+
address@hidden @asis
address@hidden @code{asis}
+Do not change the existing indentation (not implemented in @TeX{}).
+
address@hidden 0
+Omit all indentation.
+
address@hidden @var{n}
+Indent environments by @var{n} space characters in Info output, by
address@hidden ems in @TeX{}.
+
address@hidden table
+
+The default value of @var{indent} is 5. @code{@@exampleindent} is
+ignored for HTML output.
+
+It is best to write the @code{@@exampleindent} command before the
+end-of-header line at the beginning of a Texinfo file, so the region
+formatting commands indent paragraphs as specified. @xref{Start of
+Header}.
+
+
address@hidden Software Copying Permissions
address@hidden Software Copying Permissions
address@hidden Software copying permissions
address@hidden Copying software
address@hidden Distribution
address@hidden License agreement
+
+If the Texinfo file has a section containing the ``General Public
+License'' and the distribution information and a warranty disclaimer for
+the software that is documented, we recommend placing this right after
+the `Top' node. The General Public License is very important to Project
+GNU software. It ensures that you and others will continue to have a
+right to use and share the software.
+
+The copying and distribution information and the disclaimer are followed
+by an introduction or else by the first chapter of the manual.
+
address@hidden Introduction, as part of file
+Although an introduction 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, an introduction would follow the licensing and distribution
+information, although sometimes people put it earlier in the document.
+
+
address@hidden Ending a File
address@hidden Ending a Texinfo File
address@hidden Ending a Texinfo file
address@hidden Texinfo file ending
address@hidden File ending
address@hidden bye
+
+The end of a Texinfo file should include commands to create indices and
+(perhaps) to generate both the full and summary tables of contents.
+Finally, it must include the @code{@@bye} command that marks the last
+line to be processed.
+
address@hidden 700
+For example:
+
address@hidden
+@@node Index
+@@unnumbered Index
+
+@@printindex cp
+
+@@shortcontents
+@@contents
+
+@@bye
address@hidden example
+
address@hidden
+* Printing Indices & Menus:: How to print an index in hardcopy and
+ generate index menus in Info.
+* Contents:: How to create a table of contents.
+* File End:: How to mark the end of a file.
address@hidden menu
+
+
address@hidden Printing Indices & Menus
address@hidden Printing Indices and Menus
address@hidden printindex
address@hidden Printing an index
address@hidden Indices, printing and menus
address@hidden Generating menus with indices
address@hidden Menus generated with indices
+
+To print an index means to include it as part of a manual or Info file.
+This does not happen automatically just because you use @code{@@cindex}
+or other index-entry generating commands in the Texinfo file; those just
+cause the raw data for the index to be accumulated. To generate an
+index, you must include the @code{@@printindex} command at the place in
+the document where you want the index to appear. Also, as part of the
+process of creating a printed manual, you must run a program called
address@hidden (@pxref{Hardcopy}) to sort the raw data to produce a
+sorted index file. The sorted index file is what is actually used to
+print the index.
+
+Texinfo offers six separate types of predefined index, each with a
+two-letter abbreviation, as illustrated in the following table.
+However, you may merge indices (@pxref{Combining Indices}) or define
+your own indices (@pxref{New Indices}).
+
+Here are the predefined indices, their abbreviations, and the
+corresponding index entry commands:
+
address@hidden @samp
address@hidden cp
+concept index (@code{@@cindex})
address@hidden fn
+function index (@code{@@findex})
address@hidden vr
+variable index (@code{@@index})
address@hidden ky
+key index (@code{@@kindex})
address@hidden pg
+program index (@code{@@pindex})
address@hidden tp
+data type index (@code{@@tindex})
address@hidden table
+
+The @code{@@printindex} command takes a two-letter index abbreviation,
+reads the corresponding sorted index file and formats it appropriately
+into an index.
+
+The @code{@@printindex} command does not generate a chapter heading for
+the index. Consequently, you should precede the @code{@@printindex}
+command with a suitable section or chapter command (usually
address@hidden@@appendix} or @code{@@unnumbered}) to supply the chapter heading
+and put the index into the table of contents. Precede the
address@hidden@@unnumbered} command with an @code{@@node} line.
+
+For example:
+
address@hidden
address@hidden
+@@node Variable Index
+@@unnumbered Variable Index
+
+@@printindex vr
address@hidden group
+
address@hidden
+@@node Concept Index
+@@unnumbered Concept Index
+
+@@printindex cp
address@hidden group
address@hidden smallexample
+
address@hidden
+
+We recommend placing the concept index last, since that makes it easiest
+to find. We also recommend having a single index whenever possible,
+since then readers have only one place to look (@pxref{Combining Indices}).
+
+
address@hidden Contents
address@hidden Generating a Table of Contents
address@hidden Table of contents
address@hidden Contents, Table of
address@hidden Short table of contents
address@hidden contents
address@hidden summarycontents
address@hidden shortcontents
+
+The @code{@@chapter}, @code{@@section}, and other structuring commands
+supply the information to make up a table of contents, but they do not
+cause an actual table to appear in the manual. To do this, you must use
+the @code{@@contents} and/or @code{@@summarycontents} command(s).
+
address@hidden @code
address@hidden @@contents
+Generate a table of contents in a printed manual, including all
+chapters, sections, subsections, etc., as well as appendices and
+unnumbered chapters. Headings generated by the @code{@@heading}
+series of commands do not appear in the table of contents.
+
address@hidden @@shortcontents
address@hidden @@summarycontents
+(@code{@@summarycontents} is a synonym for @code{@@shortcontents}.)
+
+Generate a short or summary table of contents that lists only the
+chapters, appendices, and unnumbered chapters. Sections, subsections
+and subsubsections are omitted. Only a long manual needs a short table
+of contents in addition to the full table of contents.
+
address@hidden table
+
+Both contents commands should be written on a line by themselves.
+The contents commands automatically generate a chapter-like heading at
+the top of the first table of contents page, so don't include any
+sectioning command such as @code{@@unnumbered} before them.
+
+Since an Info file uses menus instead of tables of contents, the Info
+formatting commands ignore the contents commands. But the contents are
+included in plain text output (generated by @code{makeinfo
+--no-headers}), unless @code{makeinfo} is writing its output to standard
+output.
+
+When @code{makeinfo} writes a short table of contents while producing
+html output, the links in the short table of contents point to
+corresponding entries in the full table of contents rather than the text
+of the document. The links in the full table of contents point to the
+main text of the document.
+
+The contents commands can be placed either at the very end of the file,
+after any indices (see the previous section) and just before the
address@hidden@@bye} (see the next section), or near the beginning of the file,
+after the @code{@@end titlepage} (@pxref{titlepage}). The advantage to
+the former is that then the contents output is always up to date,
+because it reflects the processing just done. The advantage to the
+latter is that the contents are printed in the proper place, thus you do
+not need to rearrange the DVI file with @command{dviselect} or shuffle
+paper.
+
address@hidden setcontentsaftertitlepage
address@hidden setshortcontentsaftertitlepage
address@hidden Contents, after title page
address@hidden Table of contents, after title page
+As an author, you can put the contents commands wherever you prefer.
+But if you are a user simply printing a manual, you may wish to print
+the contents after the title page even if the author put the contents
+commands at the end of the document (as is the case in most existing
+Texinfo documents, at this writing). You can do this by specifying
address@hidden@@setcontentsaftertitlepage} and/or
address@hidden@@setshortcontentsaftertitlepage}. The first prints only the main
+contents after the @code{@@end titlepage}; the second prints both the
+short contents and the main contents. In either case, any subsequent
address@hidden@@contents} or @code{@@shortcontents} is ignored (unless no
address@hidden@@end titlepage} is ever encountered).
+
+You need to include the @code{@@address@hidden
+commands early in the document (just after @code{@@setfilename}, for
+example). We recommend using @command{texi2dvi} (@pxref{Format with
+texi2dvi}) to specify this without altering the source file at all. For
+example:
address@hidden
+texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi
address@hidden example
+
+
address@hidden File End
address@hidden @code{@@bye} File Ending
address@hidden bye
+
+An @code{@@bye} command terminates @TeX{} or Info formatting. None of
+the formatting commands reading anything following @code{@@bye}. The
address@hidden@@bye} command should be on a line by itself.
+
+If you wish, you may follow the @code{@@bye} line with notes. These
+notes will not be formatted and will not appear in either Info or a
+printed manual; it is as if text after @code{@@bye} were within
address@hidden@@ignore} @dots{} @code{@@end ignore}. Also, you may follow the
address@hidden@@bye} line with a local variables list for Emacs.
address@hidden, , Using Local Variables and the Compile Command},
+for more information.
+
+
address@hidden Structuring
address@hidden Chapter Structuring
address@hidden Chapter structuring
address@hidden Structuring of chapters
+
+The @dfn{chapter structuring} commands divide a document into a hierarchy of
+chapters, sections, subsections, and subsubsections. These commands
+generate large headings; they also provide information for the table
+of contents of a printed manual (@pxref{Contents, , Generating a Table
+of Contents})address@hidden
+
+The chapter structuring commands do not create an Info node structure,
+so normally you should put an @code{@@node} command immediately before
+each chapter structuring command (@pxref{Nodes}). The only time you
+are likely to use the chapter structuring commands without using the
+node structuring commands is if you are writing a document that
+contains no cross references and will never be transformed into Info
address@hidden
+
+It is unlikely that you will ever write a Texinfo file that is
+intended only as an Info file and not as a printable document. If you
+do, you might still use chapter structuring commands to create a
+heading at the top of each node---but you don't need address@hidden
+
address@hidden
+* Tree Structuring:: A manual is like an upside down tree @dots{}
+* Structuring Command Types:: How to divide a manual into parts.
+* makeinfo top:: The @code{@@top} command, part of the `Top'
node.
+* chapter::
+* unnumbered & appendix::
+* majorheading & chapheading::
+* section::
+* unnumberedsec appendixsec heading::
+* subsection::
+* unnumberedsubsec appendixsubsec subheading::
+* subsubsection:: Commands for the lowest level sections.
+* Raise/lower sections:: How to change commands' hierarchical level.
address@hidden menu
+
+
address@hidden Tree Structuring
address@hidden Tree Structure of Sections
address@hidden Tree structuring
+
+A Texinfo file is usually structured like a book with chapters,
+sections, subsections, and the like. This structure can be visualized
+as a tree (or rather as an upside-down tree) with the root at the top
+and the levels corresponding to chapters, sections, subsection, and
address@hidden
+
+Here is a diagram that shows a Texinfo file with three chapters,
+each of which has two address@hidden
+
address@hidden
address@hidden
+ Top
+ |
+ -------------------------------------
+ | | |
+ Chapter 1 Chapter 2 Chapter 3
+ | | |
+ -------- -------- --------
+ | | | | | |
+ Section Section Section Section Section Section
+ 1.1 1.2 2.1 2.2 3.1 3.2
+
address@hidden group
address@hidden example
+
+In a Texinfo file that has this structure, the beginning of Chapter 2
+looks like this:@refill
+
address@hidden
address@hidden
+@@node Chapter 2, Chapter 3, Chapter 1, top
+@@chapter Chapter 2
address@hidden group
address@hidden example
+
+The chapter structuring commands are described in the sections that
+follow; the @code{@@node} and @code{@@menu} commands are described in
+following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill
+
+
address@hidden Structuring Command Types
address@hidden Structuring Command Types
+
+The chapter structuring commands fall into four groups or series, each
+of which contains structuring commands corresponding to the
+hierarchical levels of chapters, sections, subsections, and
address@hidden
+
+The four groups are the @code{@@chapter} series, the
address@hidden@@unnumbered} series, the @code{@@appendix} series, and the
address@hidden@@heading} address@hidden
+
+Each command produces titles that have a different appearance on the
+printed page or Info file; only some of the commands produce
+titles that are listed in the table of contents of a printed book or
address@hidden
+
address@hidden @bullet
address@hidden
+The @code{@@chapter} and @code{@@appendix} series of commands produce
+numbered or lettered entries both in the body of a printed work and in
+its table of address@hidden
+
address@hidden
+The @code{@@unnumbered} series of commands produce unnumbered entries
+both in the body of a printed work and in its table of contents. The
address@hidden@@top} command, which has a special use, is a member of this
+series (@pxref{makeinfo top, , @code{@@top}})address@hidden
+
address@hidden
+The @code{@@heading} series of commands produce unnumbered headings
+that do not appear in a table of contents. The heading commands never
+start a new address@hidden
+
address@hidden
+The @code{@@majorheading} command produces results similar to using
+the @code{@@chapheading} command but generates a larger vertical
+whitespace before the address@hidden
+
address@hidden
+When an @code{@@setchapternewpage} command says to do so, the
address@hidden@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands
+start new pages in the printed manual; the @code{@@heading} commands
+do address@hidden
address@hidden itemize
+
+Here are the four groups of chapter structuring commands:
+
address@hidden
+{\globaldefs = 1 \smallfonts}
address@hidden tex
+
address@hidden @columnfractions .19 .30 .29 .22
address@hidden @tab @tab
@tab No new page
address@hidden @i{Numbered} @tab @i{Unnumbered} @tab
@i{Lettered/numbered} @tab @i{Unnumbered}
address@hidden In contents @tab In contents @tab In
contents @tab Omitted address@hidden
address@hidden @tab @code{@@top} @tab
@tab @code{@@majorheading}
address@hidden @code{@@chapter} @tab @code{@@unnumbered} @tab
@code{@@appendix} @tab @code{@@chapheading}
address@hidden @code{@@section} @tab @code{@@unnumberedsec} @tab
@code{@@appendixsec} @tab @code{@@heading}
address@hidden @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab
@code{@@appendixsubsec} @tab @code{@@subheading}
address@hidden @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab
@code{@@appendixsubsubsec} @tab @code{@@subsubheading}
address@hidden multitable
address@hidden
+{\globaldefs = 1 \textfonts}
address@hidden tex
+
+
address@hidden makeinfo top
address@hidden @code{@@top}
+
+The @code{@@top} command is a special sectioning command that you use
+only after an @samp{@@node Top} line at the beginning of a Texinfo file.
+The @code{@@top} command tells the @code{makeinfo} formatter which node
+is the `Top' node, so it can use it as the root of the node tree if your
+manual uses implicit pointers. It has the same typesetting effect as
address@hidden@@unnumbered} (@pxref{unnumbered & appendix, , @code{@@unnumbered}
+and @code{@@appendix}}). For detailed information, see @ref{makeinfo
+top command, , The @code{@@top} Command}.
+
+The @code{@@top} node and its menu (if any) is conventionally wrapped in
+an @code{@@ifnottex} conditional so that it will appear only in Info and
+HTML output, not @TeX{}.
+
+
address@hidden chapter, unnumbered & appendix, makeinfo top, Structuring
address@hidden node-name, next, previous, up
address@hidden @code{@@chapter}
address@hidden chapter
+
address@hidden@@chapter} identifies a chapter in the document. Write the
+command at the beginning of a line and follow it on the same line by
+the title of the address@hidden
+
+For example, this chapter in this manual is entitled ``Chapter
+Structuring''; the @code{@@chapter} line looks like this:@refill
+
address@hidden
+@@chapter Chapter Structuring
address@hidden example
+
+In @TeX{}, the @code{@@chapter} command creates a chapter in the
+document, specifying the chapter title. The chapter is numbered
address@hidden
+
+In Info, the @code{@@chapter} command causes the title to appear on a
+line by itself, with a line of asterisks inserted underneath. Thus,
+in Info, the above example produces the following output:@refill
+
address@hidden
+Chapter Structuring
+*******************
address@hidden example
+
address@hidden centerchap
+Texinfo also provides a command @code{@@centerchap}, which is analogous
+to @code{@@unnumbered}, but centers its argument in the printed output.
+This kind of stylistic choice is not usually offered by Texinfo.
address@hidden but the Hacker's Dictionary wanted it ...
+
+
address@hidden unnumbered & appendix
address@hidden @code{@@unnumbered} and @code{@@appendix}
address@hidden unnumbered
address@hidden appendix
+
+Use the @code{@@unnumbered} command to create a chapter that appears
+in a printed manual without chapter numbers of any kind. Use the
address@hidden@@appendix} command to create an appendix in a printed manual
+that is labelled by letter instead of by address@hidden
+
+For Info file output, the @code{@@unnumbered} and @code{@@appendix}
+commands are equivalent to @code{@@chapter}: the title is printed on a
+line by itself with a line of asterisks underneath. (@xref{chapter, ,
address@hidden@@chapter}}.)@refill
+
+To create an appendix or an unnumbered chapter, write an
address@hidden@@appendix} or @code{@@unnumbered} command at the beginning of a
+line and follow it on the same line by the title, as you would if you
+were creating a address@hidden
+
+
address@hidden majorheading & chapheading, section, unnumbered & appendix,
Structuring
address@hidden @code{@@majorheading}, @code{@@chapheading}
address@hidden majorheading
address@hidden chapheading
+
+The @code{@@majorheading} and @code{@@chapheading} commands put
+chapter-like headings in the body of a address@hidden
+
+However, neither command causes @TeX{} to produce a numbered heading
+or an entry in the table of contents; and neither command causes
address@hidden to start a new page in a printed address@hidden
+
+In @TeX{}, an @code{@@majorheading} command generates a larger vertical
+whitespace before the heading than an @code{@@chapheading} command but
+is otherwise the address@hidden
+
+In Info,
+the @code{@@majorheading} and
address@hidden@@chapheading} commands are equivalent to
address@hidden@@chapter}: the title is printed on a line by itself with a line
+of asterisks underneath. (@xref{chapter, , @code{@@chapter}}.)@refill
+
address@hidden section, unnumberedsec appendixsec heading, majorheading &
chapheading, Structuring
address@hidden node-name, next, previous, up
address@hidden @code{@@section}
address@hidden section
+
+In a printed manual, an @code{@@section} command identifies a
+numbered section within a chapter. The section title appears in the
+table of contents. In Info, an @code{@@section} command provides a
+title for a segment of text, underlined with @address@hidden
+
+This section is headed with an @code{@@section} command and looks like
+this in the Texinfo file:@refill
+
address@hidden
+@@section @@address@hidden@@@@address@hidden
address@hidden example
+
+To create a section, write the @code{@@section} command at the
+beginning of a line and follow it on the same line by the section
address@hidden
+
+Thus,
+
address@hidden
+@@section This is a section
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+This is a section
+=================
address@hidden group
address@hidden example
+
address@hidden
+in Info.
+
address@hidden unnumberedsec appendixsec heading, subsection, section,
Structuring
address@hidden node-name, next, previous, up
address@hidden @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
address@hidden unnumberedsec
address@hidden appendixsec
address@hidden heading
+
+The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading}
+commands are, respectively, the unnumbered, appendix-like, and
+heading-like equivalents of the @code{@@section} command.
+(@xref{section, , @code{@@section}}.)@refill
+
address@hidden @code
address@hidden @@unnumberedsec
+The @code{@@unnumberedsec} command may be used within an
+unnumbered chapter or within a regular chapter or appendix to
+provide an unnumbered address@hidden
+
address@hidden @@appendixsec
address@hidden @@appendixsection
address@hidden@@appendixsection} is a longer spelling of the
address@hidden@@appendixsec} command; the two are address@hidden
address@hidden appendixsection
+
+Conventionally, the @code{@@appendixsec} or @code{@@appendixsection}
+command is used only within address@hidden
+
address@hidden @@heading
+You may use the @code{@@heading} command anywhere you wish for a
+section-style heading that will not appear in the table of address@hidden
address@hidden table
+
address@hidden subsection, unnumberedsubsec appendixsubsec subheading,
unnumberedsec appendixsec heading, Structuring
address@hidden node-name, next, previous, up
address@hidden The @code{@@subsection} Command
address@hidden subsection
+
+Subsections are to sections as sections are to chapters.
+(@xref{section, , @code{@@section}}.) In Info, subsection titles are
+underlined with @samp{-}. For example,@refill
+
address@hidden
+@@subsection This is a subsection
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+This is a subsection
+--------------------
address@hidden group
address@hidden example
+
+In a printed manual, subsections are listed in the table of contents
+and are numbered three levels address@hidden
+
address@hidden unnumberedsubsec appendixsubsec subheading, subsubsection,
subsection, Structuring
address@hidden node-name, next, previous, up
address@hidden The @code{@@subsection}-like Commands
address@hidden Subsection-like commands
address@hidden unnumberedsubsec
address@hidden appendixsubsec
address@hidden subheading
+
+The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and
address@hidden@@subheading} commands are, respectively, the unnumbered,
+appendix-like, and heading-like equivalents of the @code{@@subsection}
+command. (@xref{subsection, , @code{@@subsection}}.)@refill
+
+In Info, the @code{@@subsection}-like commands generate a title
+underlined with hyphens. In a printed manual, an @code{@@subheading}
+command produces a heading like that of a subsection except that it is
+not numbered and does not appear in the table of contents. Similarly,
+an @code{@@unnumberedsubsec} command produces an unnumbered heading like
+that of a subsection and an @code{@@appendixsubsec} command produces a
+subsection-like heading labelled with a letter and numbers; both of
+these commands produce headings that appear in the table of
address@hidden
+
address@hidden subsubsection, Raise/lower sections, unnumberedsubsec
appendixsubsec subheading, Structuring
address@hidden node-name, next, previous, up
address@hidden The `subsub' Commands
address@hidden Subsub commands
address@hidden subsubsection
address@hidden unnumberedsubsubsec
address@hidden appendixsubsubsec
address@hidden subsubheading
+
+The fourth and lowest level sectioning commands in Texinfo are the
+`subsub' commands. They are:@refill
+
address@hidden @code
address@hidden @@subsubsection
+Subsubsections are to subsections as subsections are to sections.
+(@xref{subsection, , @code{@@subsection}}.) In a printed manual,
+subsubsection titles appear in the table of contents and are numbered
+four levels address@hidden
+
address@hidden @@unnumberedsubsubsec
+Unnumbered subsubsection titles appear in the table of contents of a
+printed manual, but lack numbers. Otherwise, unnumbered
+subsubsections are the same as subsubsections. In Info, unnumbered
+subsubsections look exactly like ordinary address@hidden
+
address@hidden @@appendixsubsubsec
+Conventionally, appendix commands are used only for appendices and are
+lettered and numbered appropriately in a printed manual. They also
+appear in the table of contents. In Info, appendix subsubsections look
+exactly like ordinary address@hidden
+
address@hidden @@subsubheading
+The @code{@@subsubheading} command may be used anywhere that you need
+a small heading that will not appear in the table of contents. In
+Info, subsubheadings look exactly like ordinary subsubsection
address@hidden
address@hidden table
+
+In Info, `subsub' titles are underlined with periods.
+For example,@refill
+
address@hidden
+@@subsubsection This is a subsubsection
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+This is a subsubsection
+.......................
address@hidden group
address@hidden example
+
address@hidden Raise/lower sections, , subsubsection, Structuring
address@hidden node-name, next, previous, up
address@hidden @code{@@raisesections} and @code{@@lowersections}
address@hidden raisesections
address@hidden lowersections
address@hidden Raising and lowering sections
address@hidden Sections, raising and lowering
+
+The @code{@@raisesections} and @code{@@lowersections} commands raise and
+lower the hierarchical level of chapters, sections, subsections and the
+like. The @code{@@raisesections} command changes sections to chapters,
+subsections to sections, and so on. The @code{@@lowersections} command
+changes chapters to sections, sections to subsections, and so on.
+
address@hidden Include files, and section levels
+An @code{@@lowersections} command is useful if you wish to include text
+that is written as an outer or standalone Texinfo file in another
+Texinfo file as an inner, included file. If you write the command at
+the beginning of the file, all your @code{@@chapter} commands are
+formatted as if they were @code{@@section} commands, all your
address@hidden@@section} command are formatted as if they were
address@hidden@@subsection} commands, and so on.
+
address@hidden 1000
address@hidden@@raisesections} raises a command one level in the chapter
+structuring hierarchy:@refill
+
address@hidden
address@hidden
+ @r{Change} @r{To}
+
+@@subsection @@section,
+@@section @@chapter,
+@@heading @@chapheading,
+ @r{etc.}
address@hidden group
address@hidden example
+
address@hidden 1000
address@hidden@@lowersections} lowers a command one level in the chapter
+structuring hierarchy:@refill
+
address@hidden
address@hidden
+ @r{Change} @r{To}
+
+@@chapter @@section,
+@@subsection @@subsubsection,
+@@heading @@subheading,
+ @r{etc.}
address@hidden group
address@hidden example
+
+An @code{@@raisesections} or @code{@@lowersections} command changes only
+those structuring commands that follow the command in the Texinfo file.
+Write an @code{@@raisesections} or @code{@@lowersections} command on a
+line of its own.
+
+An @code{@@lowersections} command cancels an @code{@@raisesections}
+command, and vice versa. Typically, the commands are used like this:
+
address@hidden
+@@lowersections
+@@include somefile.texi
+@@raisesections
address@hidden example
+
+Without the @code{@@raisesections}, all the subsequent sections in your
+document will be lowered.
+
+Repeated use of the commands continue to raise or lower the hierarchical
+level a step at a time.
+
+An attempt to raise above `chapters' reproduces chapter commands; an
+attempt to lower below `subsubsections' reproduces subsubsection
+commands.
+
address@hidden Nodes
address@hidden Nodes
+
address@hidden are the primary segments of a Texinfo file. They do not
+themselves impose a hierarchical or any other kind of structure on a file.
+Nodes contain @dfn{node pointers} that name other nodes, and can contain
address@hidden which are lists of nodes. In Info, the movement commands
+can carry you to a pointed-to node or to a node listed in a menu. Node
+pointers and menus provide structure for Info files just as chapters,
+sections, subsections, and the like, provide structure for printed
address@hidden
+
address@hidden
+* Two Paths:: Different commands to structure
+ Info output and printed output.
+* Node Menu Illustration:: A diagram, and sample nodes and menus.
+* node:: Creating nodes, in detail.
+* makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
+* anchor:: Defining arbitrary cross-reference targets.
address@hidden menu
+
+
address@hidden Two Paths
address@hidden Two Paths
+
+The node and menu commands and the chapter structuring commands are
+technically independent of each other:
+
address@hidden @bullet
address@hidden
+In Info, node and menu commands provide structure. The chapter
+structuring commands generate headings with different kinds of
+underlining---asterisks for chapters, hyphens for sections, and so on;
+they do nothing address@hidden
+
address@hidden
+In @TeX{}, the chapter structuring commands generate chapter and section
+numbers and tables of contents. The node and menu commands provide
+information for cross references; they do nothing address@hidden
address@hidden itemize
+
+You can use node pointers and menus to structure an Info file any way
+you want; and you can write a Texinfo file so that its Info output has a
+different structure than its printed output. However, virtually all
+Texinfo files are written such that the structure for the Info output
+corresponds to the structure for the printed output. It is neither
+convenient nor understandable to the reader to do address@hidden
+
+Generally, printed output is structured in a tree-like hierarchy in
+which the chapters are the major limbs from which the sections branch
+out. Similarly, node pointers and menus are organized to create a
+matching structure in the Info address@hidden
+
+
address@hidden Node Menu Illustration
address@hidden Node and Menu Illustration
+
+Here is a copy of the diagram shown earlier that illustrates a Texinfo
+file with three chapters, each of which contains two address@hidden
+
+The ``root'' is at the top of the diagram and the ``leaves'' are at the
+bottom. This is how such a diagram is drawn conventionally; it
+illustrates an upside-down tree. For this reason, the root node is
+called the `Top' node, and `Up' node pointers carry you closer to the
address@hidden
+
address@hidden
address@hidden
+ Top
+ |
+ -------------------------------------
+ | | |
+ Chapter 1 Chapter 2 Chapter 3
+ | | |
+ -------- -------- --------
+ | | | | | |
+ Section Section Section Section Section Section
+ 1.1 1.2 2.1 2.2 3.1 3.2
address@hidden group
address@hidden example
+
+The fully-written command to start Chapter 2 would be this:
+
address@hidden
address@hidden
+@@node Chapter 2, Chapter 3, Chapter 1, Top
+@@comment node-name, next, previous, up
address@hidden group
address@hidden example
+
address@hidden
+This @code{@@node} line says that the name of this node is ``Chapter
+2'', the name of the `Next' node is ``Chapter 3'', the name of the
+`Previous' node is ``Chapter 1'', and the name of the `Up' node is
+``Top''. You can omit writing out these node names if your document is
+hierarchically organized (@pxref{makeinfo Pointer Creation}), but the
+pointer relationships still obtain.
+
address@hidden
address@hidden Note:} `Next' refers to the next node at the same
+hierarchical level in the manual, not necessarily to the next node
+within the Texinfo file. In the Texinfo file, the subsequent node may
+be at a lower level---a section-level node most often follows a
+chapter-level node, for example. `Next' and `Previous' refer to nodes
+at the @emph{same} hierarchical level. (The `Top' node contains the
+exception to this rule. Since the `Top' node is the only node at that
+level, `Next' refers to the first following node, which is almost always
+a chapter or chapter-level node.)@refill
address@hidden quotation
+
+To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter
+2. (@xref{Menus}.) You would write the menu just
+before the beginning of Section 2.1, like this:@refill
+
address@hidden
address@hidden
+ @@menu
+ * Sect. 2.1:: Description of this section.
+ * Sect. 2.2::
+ @@end menu
address@hidden group
address@hidden example
+
+Write the node for Sect. 2.1 like this:@refill
+
address@hidden
address@hidden
+ @@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
+ @@comment node-name, next, previous, up
address@hidden group
address@hidden example
+
+In Info format, the `Next' and `Previous' pointers of a node usually
+lead to other nodes at the same level---from chapter to chapter or from
+section to section (sometimes, as shown, the `Previous' pointer points
+up); an `Up' pointer usually leads to a node at the level above (closer
+to the `Top' node); and a `Menu' leads to nodes at a level below (closer
+to `leaves'). (A cross reference can point to a node at any level;
+see @ref{Cross References}.)@refill
+
+Usually, an @code{@@node} command and a chapter structuring command are
+used in sequence, along with indexing commands. (You may follow the
address@hidden@@node} line with a comment line that reminds you which pointer is
+which.)@refill
+
+Here is the beginning of the chapter in this manual called ``Ending a
+Texinfo File''. This shows an @code{@@node} line followed by a comment
+line, an @code{@@chapter} line, and then by indexing address@hidden
+
address@hidden
address@hidden
+@@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
address@hidden group
address@hidden example
+
+
address@hidden node
address@hidden The @code{@@node} Command
+
address@hidden Node, defined
address@hidden node
+
+A @dfn{node} is a segment of text that begins at an @code{@@node}
+command and continues until the next @code{@@node} command. The
+definition of node is different from that for chapter or section. A
+chapter may contain sections and a section may contain subsections;
+but a node cannot contain subnodes; the text of a node continues only
+until the next @code{@@node} command in the file. A node usually
+contains only one chapter structuring command, the one that follows
+the @code{@@node} line. On the other hand, in printed output nodes
+are used only for cross references, so a chapter or section may
+contain any number of nodes. Indeed, a chapter usually contains
+several nodes, one for each section, subsection, and
address@hidden
+
+To create a node, write an @code{@@node} command at the beginning of a
+line, and follow it with up to four arguments, separated by commas, on
+the rest of the same line. The first argument is required; it is the
+name of this node. The subsequent arguments are the names of the
+`Next', `Previous', and `Up' pointers, in that order, and may be omitted
+if your Texinfo document is hierarchically organized (@pxref{makeinfo
+Pointer Creation}).
+
+You may insert spaces before each name if you wish; the spaces are
+ignored. You must write the name of the node and the names of the
+`Next', `Previous', and `Up' pointers all on the same line. Otherwise,
+the formatters fail. (@inforef{Top, info, info}, for more information
+about nodes in Info.)
+
+Usually, you write one of the chapter-structuring command lines
+immediately after an @code{@@node} line---for example, an
address@hidden@@section} or @code{@@subsection} line. (@xref{Structuring
+Command Types}.)
+
address@hidden
address@hidden note:} The GNU Emacs Texinfo mode updating commands work
+only with Texinfo files in which @code{@@node} lines are followed by chapter
+structuring lines. @xref{Updating address@hidden
address@hidden quotation
+
address@hidden uses @code{@@node} lines to identify the names to use for cross
+references. For this reason, you must write @code{@@node} lines in a
+Texinfo file that you intend to format for printing, even if you do not
+intend to format it for Info. (Cross references, such as the one at the
+end of this sentence, are made with @code{@@xref} and related commands;
+see @ref{Cross References}.)@refill
+
address@hidden
+* Node Names:: How to choose node and pointer names.
+* Writing a Node:: How to write an @code{@@node} line.
+* Node Line Tips:: Keep names short.
+* Node Line Requirements:: Keep names unique, without @@-commands.
+* First Node:: How to write a `Top' node.
+* makeinfo top command:: How to use the @code{@@top} command.
address@hidden menu
+
+
address@hidden Node Names
address@hidden Choosing Node and Pointer Names
+
address@hidden Node names, choosing
+The name of a node identifies the node. The pointers enable
+you to reach other nodes and consist of the names of those address@hidden
+
+Normally, a node's `Up' pointer contains the name of the node whose menu
+mentions that node. The node's `Next' pointer contains the name of the
+node that follows that node in that menu and its `Previous' pointer
+contains the name of the node that precedes it in that menu. When a
+node's `Previous' node is the same as its `Up' node, both node pointers
+name the same address@hidden
+
+Usually, the first node of a Texinfo file is the `Top' node, and its
+`Up' and `Previous' pointers point to the @file{dir} file, which
+contains the main menu for all of address@hidden
+
+The `Top' node itself contains the main or master menu for the manual.
+Also, it is helpful to include a brief description of the manual in the
+`Top' node. @xref{First Node}, for information on how to write the
+first node of a Texinfo address@hidden
+
+Even when you explicitly specify all pointers, that does not mean you
+can write the nodes in the Texinfo source file in an arbitrary order!
+Because @TeX{} processes the file sequentially, irrespective of node
+pointers, you must write the nodes in the order you wish them to appear
+in the printed output.
+
+
address@hidden Writing a Node
address@hidden How to Write an @code{@@node} Line
address@hidden Writing an @code{@@node} line
address@hidden @code{@@node} line writing
address@hidden Node line writing
+
+The easiest way to write an @code{@@node} line is to write @code{@@node}
+at the beginning of a line and then the name of the node, like
+this:@refill
+
address@hidden
+@@node @var{node-name}
address@hidden example
+
+If you are using GNU Emacs, you can use the update node commands
+provided by Texinfo mode to insert the names of the pointers; or you
+can leave the pointers out of the Texinfo file and let @code{makeinfo}
+insert node pointers into the Info file it creates. (@xref{Texinfo
+Mode}, and @ref{makeinfo Pointer Creation}.)@refill
+
+Alternatively, you can insert the `Next', `Previous', and `Up'
+pointers yourself. If you do this, you may find it helpful to use the
+Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts
address@hidden@@node} and a comment line listing the names of the pointers in
+their proper order. The comment line helps you keep track of which
+arguments are for which pointers. This comment line is especially useful
+if you are not familiar with address@hidden
+
+The template for a fully-written-out node line with `Next', `Previous',
+and `Up' pointers looks like this:@refill
+
address@hidden
+@@node @var{node-name}, @var{next}, @var{previous}, @var{up}
address@hidden example
+
+If you wish, you can ignore @code{@@node} lines altogether in your first
+draft and then use the @code{texinfo-insert-node-lines} command to
+create @code{@@node} lines for you. However, we do not recommend this
+practice. It is better to name the node itself at the same time that
+you write a segment so you can easily make cross references. A large
+number of cross references are an especially important feature of a good
+Info file.
+
+After you have inserted an @code{@@node} line, you should immediately
+write an @@-command for the chapter or section and insert its name.
+Next (and this is important!), put in several index entries. Usually,
+you will find at least two and often as many as four or five ways of
+referring to the node in the index. Use them all. This will make it
+much easier for people to find the node.
+
+
address@hidden Node Line Tips
address@hidden @code{@@node} Line Tips
+
+Here are three suggestions:
+
address@hidden @bullet
address@hidden
+Try to pick node names that are informative but address@hidden
+
+In the Info file, the file name, node name, and pointer names are all
+inserted on one line, which may run into the right edge of the window.
+(This does not cause a problem with Info, but is ugly.)@refill
+
address@hidden
+Try to pick node names that differ from each other near the beginnings
+of their names. This way, it is easy to use automatic name completion in
address@hidden
+
address@hidden
+By convention, node names are capitalized just as they would be for
+section or chapter titles---initial and significant words are
+capitalized; others are address@hidden
address@hidden itemize
+
+
address@hidden Node Line Requirements, First Node, Node Line Tips, node
address@hidden @code{@@node} Line Requirements
+
address@hidden Node line requirements
address@hidden Restrictions on node names
+Here are several requirements for @code{@@node} lines:
+
address@hidden @bullet
address@hidden Unique nodename requirement
address@hidden Node name must be unique
address@hidden
+All the node names for a single Info file must be address@hidden
+
+Duplicates confuse the Info movement commands. This means, for
+example, that if you end every chapter with a summary, you must name
+each summary node differently. You cannot just call each one
+``Summary''. You may, however, duplicate the titles of chapters, sections,
+and the like. Thus you can end each chapter in a book with a section
+called ``Summary'', so long as the node names for those sections are all
address@hidden
+
address@hidden
+A pointer name must be the name of a address@hidden
+
+The node to which a pointer points may come before or after the
+node containing the pointer.
+
address@hidden @@-commands in nodename
address@hidden Node name, should not contain @@-commands
address@hidden
address@hidden@@-commands} used in node names generally confuse Info, so you
+should avoid them. This includes punctuation characters that are
+escaped with a @samp{@@}, such as @code{@@} and @address@hidden For a few
+rare cases when this is useful, Texinfo has limited support for using
address@hidden@@-commands} in node names; see @ref{Pointer Validation}.
+
address@hidden 750
+Thus, the beginning of the section called @code{@@chapter} looks like
+this:@refill
+
address@hidden
address@hidden
+@@node chapter, unnumbered & appendix, makeinfo top, Structuring
+@@comment node-name, next, previous, up
+@@section @@address@hidden@@@@address@hidden
+@@findex chapter
address@hidden group
address@hidden smallexample
+
address@hidden
address@hidden Parentheses in nodename
+You cannot use parentheses in node names, because a node name such as
address@hidden(foo)bar} is interpreted by the Info readers as a node
address@hidden in an Info file @file{foo}.
+
address@hidden
address@hidden Apostrophe in nodename
address@hidden Colon in nodename
address@hidden Comma in nodename
address@hidden Period in nodename
address@hidden Characters, invalid in node name
address@hidden Invalid characters in node names
+Unfortunately, you cannot use periods, commas, colons or apostrophes
+within a node name; these confuse @TeX{} or the Info formatters.
+
address@hidden 700
+For example, the following is a section title:
+
address@hidden
+@@address@hidden@@@@address@hidden, @@address@hidden@@@@address@hidden,
@@address@hidden@@@@address@hidden
address@hidden smallexample
+
address@hidden
+The corresponding node name is:
+
address@hidden
+unnumberedsec appendixsec heading
address@hidden smallexample
+
address@hidden Case in node name
address@hidden
+Case is significant.
address@hidden itemize
+
+
address@hidden First Node
address@hidden The First Node
address@hidden Top node is first
address@hidden First node
+
+The first node of a Texinfo file is the @dfn{Top} node, except in an
+included file (@pxref{Include Files}). The Top node should contain a
+short summary, copying permissions, and a master menu. @xref{The Top
+Node}, for more information on the Top node contents and examples.
+
+Here is a description of the node pointers to be used in the Top node:
+
address@hidden @bullet
+
address@hidden
address@hidden Up node of Top node
address@hidden (dir) as Up node of Top node
+The Top node (which must be named @samp{top} or @samp{Top}) should have
+as its `Up' node the name of a node in another file, where there is a
+menu that leads to this file. Specify the file name in parentheses.
+
+Usually, all Info files are installed in the same Info directory tree;
+in this case, use @samp{(dir)} as the parent of the Top node; this is
+short for @samp{(dir)top}, and specifies the Top node in the @file{dir}
+file, which contains the main menu for the Info system as a whole.
+
address@hidden
address@hidden Previous node of Top node
+On the other hand, do not define the `Previous' node of the Top node to
+be @samp{(dir)}, as it causes confusing behavior for users: if you are
+in the Top node and hits @key{DEL} to go backwards, you wind up in the
+middle of the some other entry in the @file{dir} file, which has nothing
+to do with what you were reading.
+
address@hidden
address@hidden Next node of Top node
+The `Next' node of the Top node should be the first chapter in your
+document.
+
address@hidden itemize
+
address@hidden an Info File}, for more information about installing
+an Info file in the @file{info} directory.
+
+For concreteness, here is an example with explicit pointers (which you
+can maintain automatically with the texinfo mode commands):
+
+Or you can leave the pointers off entirely and let the tools implicitly
+define them. This is recommended. Thus:
+
address@hidden
+@@node Top
address@hidden example
+
+
address@hidden makeinfo top command
address@hidden The @code{@@top} Sectioning Command
address@hidden top @r{(@@-command)}
+
+A special sectioning command, @code{@@top} should be used with the
address@hidden@@node Top} line. The @code{@@top} sectioning command tells
address@hidden that it marks the `Top' node in the file. It provides
+the information that @code{makeinfo} needs to insert node pointers
+automatically. Write the @code{@@top} command at the beginning of the
+line immediately following the @code{@@node Top} line. Write the title
+on the remaining part of the same line as the @code{@@top} command.
+
+In Info, the @code{@@top} sectioning command causes the title to appear
+on a line by itself, with a line of asterisks inserted underneath, as
+other sectioning commands do.
+
+In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
+sectioning command is merely a synonym for @code{@@unnumbered}.
+Neither of these formatters require an @code{@@top} command, and do
+nothing special with it. You can use @code{@@chapter} or
address@hidden@@unnumbered} after the @code{@@node Top} line when you use
+these formatters. Also, you can use @code{@@chapter} or
address@hidden@@unnumbered} when you use the Texinfo updating commands to
+create or update pointers and menus.
+
+Thus, in practice, a Top node starts like this:
+
address@hidden
+@@node Top
+@@top Your Manual Title
address@hidden example
+
+
address@hidden makeinfo Pointer Creation
address@hidden Creating Pointers with @code{makeinfo}
address@hidden Creating pointers with @code{makeinfo}
address@hidden Pointer creation with @code{makeinfo}
address@hidden Automatic pointer creation with @code{makeinfo}
+
+The @code{makeinfo} program has a feature for automatically defining
+node pointers for a hierarchically organized file.
+
+When you take advantage of this feature, you do not need to write the
+`Next', `Previous', and `Up' pointers after the name of a node.
+However, you must write a sectioning command, such as @code{@@chapter}
+or @code{@@section}, on the line immediately following each truncated
address@hidden@@node} line (except that comment lines may intervene).
+
+In addition, you must follow the `Top' @code{@@node} line with a line
+beginning with @code{@@top} to mark the `Top' node in the
+file. @xref{makeinfo top, , @code{@@top}}.
+
+Finally, you must write the name of each node (except for the `Top'
+node) in a menu that is one or more hierarchical levels above the
+node's hierarchical level.
+
+This node pointer insertion feature in @code{makeinfo} relieves you from
+the need to update menus and pointers manually or with Texinfo mode
+commands. (@xref{Updating Nodes and Menus}.)
+
+In most cases, you will want to take advantage of this feature and not
+redundantly specify node pointers. However, Texinfo documents are not
+required to be organized hierarchically or in fact contain sectioning
+commands at all. For example, if you never intend the document to be
+printed. In those cases, you will need to explicitly specify the pointers.
+
+
address@hidden anchor
address@hidden @code{@@anchor}: Defining Arbitrary Cross-reference Targets
+
address@hidden anchor
address@hidden Anchors
address@hidden Cross-reference targets, arbitrary
address@hidden Targets for cross-references, arbitrary
+
+An @dfn{anchor} is a position in your document, labeled so that
+cross-references can refer to it, just as they can to nodes. You create
+an anchor with the @code{@@anchor} command, and give the label as a
+normal brace-delimited argument. For example:
+
address@hidden
+This marks the @@address@hidden@}spot.
address@hidden
+@@address@hidden,,the address@hidden
address@hidden example
+
address@hidden produces:
+
address@hidden
+This marks the spot.
address@hidden
+See [the spot], page 1.
address@hidden example
+
+As you can see, the @code{@@anchor} command itself produces no output.
+This example defines an anchor `x-spot' just before the word `spot'.
+You can refer to it later with an @code{@@xref} or other cross-reference
+command, as shown. @xref{Cross References}, for details on the
+cross-reference commands.
+
+It is best to put @code{@@anchor} commands just before the position you
+wish to refer to; that way, the reader's eye is led on to the correct
+text when they jump to the anchor. You can put the @code{@@anchor}
+command on a line by itself if that helps readability of the source.
+Spaces are always ignored after @code{@@anchor}.
+
+Anchor names and node names may not conflict. Anchors and nodes are
+given similar treatment in some ways; for example, the @code{goto-node}
+command in standalone Info takes either an anchor name or a node name as
+an argument. (@xref{goto-node,,,info-stnd,GNU Info}.)
+
+
address@hidden Menus
address@hidden Menus
address@hidden Menus
address@hidden menu
+
address@hidden contain pointers to subordinate address@hidden can
+carry you to any node, regardless of the hierarchical structure; even to
+nodes in a different Info file. However, the GNU Emacs Texinfo mode
+updating commands work only to create menus of subordinate nodes.
+Conventionally, cross references are used to refer to other nodes.} In
+Info, you use menus to go to such nodes. Menus have no effect in
+printed manuals and do not appear in them.
+
+By convention, a menu is put at the end of a node since a reader who
+uses the menu may not see text that follows it. Furthermore, a node
+that has a menu should not contain much text. If you have a lot of text
+and a menu, move most of the text into a new subnode---all but a few
+lines. Otherwise, a reader with a terminal that displays only a few
+lines may miss the menu and its associated text. As a practical matter,
+you should locate a menu within 20 lines of the beginning of the
+node.
+
address@hidden
+* Menu Location:: Put a menu in a short node.
+* Writing a Menu:: What is a menu?
+* Menu Parts:: A menu entry has three parts.
+* Less Cluttered Menu Entry:: Two part menu entry.
+* Menu Example:: Two and three part menu entries.
+* Other Info Files:: How to refer to a different Info file.
address@hidden menu
+
+
address@hidden Menu Location, Writing a Menu, Menus, Menus
address@hidden Menus Need Short Nodes
address@hidden Menu location
address@hidden Location of menus
address@hidden Nodes for menus are short
address@hidden Short nodes for menus
+
+The short text before a menu may look awkward in a printed manual. To
+avoid this, you can write a menu near the beginning of its node and
+follow the menu by an @code{@@node} line, and then an @code{@@heading}
+line located within @code{@@ifinfo} and @code{@@end ifinfo}. This way,
+the menu, @code{@@node} line, and title appear only in the Info file,
+not the printed document.
+
+For example, the preceding two paragraphs follow an Info-only menu,
address@hidden@@node} line, and heading, and look like this:
+
address@hidden
address@hidden
+@@menu
+* Menu Location:: Put a menu in a short node.
+* Writing a Menu:: What is a menu?
+* Menu Parts:: A menu entry has three parts.
+* Less Cluttered Menu Entry:: Two part menu entry.
+* Menu Example:: Two and three part entries.
+* Other Info Files:: How to refer to a different
+ Info file.
+@@end menu
+
+@@node Menu Location, Writing a Menu, , Menus
+@@ifinfo
+@@heading Menus Need Short Nodes
+@@end ifinfo
address@hidden group
address@hidden example
+
+The Texinfo file for this document contains a number of
+examples of this procedure; one is at the beginning of this chapter.
+
+
address@hidden Writing a Menu, Menu Parts, Menu Location, Menus
address@hidden Writing a Menu
address@hidden Writing a menu
address@hidden Menu writing
+
+A menu consists of an @code{@@menu} command on a line by
+itself followed by menu entry lines or menu comment lines
+and then by an @code{@@end menu} command on a line by
address@hidden
+
+A menu looks like this:@refill
+
address@hidden
address@hidden
+@@menu
+Larger Units of Text
+
+* Files:: All about handling files.
+* Multiples: Buffers. Multiple buffers; editing
+ several files at once.
+@@end menu
address@hidden group
address@hidden example
+
+In a menu, every line that begins with an @address@hidden }} is a @dfn{menu
+entry}. (Note the space after the asterisk.) A line that does not
+start with an @address@hidden }} may also appear in a menu. Such a line is
+not a menu entry but is a menu comment line that appears in the Info
+file. In the example above, the line @samp{Larger Units of Text} is a
+menu comment line; the two lines starting with @address@hidden }} are menu
address@hidden Spaces, in menus
+entries. Space characters in a menu are preserved as-is; this allows
+you to format the menu as you wish.
+
+
address@hidden Menu Parts, Less Cluttered Menu Entry, Writing a Menu, Menus
address@hidden The Parts of a Menu
address@hidden Parts of a menu
address@hidden Menu parts
address@hidden @code{@@menu} parts
+
+A menu entry has three parts, only the second of which is required:
+
address@hidden
address@hidden
+The menu entry name (optional).
+
address@hidden
+The name of the node (required).
+
address@hidden
+A description of the item (optional).
address@hidden enumerate
+
+The template for a menu entry looks like this:@refill
+
address@hidden
+* @var{menu-entry-name}: @var{node-name}. @var{description}
address@hidden example
+
+Follow the menu entry name with a single colon and follow the node name
+with tab, comma, period, or address@hidden
+
+In Info, a user selects a node with the @kbd{m} (@code{Info-menu})
+command. The menu entry name is what the user types after the @kbd{m}
address@hidden
+
+The third part of a menu entry is a descriptive phrase or sentence.
+Menu entry names and node names are often short; the description
+explains to the reader what the node is about. A useful description
+complements the node name rather than repeats it. The description,
+which is optional, can spread over two or more lines; if it does, some
+authors prefer to indent the second line while others prefer to align it
+with the first (and all others). It's up to you.
+
+
address@hidden Less Cluttered Menu Entry, Menu Example, Menu Parts, Menus
address@hidden node-name, next, previous, up
address@hidden Less Cluttered Menu Entry
address@hidden Two part menu entry
address@hidden Double-colon menu entries
address@hidden Menu entries with two colons
address@hidden Less cluttered menu entry
address@hidden Uncluttered menu entry
+
+When the menu entry name and node name are the same, you can write
+the name immediately after the asterisk and space at the beginning of
+the line and follow the name with two address@hidden
+
address@hidden 800
+For example, write
+
address@hidden
+* Name:: @var{description}
address@hidden example
+
address@hidden 800
address@hidden
+instead of
+
address@hidden
+* Name: Name. @var{description}
address@hidden example
+
+You should use the node name for the menu entry name whenever possible,
+since it reduces visual clutter in the address@hidden
+
address@hidden Menu Example, Other Info Files, Less Cluttered Menu Entry, Menus
address@hidden node-name, next, previous, up
address@hidden A Menu Example
address@hidden Menu example
address@hidden Example menu
+
+A menu looks like this in Texinfo:@refill
+
address@hidden
address@hidden
+@@menu
+* menu entry name: Node name. A short description.
+* Node name:: This form is preferred.
+@@end menu
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+This produces:
+
address@hidden
address@hidden
+* menu:
+
+* menu entry name: Node name. A short description.
+* Node name:: This form is preferred.
address@hidden group
address@hidden example
+
address@hidden 700
+Here is an example as you might see it in a Texinfo file:@refill
+
address@hidden
address@hidden
+@@menu
+Larger Units of Text
+
+* Files:: All about handling files.
+* Multiples: Buffers. Multiple buffers; editing
+ several files at once.
+@@end menu
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+This produces:
+
address@hidden
address@hidden
+* menu:
+Larger Units of Text
+
+* Files:: All about handling files.
+* Multiples: Buffers. Multiple buffers; editing
+ several files at once.
address@hidden group
address@hidden example
+
+In this example, the menu has two entries. @samp{Files} is both a menu
+entry name and the name of the node referred to by that name.
address@hidden is the menu entry name; it refers to the node named
address@hidden The line @samp{Larger Units of Text} is a comment; it
+appears in the menu, but is not an address@hidden
+
+Since no file name is specified with either @samp{Files} or
address@hidden, they must be the names of nodes in the same Info file
+(@pxref{Other Info Files, , Referring to Other Info Files})address@hidden
+
address@hidden Other Info Files, , Menu Example, Menus
address@hidden node-name, next, previous, up
address@hidden Referring to Other Info Files
address@hidden Referring to other Info files
address@hidden Nodes in other Info files
address@hidden Other Info files' nodes
address@hidden Going to other Info files' nodes
address@hidden Info; other files' nodes
+
+You can create a menu entry that enables a reader in Info to go to a
+node in another Info file by writing the file name in parentheses just
+before the node name. In this case, you should use the three-part menu
+entry format, which saves the reader from having to type the file
address@hidden
+
address@hidden 800
+The format looks like this:@refill
+
address@hidden
address@hidden
+@@menu
+* @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description}
+* @var{second-entry-name}:(@var{filename})@var{second-node}. @var{description}
+@@end menu
address@hidden group
address@hidden example
+
+For example, to refer directly to the @samp{Outlining} and
address@hidden nodes in the @cite{Emacs Manual}, you would write a
+menu like this:@refill
+
address@hidden
address@hidden
+@@menu
+* Outlining: (emacs)Outline Mode. The major mode for
+ editing outlines.
+* Rebinding: (emacs)Rebinding. How to redefine the
+ meaning of a key.
+@@end menu
address@hidden group
address@hidden example
+
+If you do not list the node name, but only name the file, then Info
+presumes that you are referring to the `Top' address@hidden
+
+The @file{dir} file that contains the main menu for Info has menu
+entries that list only file names. These take you directly to the `Top'
+nodes of each Info document. (@xref{Installing an Info File}.)
+
address@hidden 700
+For example:
+
address@hidden
address@hidden
+* Info: (info). Documentation browsing system.
+* Emacs: (emacs). The extensible, self-documenting
+ text editor.
address@hidden group
address@hidden example
+
address@hidden
+(The @file{dir} top level directory for the Info system is an Info file,
+not a Texinfo file, but a menu entry looks the same in both types of
+file.)@refill
+
+The GNU Emacs Texinfo mode menu updating commands only work with nodes
+within the current buffer, so you cannot use them to create menus that
+refer to other files. You must write such menus by hand.
+
+
address@hidden Cross References
address@hidden Cross References
address@hidden Making cross references
address@hidden Cross references
address@hidden References
+
address@hidden references} are used to refer the reader to other parts of the
+same or different Texinfo files. In Texinfo, nodes and anchors are the
+places to which cross references can refer.
+
address@hidden
+* References:: What cross references are for.
+* Cross Reference Commands:: A summary of the different commands.
+* Cross Reference Parts:: A cross reference has several parts.
+* xref:: Begin a reference with `See' @dots{}
+* Top Node Naming:: How to refer to the beginning of another file.
+* ref:: A reference for the last part of a sentence.
+* pxref:: How to write a parenthetical cross reference.
+* inforef:: How to refer to an Info-only file.
+* uref:: How to refer to a uniform resource locator.
address@hidden menu
+
address@hidden References, Cross Reference Commands, Cross References, Cross
References
address@hidden What References Are For
+
+Often, but not always, a printed document should be designed so that
+it can be read sequentially. People tire of flipping back and forth
+to find information that should be presented to them as they need
address@hidden
+
+However, in any document, some information will be too detailed for
+the current context, or incidental to it; use cross references to
+provide access to such information. Also, an online help system or a
+reference manual is not like a novel; few read such documents in
+sequence from beginning to end. Instead, people look up what they
+need. For this reason, such creations should contain many cross
+references to help readers find other information that they may not
+have address@hidden
+
+In a printed manual, a cross reference results in a page reference,
+unless it is to another manual altogether, in which case the cross
+reference names that address@hidden
+
+In Info, a cross reference results in an entry that you can follow using
+the Info @samp{f} command. (@inforef{Help-Adv, Some advanced Info
+commands, info}.)@refill
+
+The various cross reference commands use nodes (or anchors,
address@hidden,,@code{@@anchor}}) to define cross reference locations.
+This is evident in Info, in which a cross reference takes you to the
+specified location. @TeX{} also uses nodes to define cross reference
+locations, but the action is less obvious. When @TeX{} generates a DVI
+file, it records each node's page number and uses the page numbers in making
+references. Thus, if you are writing a manual that will only be
+printed, and will not be used online, you must nonetheless write
address@hidden@@node} lines to name the places to which you make cross
address@hidden
+
address@hidden 800
address@hidden Cross Reference Commands, Cross Reference Parts, References,
Cross References
address@hidden node-name, next, previous, up
address@hidden Different Cross Reference Commands
address@hidden Different cross reference commands
+
+There are four different cross reference commands:@refill
+
address@hidden @code
address@hidden @@xref
+Used to start a sentence in the printed manual saying @w{`See @dots{}'}
+or an Info cross-reference saying @samp{*Note @var{name}: @var{node}.}.
+
address@hidden @@ref
+Used within or, more often, at the end of a sentence; same as
address@hidden@@xref} for Info; produces just the reference in the printed
+manual without a preceding `See'address@hidden
+
address@hidden @@pxref
+Used within parentheses to make a reference that suits both an Info
+file and a printed book. Starts with a lower case `see' within the
+printed manual. (@samp{p} is for `parenthesis'.)@refill
+
address@hidden @@inforef
+Used to make a reference to an Info file for which there is no printed
address@hidden
address@hidden table
+
address@hidden
+(The @code{@@cite} command is used to make references to books and
+manuals for which there is no corresponding Info file and, therefore,
+no node to which to point. @xref{cite, , @code{@@cite}}.)@refill
+
address@hidden Cross Reference Parts, xref, Cross Reference Commands, Cross
References
address@hidden node-name, next, previous, up
address@hidden Parts of a Cross Reference
address@hidden Cross reference parts
address@hidden Parts of a cross reference
+
+A cross reference command requires only one argument, which is the
+name of the node to which it refers. But a cross reference command
+may contain up to four additional arguments. By using these
+arguments, you can provide a cross reference name for Info, a topic
+description or section title for the printed output, the name of a
+different Info file, and the name of a different printed
address@hidden
+
+Here is a simple cross reference example:@refill
+
address@hidden
+@@address@hidden address@hidden
address@hidden example
+
address@hidden
+which produces
+
address@hidden
+*Note Node name::.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See Section @var{nnn} [Node name], page @var{ppp}.
address@hidden quotation
+
address@hidden 700
+Here is an example of a full five-part cross reference:@refill
+
address@hidden
address@hidden
+@@address@hidden name, Cross Reference Name, Particular Topic,
+info-file-name, A Printed address@hidden, for details.
address@hidden group
address@hidden example
+
address@hidden
+which produces
+
address@hidden
+*Note Cross Reference Name: (info-file-name)Node name,
+for details.
address@hidden example
+
address@hidden
+in Info and
+
address@hidden
+See section ``Particular Topic'' in @i{A Printed Manual}, for details.
address@hidden quotation
+
address@hidden
+in a printed book.
+
+The five possible arguments for a cross reference are:@refill
+
address@hidden
address@hidden
+The node or anchor name (required). This is the location to which the
+cross reference takes you. In a printed document, the location of the
+node provides the page reference only for references within the same
address@hidden
+
address@hidden
+The cross reference name for the Info reference, if it is to be different
+from the node name. If you include this argument, it becomes
+the first part of the cross reference. It is usually address@hidden
+
address@hidden
+A topic description or section name. Often, this is the title of the
+section. This is used as the name of the reference in the printed
+manual. If omitted, the node name is address@hidden
+
address@hidden
+The name of the Info file in which the reference is located, if it is
+different from the current file. You need not include any @samp{.info}
+suffix on the file name, since Info readers try appending it
+automatically.
+
address@hidden
+The name of a printed manual from a different Texinfo address@hidden
address@hidden enumerate
+
+The template for a full five argument cross reference looks like
+this:@refill
+
address@hidden
address@hidden
+@@address@hidden@var{node-name}, @var{cross-reference-name},
@var{title-or-topic},
address@hidden, @address@hidden
address@hidden group
address@hidden example
+
+Cross references with one, two, three, four, and five arguments are
+described separately following the description of @code{@@address@hidden
+
+Write a node name in a cross reference in exactly the same way as in
+the @code{@@node} line, including the same capitalization; otherwise, the
+formatters may not find the address@hidden
+
+You can write cross reference commands within a paragraph, but note
+how Info and @TeX{} format the output of each of the various commands:
+write @code{@@xref} at the beginning of a sentence; write
address@hidden@@pxref} only within parentheses, and so address@hidden
+
address@hidden xref, Top Node Naming, Cross Reference Parts, Cross References
address@hidden node-name, next, previous, up
address@hidden @code{@@xref}
address@hidden xref
address@hidden Cross references using @code{@@xref}
address@hidden References using @code{@@xref}
+
+The @code{@@xref} command generates a cross reference for the
+beginning of a sentence. The Info formatting commands convert it into
+an Info cross reference, which the Info @samp{f} command can use to
+bring you directly to another node. The @TeX{} typesetting commands
+convert it into a page reference, or a reference to another book or
address@hidden
+
address@hidden
+* Reference Syntax:: What a reference looks like and requires.
+* 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.
address@hidden menu
+
address@hidden Reference Syntax, One Argument, xref, xref
address@hidden What a Reference Looks Like and Requires
+
+Most often, an Info cross reference looks like this:@refill
+
address@hidden
+*Note @var{node-name}::.
address@hidden example
+
address@hidden
+or like this
+
address@hidden
+*Note @var{cross-reference-name}: @var{node-name}.
address@hidden example
+
address@hidden
+In @TeX{}, a cross reference looks like this:
+
address@hidden
+See Section @var{section-number} address@hidden, page @var{page}.
address@hidden quotation
+
address@hidden
+or like this
+
address@hidden
+See Section @var{section-number} address@hidden, page @var{page}.
address@hidden quotation
+
+The @code{@@xref} command does not generate a period or comma to end
+the cross reference in either the Info file or the printed output.
+You must write that period or comma yourself; otherwise, Info will not
+recognize the end of the reference. (The @code{@@pxref} command works
+differently. @xref{pxref, , @code{@@pxref}}.)@refill
+
address@hidden
address@hidden note:} A period or comma @strong{must} follow the closing
+brace of an @code{@@xref}. It is required to terminate the cross
+reference. This period or comma will appear in the output, both in
+the Info file and in the printed address@hidden
address@hidden quotation
+
address@hidden@@xref} must refer to an Info node by name. Use @code{@@node}
+to define the node (@pxref{Writing a Node})address@hidden
+
address@hidden@@xref} is followed by several arguments inside braces, separated
by
+commas. Whitespace before and after these commas is address@hidden
+
+A cross reference requires only the name of a node; but it may contain
+up to four additional arguments. Each of these variations produces a
+cross reference that looks somewhat address@hidden
+
address@hidden
address@hidden note:} Commas separate arguments in a cross reference;
+avoid including them in the title or other part lest the formatters
+mistake them for address@hidden
address@hidden quotation
+
address@hidden One Argument, Two Arguments, Reference Syntax, xref
address@hidden @code{@@xref} with One Argument
+
+The simplest form of @code{@@xref} takes one argument, the name of
+another node in the same Info file. The Info formatters produce
+output that the Info readers can use to jump to the reference; @TeX{}
+produces output that specifies the page and section number for address@hidden
+
address@hidden 700
address@hidden
+For example,
+
address@hidden
+@@address@hidden address@hidden
address@hidden example
+
address@hidden
+produces
+
address@hidden
+*Note Tropical Storms::.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See Section 3.1 [Tropical Storms], page 24.
address@hidden quotation
+
address@hidden
+(Note that in the preceding example the closing brace is followed by a
+period.)@refill
+
+You can write a clause after the cross reference, like this:@refill
+
address@hidden
+@@address@hidden address@hidden, for more info.
address@hidden example
+
address@hidden
+which produces
+
address@hidden
+*Note Tropical Storms::, for more info.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See Section 3.1 [Tropical Storms], page 24, for more info.
address@hidden quotation
+
address@hidden
+(Note that in the preceding example the closing brace is followed by a
+comma, and then by the clause, which is followed by a period.)@refill
+
address@hidden Two Arguments, Three Arguments, One Argument, xref
address@hidden @code{@@xref} with Two Arguments
+
+With two arguments, the second is used as the name of the Info cross
+reference, while the first is still the name of the node to which the
+cross reference address@hidden
+
address@hidden 750
address@hidden
+The template is like this:
+
address@hidden
+@@address@hidden@var{node-name}, @address@hidden
address@hidden example
+
address@hidden 700
address@hidden
+For example,
+
address@hidden
+@@address@hidden Effects, address@hidden
address@hidden example
+
address@hidden
+produces:
+
address@hidden
+*Note Lightning: Electrical Effects.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See Section 5.2 [Electrical Effects], page 57.
address@hidden quotation
+
address@hidden
+(Note that in the preceding example the closing brace is followed by a
+period; and that the node name is printed, not the cross reference name.)
+
+You can write a clause after the cross reference, like this:@refill
+
address@hidden
+@@address@hidden Effects, address@hidden, for more info.
address@hidden example
+
address@hidden
+which produces
address@hidden
+*Note Lightning: Electrical Effects, for more info.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See Section 5.2 [Electrical Effects], page 57, for more info.
address@hidden quotation
+
address@hidden
+(Note that in the preceding example the closing brace is followed by a
+comma, and then by the clause, which is followed by a period.)@refill
+
address@hidden Three Arguments, Four and Five Arguments, Two Arguments, xref
address@hidden @code{@@xref} with Three Arguments
+
+A third argument replaces the node name in the @TeX{} output. The third
+argument should be the name of the section in the printed output, or
+else state the topic discussed by that section. Often, you will want to
+use initial upper case letters so it will be easier to read when the
+reference is printed. Use a third argument when the node name is
+unsuitable because of syntax or address@hidden
+
+Remember to avoid placing a comma within the title or topic section of
+a cross reference, or within any other section. The formatters divide
+cross references into arguments according to the commas; a comma
+within a title or other section will divide it into two arguments. In
+a reference, you need to write a title such as ``Clouds, Mist, and
+Fog'' without the address@hidden
+
+Also, remember to write a comma or period after the closing brace of an
address@hidden@@xref} to terminate the cross reference. In the following
+examples, a clause follows a terminating address@hidden
+
+
address@hidden 750
address@hidden
+The template is like this:
+
address@hidden
address@hidden
+@@address@hidden@var{node-name}, @var{cross-reference-name}, @address@hidden
address@hidden group
address@hidden example
+
address@hidden 700
address@hidden
+For example,
+
address@hidden
address@hidden
+@@address@hidden Effects, Lightning, Thunder and address@hidden,
+for details.
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
+*Note Lightning: Electrical Effects, for details.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See Section 5.2 [Thunder and Lightning], page 57, for details.
address@hidden quotation
+
+If a third argument is given and the second one is empty, then the
+third argument serves both. (Note how two commas, side by side, mark
+the empty second argument.)@refill
+
address@hidden
address@hidden
+@@address@hidden Effects, , Thunder and address@hidden,
+for details.
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
+*Note Thunder and Lightning: Electrical Effects, for details.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See Section 5.2 [Thunder and Lightning], page 57, for details.
address@hidden quotation
+
+As a practical matter, it is often best to write cross references with
+just the first argument if the node name and the section title are the
+same, and with the first and third arguments if the node name and title
+are address@hidden
+
+Here are several examples from @cite{The GNU Awk User's Guide}:@refill
+
address@hidden
+@@address@hidden address@hidden
+@@address@hidden@}.
+@@address@hidden, ,Case-sensitivity in address@hidden
+@@address@hidden Output, , Closing Output Files and address@hidden,
+ for more information.
+@@address@hidden, , Regular Expressions as address@hidden
address@hidden smallexample
+
address@hidden Four and Five Arguments, , Three Arguments, xref
address@hidden @code{@@xref} with Four and Five Arguments
+
+In a cross reference, a fourth argument specifies the name of another
+Info file, different from the file in which the reference appears, and
+a fifth argument specifies its title as a printed address@hidden
+
+Remember that a comma or period must follow the closing brace of an
address@hidden@@xref} command to terminate the cross reference. In the
+following examples, a clause follows a terminating address@hidden
+
address@hidden 800
address@hidden
+The template is:
+
address@hidden
address@hidden
+@@address@hidden@var{node-name}, @var{cross-reference-name},
@var{title-or-topic},
address@hidden, @address@hidden
address@hidden group
address@hidden example
+
address@hidden 700
address@hidden
+For example,
+
address@hidden
+@@address@hidden Effects, Lightning, Thunder and Lightning,
+weather, An Introduction to address@hidden, for details.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+*Note Lightning: (weather)Electrical Effects, for details.
address@hidden example
+
address@hidden
+The name of the Info file is enclosed in parentheses and precedes
+the name of the node.
+
address@hidden
+In a printed manual, the reference looks like this:@refill
+
address@hidden
+See section ``Thunder and Lightning'' in @i{An Introduction to
+Meteorology}, for details.
address@hidden quotation
+
address@hidden
+The title of the printed manual is typeset in italics; and the
+reference lacks a page number since @TeX{} cannot know to which page a
+reference refers when that reference is to another address@hidden
+
+Often, you will leave out the second argument when you use the long
+version of @code{@@xref}. In this case, the third argument, the topic
+description, will be used as the cross reference name in address@hidden
+
address@hidden
+The template looks like this:
+
address@hidden
+@@address@hidden@var{node-name}, , @var{title-or-topic}, @var{info-file-name},
address@hidden@}, for details.
address@hidden example
+
address@hidden
+which produces
+
address@hidden
+*Note @var{title-or-topic}: (@var{info-file-name})@var{node-name}, for details.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See section @var{title-or-topic} in @var{printed-manual-title}, for details.
address@hidden quotation
+
address@hidden 700
address@hidden
+For example,
+
address@hidden
+@@address@hidden Effects, , Thunder and Lightning,
+weather, An Introduction to address@hidden, for details.
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+*Note Thunder and Lightning: (weather)Electrical Effects,
+for details.
address@hidden group
address@hidden example
+
address@hidden
+and
+
address@hidden
+See section ``Thunder and Lightning'' in @i{An Introduction to
+Meteorology}, for details.
address@hidden quotation
+
+On rare occasions, you may want to refer to another Info file that
+is within a single printed manual---when multiple Texinfo files are
+incorporated into the same @TeX{} run but make separate Info files.
+In this case, you need to specify only the fourth argument, and not
+the address@hidden
+
address@hidden Top Node Naming, ref, xref, Cross References
address@hidden Naming a `Top' Node
address@hidden Naming a `Top' Node in references
address@hidden @address@hidden node naming for references
+
+In a cross reference, you must always name a node. This means that in
+order to refer to a whole manual, you must identify the `Top' node by
+writing it as the first argument to the @code{@@xref} command. (This
+is different from the way you write a menu entry; see @ref{Other Info
+Files, , Referring to Other Info Files}.) At the same time, to
+provide a meaningful section topic or title in the printed cross
+reference (instead of the word `Top'), you must write an appropriate
+entry for the third argument to the @code{@@xref} command.
address@hidden
+
address@hidden
+Thus, to make a cross reference to @cite{The GNU Make Manual},
+write:@refill
+
address@hidden
+@@address@hidden, , Overview, make, The GNU Make address@hidden
address@hidden example
+
address@hidden
+which produces
+
address@hidden
+*Note Overview: (make)Top.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See section ``Overview'' in @i{The GNU Make Manual}.
address@hidden quotation
+
address@hidden
+In this example, @samp{Top} is the name of the first node, and
address@hidden is the name of the first section of the address@hidden
address@hidden ref, pxref, Top Node Naming, Cross References
address@hidden node-name, next, previous, up
address@hidden @code{@@ref}
address@hidden Cross references using @code{@@ref}
address@hidden References using @code{@@ref}
address@hidden ref
+
address@hidden@@ref} is nearly the same as @code{@@xref} except that it does
+not generate a `See' in the printed output, just the reference itself.
+This makes it useful as the last part of a address@hidden
+
address@hidden 700
address@hidden
+For example,
+
address@hidden Hurricanes
address@hidden
+For more information, see @@address@hidden@}.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+For more information, see *Note Hurricanes::.
address@hidden example
+
address@hidden
+and
+
address@hidden
+For more information, see Section 8.2 [Hurricanes], page 123.
address@hidden quotation
+
+The @code{@@ref} command sometimes leads writers to express themselves
+in a manner that is suitable for a printed manual but looks awkward
+in the Info format. Bear in mind that your audience will be using
+both the printed and the Info address@hidden
+
address@hidden 800
address@hidden
+For example,
+
address@hidden Sea surges
address@hidden
address@hidden
+Sea surges are described in @@address@hidden@}.
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+produces
+
address@hidden
+Sea surges are described in Section 6.7 [Hurricanes], page 72.
address@hidden quotation
+
address@hidden 800
address@hidden
+in a printed document, and the following in Info:
+
address@hidden
+Sea surges are described in *Note Hurricanes::.
address@hidden example
+
address@hidden
address@hidden:} You @emph{must} write a period, comma, or right
+parenthesis immediately after an @code{@@ref} command with two or more
+arguments. Otherwise, Info will not find the end of the cross reference
+entry and its attempt to follow the cross reference will fail. As a
+general rule, you should write a period or comma after every
address@hidden@@ref} command. This looks best in both the printed and the Info
address@hidden
address@hidden quotation
+
address@hidden pxref, inforef, ref, Cross References
address@hidden node-name, next, previous, up
address@hidden @code{@@pxref}
address@hidden Cross references using @code{@@pxref}
address@hidden References using @code{@@pxref}
address@hidden pxref
+
+The parenthetical reference command, @code{@@pxref}, is nearly the
+same as @code{@@xref}, but you use it @emph{only} inside parentheses
+and you do @emph{not} type a comma or period after the command's
+closing brace. The command differs from @code{@@xref} in two
+ways:@refill
+
address@hidden
address@hidden
address@hidden typesets the reference for the printed manual with a lower case
+`see' rather than an upper case `See'address@hidden
+
address@hidden
+The Info formatting commands automatically end the reference with a
+closing colon or address@hidden
address@hidden enumerate
+
+Because one type of formatting automatically inserts closing
+punctuation and the other does not, you should use @code{@@pxref}
address@hidden inside parentheses as part of another sentence. Also, you
+yourself should not insert punctuation after the reference, as you do
+with @code{@@address@hidden
+
address@hidden@@pxref} is designed so that the output looks right and works
+right between parentheses both in printed output and in an Info file.
+In a printed manual, a closing comma or period should not follow a
+cross reference within parentheses; such punctuation is wrong. But in
+an Info file, suitable closing punctuation must follow the cross
+reference so Info can recognize its end. @code{@@pxref} spares you
+the need to use complicated methods to put a terminator into one form
+of the output and not the address@hidden
+
address@hidden
+With one argument, a parenthetical cross reference looks like
+this:@refill
+
address@hidden Flooding
address@hidden
address@hidden storms cause flooding (@@address@hidden@}) @dots{}
address@hidden example
+
address@hidden 800
address@hidden
+which produces
+
address@hidden
address@hidden
address@hidden storms cause flooding (*Note Hurricanes::) @dots{}
address@hidden group
address@hidden example
+
address@hidden
+and
+
address@hidden
address@hidden storms cause flooding (see Section 6.7 [Hurricanes], page 72)
@dots{}
address@hidden quotation
+
+With two arguments, a parenthetical cross reference has this
+template:@refill
+
address@hidden
address@hidden (@@address@hidden@var{node-name}, @address@hidden) @dots{}
address@hidden example
+
address@hidden
+which produces
+
address@hidden
address@hidden (*Note @var{cross-reference-name}: @var{node-name}.) @dots{}
address@hidden example
+
address@hidden
+and
+
address@hidden 1500
address@hidden
address@hidden (see Section @var{nnn} address@hidden, page @var{ppp}) @dots{}
address@hidden quotation
+
address@hidden@@pxref} can be used with up to five arguments just like
address@hidden@@xref} (@pxref{xref, , @code{@@xref}})address@hidden
+
address@hidden
address@hidden note:} Use @code{@@pxref} only as a parenthetical
+reference. Do not try to use @code{@@pxref} as a clause in a sentence.
+It will look bad in either the Info file, the printed output, or
address@hidden
+
+Also, parenthetical cross references look best at the ends of sentences.
+Although you may write them in the middle of a sentence, that location
+breaks up the flow of address@hidden
address@hidden quotation
+
address@hidden inforef, uref, pxref, Cross References
address@hidden @code{@@inforef}
address@hidden Cross references using @code{@@inforef}
address@hidden References using @code{@@inforef}
address@hidden inforef
+
address@hidden@@inforef} is used for cross references to Info files for which
+there are no printed manuals. Even in a printed manual,
address@hidden@@inforef} generates a reference directing the user to look in
+an Info address@hidden
+
+The command takes either two or three arguments, in the following
+order:@refill
+
address@hidden
address@hidden
+The node name.
+
address@hidden
+The cross reference name (optional).
+
address@hidden
+The Info file name.
address@hidden enumerate
+
address@hidden
+Separate the arguments with commas, as with @code{@@xref}. Also, you
+must terminate the reference with a comma or period after the
address@hidden@}}, as you do with @code{@@address@hidden
+
address@hidden
+The template is:
+
address@hidden
+@@address@hidden@var{node-name}, @var{cross-reference-name}, @address@hidden,
address@hidden example
+
address@hidden 800
address@hidden
+Thus,
+
address@hidden
address@hidden
+@@address@hidden, Advanced Info commands, address@hidden,
+for more information.
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+produces
+
address@hidden
address@hidden
+*Note Advanced Info commands: (info)Expert,
+for more information.
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+and
+
address@hidden
+See Info file @file{info}, node @samp{Expert}, for more information.
address@hidden quotation
+
address@hidden 800
address@hidden
+Similarly,
+
address@hidden
address@hidden
+@@address@hidden, , address@hidden, for more information.
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+produces
+
address@hidden
+*Note (info)Expert::, for more information.
address@hidden example
+
address@hidden 800
address@hidden
+and
+
address@hidden
+See Info file @file{info}, node @samp{Expert}, for more information.
address@hidden quotation
+
+The converse of @code{@@inforef} is @code{@@cite}, which is used to
+refer to printed works for which no Info form exists. @xref{cite, ,
address@hidden@@address@hidden
+
+
address@hidden uref
address@hidden @code{@@address@hidden@var{url}[, @var{text}][, @address@hidden
address@hidden uref
address@hidden Uniform resource locator, referring to
address@hidden URL, referring to
+
address@hidden @code{href}, producing HTML
address@hidden@@uref} produces a reference to a uniform resource locator (url).
+It takes one mandatory argument, the url, and two optional arguments
+which control the text that is displayed. In HTML output, @code{@@uref}
+produces a link you can follow.
+
+The second argument, if specified, is the text to display (the default
+is the url itself); in Info and DVI output, but not in HTML output, the
+url is also output.
+
address@hidden Man page, reference to
+The third argument, on the other hand, if specified is also the text to
+display, but the url is @emph{not} output in any format. This is useful
+when the text is already sufficiently referential, as in a man page. If
+the third argument is given, the second argument is ignored.
+
+The simple one argument form, where the url is both the target and the
+text of the link:
+
address@hidden
+The official GNU ftp site is @@address@hidden://ftp.gnu.org/address@hidden
address@hidden example
+
address@hidden produces:
address@hidden
+The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}.
address@hidden display
+
+
+An example of the two-argument form:
address@hidden
+The official @@address@hidden://ftp.gnu.org/gnu, GNU ftp address@hidden
+holds programs and texts.
address@hidden example
+
address@hidden produces:
address@hidden
+The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site}
+holds programs and texts.
address@hidden display
+
address@hidden that is, the Info output is this:
address@hidden
+The official GNU ftp site (ftp://ftp.gnu.org/gnu)
+holds programs and texts.
address@hidden example
+
address@hidden and the HTML output is this:
address@hidden
+The official <a href="ftp://ftp.gnu.org/gnu";>GNU ftp site</a>
+holds programs and texts.
address@hidden example
+
+
+An example of the three-argument form:
address@hidden
+The @@address@hidden/man.cgi/1/ls,,ls(1)@} program @dots{}
address@hidden example
+
address@hidden produces:
address@hidden
+The @uref{/man.cgi/1/ls,,ls(1)} program @dots{}
address@hidden display
+
address@hidden but with HTML:
address@hidden
+The <a href="/man.cgi/1/ls">ls(1)</a> program @dots{}
address@hidden example
+
+To merely indicate a url without creating a link people can follow, use
address@hidden@@url} (@pxref{url, @code{@@url}}).
+
+Some people prefer to display url's in the unambiguous format:
+
address@hidden
+<URL:http://@var{host}/@var{path}>
address@hidden display
+
address@hidden
address@hidden <URL convention, not used
+You can use this form in the input file if you wish. We feel it's not
+necessary to clutter up the output with the extra @samp{<URL:} and
address@hidden>}, since any software that tries to detect url's in text already
+has to detect them without the @samp{<URL:} to be useful.
+
+
address@hidden Marking Text
address@hidden Marking Words and Phrases
address@hidden Paragraph, marking text within
address@hidden Marking words and phrases
address@hidden Words and phrases, marking them
address@hidden Marking text within a paragraph
address@hidden Text, marking up
+
+In Texinfo, you can mark words and phrases in a variety of ways.
+The Texinfo formatters use this information to determine how to
+highlight the text.
+You can specify, for example, whether a word or phrase is a
+defining occurrence, a metasyntactic variable, or a symbol used in a
+program. Also, you can emphasize text, in several different ways.
+
address@hidden
+* Indicating:: How to indicate definitions, files, etc.
+* Emphasis:: How to emphasize text.
address@hidden menu
+
+
address@hidden Indicating, Emphasis, Marking Text, Marking Text
address@hidden Indicating Definitions, Commands, etc.
address@hidden Highlighting text
address@hidden Indicating commands, definitions, etc.
+
+Texinfo has commands for indicating just what kind of object a piece of
+text refers to. For example, metasyntactic variables are marked by
address@hidden@@var}, and code by @code{@@code}. Since the pieces of text are
+labelled by commands that tell what kind of object they are, it is easy
+to change the way the Texinfo formatters prepare such text. (Texinfo is
+an @emph{intentional} formatting language rather than a @emph{typesetting}
+formatting language.)@refill
+
+For example, in a printed manual,
+code is usually illustrated in a typewriter font;
address@hidden@@code} tells @TeX{} to typeset this text in this font. But it
+would be easy to change the way @TeX{} highlights code to use another
+font, and this change would not affect how keystroke examples are
+highlighted. If straight typesetting commands were used in the body
+of the file and you wanted to make a change, you would need to check
+every single occurrence to make sure that you were changing code and
+not something else that should not be address@hidden
+
address@hidden
+* Useful Highlighting:: Highlighting provides useful information.
+* code:: Indicating program code.
+* kbd:: Showing keyboard input.
+* key:: Specifying keys.
+* samp:: A literal sequence of characters.
+* verb:: A verbatim sequence of characters.
+* var:: Indicating metasyntactic variables.
+* env:: Indicating environment variables.
+* file:: Indicating file names.
+* command:: Indicating command names.
+* option:: Indicating option names.
+* dfn:: Specifying definitions.
+* cite:: Referring to books not in the Info system.
+* acronym:: Indicating acronyms.
+* url:: Indicating a World Wide Web reference.
+* email:: Indicating an electronic mail address.
address@hidden menu
+
+
address@hidden Useful Highlighting, code, Indicating, Indicating
address@hidden Highlighting Commands are Useful
+
+The highlighting commands can be used to extract useful information
+from the file, such as lists of functions or file names. It is
+possible, for example, to write a program in Emacs Lisp (or a keyboard
+macro) to insert an index entry after every paragraph that contains
+words or phrases marked by a specified command. You could do this to
+construct an index of functions if you had not already made the
address@hidden
+
+The commands serve a variety of purposes:@refill
+
address@hidden @code
address@hidden @@address@hidden@address@hidden
+Indicate text that is a literal example of a piece of a address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate keyboard address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate the conventional name for a key on a address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate text that is a literal example of a sequence of address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate a metasyntactic address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate an environment address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate the name of a address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate the name of a address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate a command-line address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate the introductory or defining use of a address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate the name of a address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate an address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate a uniform resource locator for the World Wide Web.
+
address@hidden @@address@hidden@var{email-address}[, @address@hidden
+Indicate an electronic mail address.
+
address@hidden table
+
+
address@hidden code
address@hidden @code{@@address@hidden@address@hidden
address@hidden code
+
address@hidden Syntactic tokens, indicating
+Use the @code{@@code} command to indicate text that is a piece of a
+program and which consists of entire syntactic tokens. Enclose the
+text in braces.
+
address@hidden Expressions in a program, indicating
address@hidden Keywords, indicating
address@hidden Reserved words, indicating
+Thus, you should use @code{@@code} for an expression in a program, for
+the name of a variable or function used in a program, or for a
+keyword in a programming language.
+
+Use @code{@@code} for command names in languages that resemble
+programming languages, such as Texinfo. For example, @code{@@code} and
address@hidden@@samp} are produced by writing
@samp{@@address@hidden@@@@address@hidden and
address@hidden@@address@hidden@@@@address@hidden in the Texinfo source,
respectively.
+
address@hidden Case, not altering in @code{@@code}
+It is incorrect to alter the case of a word inside an @code{@@code}
+command when it appears at the beginning of a sentence. Most computer
+languages are case sensitive. In C, for example, @code{Printf} is
+different from the identifier @code{printf}, and most likely is a
+misspelling of it. Even in languages which are not case sensitive, it
+is confusing to a human reader to see identifiers spelled in different
+ways. Pick one spelling and always use that. If you do not want to
+start a sentence with a command name written all in lower case, you
+should rearrange the sentence.
+
+In the printed manual, @code{@@code} causes @TeX{} to typeset the
+argument in a typewriter face. In the Info file, it causes the Info
+formatting commands to use single quotation marks around the text.
+
address@hidden 700
+For example,
+
address@hidden
+The function returns @@address@hidden@}.
address@hidden example
+
address@hidden
+produces this in the printed manual:
+
address@hidden
+The function returns @code{nil}.
address@hidden quotation
+
+
+Here are some cases for which it is preferable not to use @code{@@code}:
+
address@hidden @bullet
address@hidden
+For shell command names such as @command{ls} (use @code{@@command}).
+
address@hidden
+For shell options such as @samp{-c} when such options stand alone (use
address@hidden@@option}).
+
address@hidden
+Also, an entire shell command often looks better if written using
address@hidden@@samp} rather than @code{@@code}. In this case, the rule is to
+choose the more pleasing format.
+
address@hidden
+For environment variable such as @env{TEXINPUTS} (use @code{@@env}).
+
address@hidden
+For a string of characters shorter than a syntactic token. For example,
+if you are writing about @samp{goto-ch}, which is just a part of the
+name for the @code{goto-char} Emacs Lisp function, you should use
address@hidden@@samp}.
+
address@hidden
+In general, when writing about the characters used in a token; for
+example, do not use @code{@@code} when you are explaining what letters
+or printable symbols can be used in the names of functions. (Use
address@hidden@@samp}.) Also, you should not use @code{@@code} to mark text
+that is considered input to programs unless the input is written in a
+language that is like a programming language. For example, you should
+not use @code{@@code} for the keystroke commands of GNU Emacs (use
address@hidden@@kbd} instead) although you may use @code{@@code} for the names
+of the Emacs Lisp functions that the keystroke commands invoke.
+
address@hidden itemize
+
+Since @code{@@command}, @code{@@option}, and @code{@@env} were
+introduced relatively recently, it is acceptable to use @code{@@code} or
address@hidden@@samp} for command names, options, and environment variables.
+The new commands allow you to express the markup more precisely, but
+there is no real harm in using the older commands, and of course the
+long-standing manuals do so.
+
+
address@hidden kbd
address@hidden @code{@@address@hidden@address@hidden
address@hidden kbd
address@hidden Keyboard input
+
+Use the @code{@@kbd} command for characters of input to be typed by
+users. For example, to refer to the characters @kbd{M-a},
address@hidden
+
address@hidden
+@@address@hidden@}
address@hidden example
+
address@hidden
+and to refer to the characters @kbd{M-x shell}, address@hidden
+
address@hidden
+@@address@hidden address@hidden
address@hidden example
+
address@hidden user input
address@hidden slanted typewriter font, for @code{@@kbd}
+The @code{@@kbd} command has the same effect as @code{@@code} in Info,
+but by default produces a different font (slanted typewriter instead of
+normal typewriter) in the printed manual, so users can distinguish the
+characters they are supposed to type from those the computer outputs.
+
address@hidden kbdinputstyle
+Since the usage of @code{@@kbd} varies from manual to manual, you can
+control the font switching with the @code{@@kbdinputstyle} command.
+This command has no effect on Info output. Write this command at the
+beginning of a line with a single word as an argument, one of the
+following:
address@hidden address@hidden, arg to @@kbdinputstyle}
address@hidden address@hidden, arg to @@kbdinputstyle}
address@hidden address@hidden, arg to @@kbdinputstyle}
address@hidden @samp
address@hidden code
+Always use the same font for @code{@@kbd} as @code{@@code}.
address@hidden example
+Use the distinguishing font for @code{@@kbd} only in @code{@@example}
+and similar environments.
address@hidden distinct
+(the default) Always use the distinguishing font for @code{@@kbd}.
address@hidden table
+
+You can embed another @@-command inside the braces of an @code{@@kbd}
+command. Here, for example, is the way to describe a command that
+would be described more verbosely as ``press an @samp{r} and then
+press the @key{RET} key'':@refill
+
address@hidden
+@@address@hidden @@address@hidden@address@hidden
address@hidden example
+
address@hidden
+This produces: @kbd{r @key{RET}}
+
+You also use the @code{@@kbd} command if you are spelling out the letters
+you type; for example:@refill
+
address@hidden
+To give the @@address@hidden@} command,
+type the characters @@address@hidden o g o u t @@address@hidden@address@hidden
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
+To give the @code{logout} command,
+type the characters @kbd{l o g o u t @key{RET}}.
address@hidden quotation
+
+(Also, this example shows that you can add spaces for clarity. If you
+really want to mention a space character as one of the characters of
+input, write @kbd{@@address@hidden@}} for it.)@refill
+
+
address@hidden key, samp, kbd, Indicating
address@hidden node-name, next, previous, up
address@hidden @code{@@address@hidden@address@hidden
address@hidden key
+
+Use the @code{@@key} command for the conventional name for a key on a
+keyboard, as in:@refill
+
address@hidden
+@@address@hidden@}
address@hidden example
+
+You can use the @code{@@key} command within the argument of an
address@hidden@@kbd} command when the sequence of characters to be typed
+includes one or more keys that are described by address@hidden
+
address@hidden 700
+For example, to produce @kbd{C-x @key{ESC}} you would type:@refill
+
address@hidden
+@@address@hidden @@address@hidden@address@hidden
address@hidden example
+
+Here is a list of the recommended names for keys:
address@hidden Recommended names for keys
address@hidden Keys, recommended names
address@hidden Names recommended for keys
address@hidden Abbreviations for keys
+
address@hidden
address@hidden @t
address@hidden SPC
+Space
address@hidden RET
+Return
address@hidden LFD
+Linefeed (however, since most keyboards nowadays do not have a Linefeed key,
+it might be better to call this character @kbd{C-j}.
address@hidden TAB
+Tab
address@hidden BS
+Backspace
address@hidden ESC
+Escape
address@hidden DEL
+Delete
address@hidden SHIFT
+Shift
address@hidden CTRL
+Control
address@hidden META
+Meta
address@hidden table
address@hidden quotation
+
address@hidden META key
+There are subtleties to handling words like `meta' or `ctrl' that are
+names of modifier keys. When mentioning a character in which the
+modifier key is used, such as @kbd{Meta-a}, use the @code{@@kbd} command
+alone; do not use the @code{@@key} command; but when you are referring
+to the modifier key in isolation, use the @code{@@key} command. For
+example, write @samp{@@address@hidden@}} to produce @kbd{Meta-a} and
address@hidden@@address@hidden@}} to produce @key{META}.
+
address@hidden I don't think this is a good explanation.
address@hidden I think it will puzzle readers more than it clarifies matters.
-- rms.
address@hidden In other words, use @code{@@kbd} for what you do, and use
@code{@@key}
address@hidden for what you talk about: ``Press @code{@@address@hidden@}} to
move point to
address@hidden the beginning of the sentence. The @code{@@address@hidden@}}
key is often in
address@hidden the lower left of the keyboard.''@refill
+
address@hidden samp
address@hidden @code{@@address@hidden@address@hidden
address@hidden samp
+
+Use the @code{@@samp} command to indicate text that is a literal example
+or `sample' of a sequence of characters in a file, string, pattern, etc.
+Enclose the text in braces. The argument appears within single
+quotation marks in both the Info file and the printed manual; in
+addition, it is printed in a fixed-width address@hidden
+
address@hidden
+To match @@address@hidden@} at the end of the line,
+use the regexp @@address@hidden@}.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+To match @samp{foo} at the end of the line, use the regexp
address@hidden@refill
address@hidden quotation
+
+Any time you are referring to single characters, you should use
address@hidden@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate.
+Also, you may use @code{@@samp} for entire statements in C and for entire
+shell commands---in this case, @code{@@samp} often looks better than
address@hidden@@code}. Basically, @code{@@samp} is a catchall for whatever is
+not covered by @code{@@code}, @code{@@kbd}, or @code{@@address@hidden
+
+Only include punctuation marks within braces if they are part of the
+string you are specifying. Write punctuation marks outside the braces
+if those punctuation marks are part of the English text that surrounds
+the string. In the following sentence, for example, the commas and
+period are outside of the braces:@refill
+
address@hidden
address@hidden
+In English, the vowels are @@address@hidden@}, @@address@hidden@},
+@@address@hidden@}, @@address@hidden@}, @@address@hidden@}, and sometimes
+@@address@hidden@}.
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
+In English, the vowels are @samp{a}, @samp{e},
address@hidden, @samp{o}, @samp{u}, and sometimes
address@hidden
address@hidden quotation
+
+
address@hidden verb
address@hidden @code{@@address@hidden<char>@var{text}<char>@}
address@hidden verb
address@hidden Verbatim in-line text
+
address@hidden Delimiter character, for verbatim
+Use the @code{@@verb} command to print a verbatim sequence of
+characters.
+
+Like address@hidden's @code{\verb} command, the verbatim text can be quoted
using
+any unique delimiter character. Enclose the verbatim text, including the
+delimiters, in braces. Text is printed in a fixed-width font:
+
address@hidden
+How many @@address@hidden|@@|@}-escapes does one need to print this
+@@address@hidden@@a @@b @@address@hidden string or
@@address@hidden@@'address@hidden@address@hidden@address@hidden this?
address@hidden example
+
address@hidden
+produces
+
address@hidden
+How many @verb{|@ |}-escapes does one need to print this
address@hidden@a @b @c.} string or these @verb{+@'e?`{}!`\+} this?
address@hidden example
+
+This is in contrast to @code{@@samp} (see the previous
+section), whose argument is normal Texinfo text, where the characters
address@hidden@@@address@hidden are special; with @code{@@verb}, nothing is
special except
+the delimiter character you choose.
+
+
address@hidden var
address@hidden @code{@@address@hidden@address@hidden
address@hidden var
+
+Use the @code{@@var} command to indicate metasyntactic variables. A
address@hidden variable} is something that stands for another piece of
+text. For example, you should use a metasyntactic variable in the
+documentation of a function to describe the arguments that are passed
+to that address@hidden
+
+Do not use @code{@@var} for the names of particular variables in
+programming languages. These are specific names from a program, so
address@hidden@@code} is correct for them (@pxref{code}). For example, the
+Emacs Lisp variable @code{texinfo-tex-command} is not a metasyntactic
+variable; it is properly formatted using @code{@@code}.
+
+Do not use @code{@@var} for environment variables either; @code{@@env}
+is correct for them (see the next section).
+
+The effect of @code{@@var} in the Info file is to change the case of the
+argument to all upper case. In the printed manual and HTML output, the
+argument is printed in slanted type.
+
address@hidden 700
+For example,
+
address@hidden
+To delete file @@address@hidden@},
+type @@address@hidden @@address@hidden@address@hidden
address@hidden example
+
address@hidden
+produces
+
address@hidden
+To delete file @var{filename}, type @samp{rm @var{filename}}.
address@hidden quotation
+
address@hidden
+(Note that @code{@@var} may appear inside @code{@@code},
address@hidden@@samp}, @code{@@file}, etc.)@refill
+
+Write a metasyntactic variable all in lower case without spaces, and
+use hyphens to make it more readable. Thus, the Texinfo source for
+the illustration of how to begin a Texinfo manual looks like
+this:@refill
+
address@hidden
address@hidden
+\input texinfo
+@@@@setfilename @@address@hidden@}
+@@@@settitle @@address@hidden@}
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
address@hidden
+\input texinfo
+@@setfilename @var{info-file-name}
+@@settitle @var{name-of-manual}
address@hidden group
address@hidden example
+
+In some documentation styles, metasyntactic variables are shown with
+angle brackets, for example:@refill
+
address@hidden
address@hidden, type rm <filename>
address@hidden example
+
address@hidden
+However, that is not the style that Texinfo uses. (You can, of
+course, modify the sources to @file{texinfo.tex} and the Info formatting
commands
+to output the @code{<@dots{}>} format if you wish.)@refill
+
+
address@hidden env
address@hidden @code{@@address@hidden@address@hidden
address@hidden env
+
+Use the @code{@@env} command to indicate environment variables, as used
+by many operating systems, including GNU. Do not use it for
+metasyntactic variables; use @code{@@var} instead (see the previous
+section).
+
address@hidden@@env} is equivalent to @code{@@code} in its effects.
+For example:
+
address@hidden
+The @@address@hidden@} environment variable @dots{}
address@hidden example
address@hidden produces
address@hidden
+The @env{PATH} environment variable @dots{}
address@hidden quotation
+
+
address@hidden file
address@hidden @code{@@address@hidden@address@hidden
address@hidden file
+
+Use the @code{@@file} command to indicate text that is the name of a
+file, buffer, or directory, or is the name of a node in Info. You can
+also use the command for file name suffixes. Do not use @code{@@file}
+for symbols in a programming language; use @code{@@code}.
+
+Currently, @code{@@file} is equivalent to @code{@@samp} in its effects.
+For example,@refill
+
address@hidden
+The @@address@hidden@} files are in
+the @@address@hidden/usr/local/emacs/address@hidden directory.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+The @file{.el} files are in
+the @file{/usr/local/emacs/lisp} directory.
address@hidden quotation
+
+
address@hidden command
address@hidden @code{@@address@hidden@address@hidden
address@hidden command
address@hidden Command names, indicating
address@hidden Program names, indicating
+
+Use the @code{@@command} command to indicate command names, such as
address@hidden or @command{cc}.
+
address@hidden@@command} is equivalent to @code{@@code} in its effects.
+For example:
+
address@hidden
+The command @@address@hidden@} lists directory contents.
address@hidden example
address@hidden produces
address@hidden
+The command @command{ls} lists directory contents.
address@hidden quotation
+
+You should write the name of a program in the ordinary text font, rather
+than using @code{@@command}, if you regard it as a new English word,
+such as `Emacs' or `Bison'.
+
+When writing an entire shell command invocation, as in @samp{ls -l},
+you should use either @code{@@samp} or @code{@@code} at your discretion.
+
+
address@hidden option
address@hidden @code{@@address@hidden@address@hidden
address@hidden option
+
+Use the @code{@@option} command to indicate a command-line option; for
+example, @option{-l} or @option{--version} or
address@hidden@var{filename}}.
+
address@hidden@@option} is equivalent to @code{@@samp} in its effects.
+For example:
+
address@hidden
+The option @@address@hidden@} produces a long listing.
address@hidden example
address@hidden produces
address@hidden
+The option @option{-l} produces a long listing.
address@hidden quotation
+
+In tables, putting options inside @code{@@code} produces a
+more pleasing effect.
+
address@hidden dfn
address@hidden node-name, next, previous, up
address@hidden @code{@@address@hidden@address@hidden
address@hidden dfn
+
+Use the @code{@@dfn} command to identify the introductory or defining
+use of a technical term. Use the command only in passages whose
+purpose is to introduce a term which will be used again or which the
+reader ought to know. Mere passing mention of a term for the first
+time does not deserve @code{@@dfn}. The command generates italics in
+the printed manual, and double quotation marks in the Info file. For
+example:@refill
+
address@hidden
+Getting rid of a file is called @@address@hidden@} it.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+Getting rid of a file is called @dfn{deleting} it.
address@hidden quotation
+
+As a general rule, a sentence containing the defining occurrence of a
+term should be a definition of the term. The sentence does not need
+to say explicitly that it is a definition, but it should contain the
+information of a definition---it should make the meaning clear.
+
address@hidden cite
address@hidden @code{@@address@hidden@address@hidden
address@hidden cite
+
+Use the @code{@@cite} command for the name of a book that lacks a
+companion Info file. The command produces italics in the printed
+manual, and quotation marks in the Info file.
+
+If a book is written in Texinfo, it is better to use a cross reference
+command since a reader can easily follow such a reference in Info.
address@hidden, , @code{@@xref}}.
+
+
+
+
address@hidden acronym
address@hidden @code{@@address@hidden@address@hidden
address@hidden acronym
+
address@hidden NASA, as acronym
address@hidden F.B.I., as acronym
address@hidden Abbreviations, tagging
address@hidden Acronyms, tagging
+Use the @code{@@acronym} command for abbreviations written in all
+capital letters, such as address@hidden'. The abbreviation is given as
+the single argument in braces, as in @samp{@@address@hidden@}}. As
+a matter of style, or for particular abbreviations, you may prefer to
+use periods, as in @samp{@@address@hidden@}}.
+
+In @TeX{} and HTML, the argument is printed in a slightly smaller font
+size. In Info or plain text output, this command changes nothing.
+
+
address@hidden url
address@hidden @code{@@address@hidden@address@hidden
address@hidden url
address@hidden Uniform resource locator, indicating
address@hidden URL, indicating
+
+Use the @code{@@url} command to indicate a uniform resource locator on
+the World Wide Web. This is analogous to @code{@@file}, @code{@@var},
+etc., and is purely for markup purposes. It does not produce a link you
+can follow in HTML output (use the @code{@@uref} command for that,
address@hidden,, @code{@@uref}}). It is useful for url's which do
+not actually exist. For example:
+
address@hidden Two lines because one is too long for smallbook format.
address@hidden
+For example, the url might be @@address@hidden://example.org/address@hidden
address@hidden example
+
address@hidden which produces:
+
address@hidden
+For example, the url might be @url{http://example.org/path}.
address@hidden display
+
+
address@hidden email
address@hidden @code{@@address@hidden@var{email-address}[, @address@hidden
address@hidden email
+
+Use the @code{@@email} command to indicate an electronic mail address.
+It takes one mandatory argument, the address, and one optional argument, the
+text to display (the default is the address itself).
+
address@hidden mailto link
+In Info and @TeX{}, the address is shown in angle brackets, preceded by
+the text to display if any. In HTML output, @code{@@email} produces a
address@hidden link that usually brings up a mail composition window.
+For example:
+
address@hidden
+Send bug reports to @@address@hidden@@@@address@hidden,
+suggestions to the @@address@hidden@@@@gnu.org, same address@hidden
address@hidden example
address@hidden produces
address@hidden
+Send bug reports to @email{bug-texinfo@@gnu.org},
+suggestions to the @email{bug-texinfo@@gnu.org, same place}.
address@hidden display
+
+
address@hidden Emphasis
address@hidden node-name, next, previous, up
address@hidden Emphasizing Text
address@hidden Emphasizing text
+
+Usually, Texinfo changes the font to mark words in the text according to
+what category the words belong to; an example is the @code{@@code} command.
+Most often, this is the best way to mark words.
+However, sometimes you will want to emphasize text without indicating a
+category. Texinfo has two commands to do this. Also, Texinfo has
+several commands that specify the font in which @TeX{} will typeset
+text. These commands have no effect on Info and only one of them,
+the @code{@@r} command, has any regular address@hidden
+
address@hidden
+* emph & strong:: How to emphasize text in Texinfo.
+* Smallcaps:: How to use the small caps font.
+* Fonts:: Various font commands for printed output.
address@hidden menu
+
address@hidden emph & strong
address@hidden @code{@@address@hidden@address@hidden and
@code{@@address@hidden@address@hidden
address@hidden Emphasizing text, font for
address@hidden emph
address@hidden strong
+
+The @code{@@emph} and @code{@@strong} commands are for emphasis;
address@hidden@@strong} is stronger. In printed output, @code{@@emph} produces
address@hidden and @code{@@strong} produces @strong{bold}.
+
address@hidden 800
+For example,
+
address@hidden
address@hidden
+@@quotation
+@@address@hidden:@} @@address@hidden * address@hidden removes
@@address@hidden@}
+files in the directory.
+@@end quotation
address@hidden group
address@hidden example
+
address@hidden
+produces:
+
address@hidden
+ *Caution*: `rm * .[^.]*' removes _all_
+ files in the directory.
address@hidden example
+
+The @code{@@strong} command is seldom used except to mark what is, in
+effect, a typographical element, such as the word `Caution' in the
+preceding example.
+
+In the Info output, @code{@@emph} surrounds the text with underscores
+(@samp{_}), and @code{@@strong} puts asterisks around the text.
+
address@hidden
address@hidden:} Do not use @code{@@strong} with the word @samp{Note};
+Info will mistake the combination for a cross reference. Use a phrase
+such as @strong{Please note} or @strong{Caution} instead.
address@hidden quotation
+
+
address@hidden Smallcaps
address@hidden @code{@@address@hidden@address@hidden: The Small Caps Font
address@hidden Small caps font
address@hidden sc @r{(small caps font)}
+
+Use the @samp{@@sc} command to set text in the printed and the HTML
+output in @sc{a small caps font} and set text in the Info file in upper
+case letters. Write the text you want to be in small caps (where
+possible) between braces in lower case, like this:
+
address@hidden
+The @@address@hidden@} and @@address@hidden@} are technical societies.
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
+The @sc{acm} and @sc{ieee} are technical societies.
address@hidden display
+
address@hidden typesets the small caps font in a manner that prevents the
+letters from `jumping out at you on the page'. This makes small caps
+text easier to read than text in all upper case---but it's usually
+better to use regular mixed case anyway. The Info formatting commands
+set all small caps text in upper case. In HTML, the text is upper-cased
+and a smaller font is used to render it.
+
+If the text between the braces of an @code{@@sc} command is uppercase,
address@hidden typesets in FULL-SIZE CAPITALS. Use full-size capitals
+sparingly, if ever, and since it's redundant to mark all-uppercase text
+with @code{@@sc}, @command{makeinfo} warns about such usage.
+
+You may also use the small caps font for a jargon word such as
address@hidden (a @sc{nasa} word meaning `abort to orbit').
+
+There are subtleties to using the small caps font with a jargon word
+such as @sc{cdr}, a word used in Lisp programming. In this case, you
+should use the small caps font when the word refers to the second and
+subsequent elements of a list (the @sc{cdr} of the list), but you
+should use @samp{@@code} when the word refers to the Lisp function of
+the same spelling.
+
+
address@hidden Fonts
address@hidden Fonts for Printing, Not Info
address@hidden Fonts for printing, not for Info
address@hidden i @r{(italic font)}
address@hidden b @r{(bold font)}
address@hidden t @r{(typewriter font)}
address@hidden r @r{(Roman font)}
+
+Texinfo provides four font commands that specify font changes in the
+printed manual but have no effect in the Info file. @code{@@i}
+requests @i{italic} font (in some versions of @TeX{}, a slanted font
+is used), @code{@@b} requests @b{bold} face, @code{@@t} requests the
address@hidden, typewriter-style font used by @code{@@code}, and @code{@@r}
requests a
address@hidden font, which is the usual font in which text is printed. All
+four commands apply to an argument that follows, surrounded by
address@hidden
+
+Only the @code{@@r} command has much use: in example programs, you
+can use the @code{@@r} command to convert code comments from the
+fixed-width font to a roman font. This looks better in printed
address@hidden
+
address@hidden 700
+For example,
+
address@hidden
address@hidden
+@@lisp
+(+ 2 2) ; @@address@hidden two plus address@hidden
+@@end lisp
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
+(+ 2 2) ; @r{Add two plus two.}
address@hidden lisp
+
+If possible, you should avoid using the other three font commands. If
+you need to use one, it probably indicates a gap in the Texinfo
+language.
+
+
address@hidden Quotations and Examples
address@hidden Quotations and Examples
+
+Quotations and examples are blocks of text consisting of one or more
+whole paragraphs that are set off from the bulk of the text and
+treated differently. They are usually address@hidden
+
+In Texinfo, you always begin a quotation or example by writing an
+@@-command at the beginning of a line by itself, and end it by writing
+an @code{@@end} command that is also at the beginning of a line by
+itself. For instance, you begin an example by writing @code{@@example}
+by itself at the beginning of a line and end the example by writing
address@hidden@@end example} on a line by itself, at the beginning of that
+line.
address@hidden end
+
address@hidden
+* Block Enclosing Commands:: Different constructs for different purposes.
+* quotation:: Writing a quotation.
+* example:: Writing an example in a fixed-width font.
+* verbatim:: Writing a verbatim example.
+* verbatiminclude:: Including a file verbatim.
+* lisp:: Illustrating Lisp code.
+* small:: Forms for @code{@@smallbook}.
+* display:: Writing an example in the current font.
+* format:: Writing an example without narrowed margins.
+* exdent:: Undo indentation on a line.
+* flushleft & flushright:: Pushing text flush left or flush right.
+* noindent:: Preventing paragraph indentation.
+* cartouche:: Drawing rounded rectangles around examples.
address@hidden menu
+
+
address@hidden Block Enclosing Commands
address@hidden Block Enclosing Commands
+
+Here are commands for quotations and examples, explained further in the
+following sections:
+
address@hidden @code
address@hidden @@quotation
+Indicate text that is quoted. The text is filled, indented, and
+printed in a roman font by default.
+
address@hidden @@example
+Illustrate code, commands, and the like. The text is printed
+in a fixed-width font, and indented but not filled.
+
address@hidden @@verbatim
+Mark a piece of text that is to be printed verbatim; no character
+substitutions are made and all commands are ignored, until the next
address@hidden@@end verbatim}. The text is printed in a fixed-width font,
+and not indented or filled. Extra spaces and blank lines are
+significant, and tabs are expanded.
+
address@hidden @@smallexample
+Same as @code{@@example}, except that in @TeX{} this command typesets
+text in a smaller font.
+
address@hidden @@lisp
+Like @code{@@example}, but specifically for illustrating Lisp code. The
+text is printed in a fixed-width font, and indented but not filled.
+
address@hidden @@smalllisp
+Is to @code{@@lisp} as @code{@@smallexample} is to @code{@@example}.
+
address@hidden @@display
+Display illustrative text. The text is indented but not filled, and
+no font is selected (so, by default, the font is roman)address@hidden
+
address@hidden @@smalldisplay
+Is to @code{@@display} as @code{@@smallexample} is to @code{@@example}.
+
address@hidden @@format
+Like @code{@@display} (the text is not filled and no font is selected),
+but the text is not indented.
+
address@hidden @@smallformat
+Is to @code{@@format} as @code{@@smallexample} is to @code{@@example}.
address@hidden table
+
+The @code{@@exdent} command is used within the above constructs to
+undo the indentation of a line.
+
+The @code{@@flushleft} and @code{@@flushright} commands are used to line
+up the left or right margins of unfilled address@hidden
+
+The @code{@@noindent} command may be used after one of the above
+constructs to prevent the following text from being indented as a new
+paragraph.
+
+You can use the @code{@@cartouche} command within one of the above
+constructs to highlight the example or quotation by drawing a box with
+rounded corners around it. @xref{cartouche, , Drawing Cartouches Around
+Examples}.
+
+
address@hidden quotation
address@hidden @code{@@quotation}
address@hidden Quotations
address@hidden quotation
+
+The text of a quotation is processed normally except that:
+
address@hidden @bullet
address@hidden
+the margins are closer to the center of the page, so the whole of the
+quotation is indented;@refill
+
address@hidden
+the first lines of paragraphs are indented no more than other
+lines;@refill
+
address@hidden
+in the printed output, interparagraph spacing is address@hidden
address@hidden itemize
+
address@hidden
+This is an example of text written between an @code{@@quotation}
+command and an @code{@@end quotation} command. An @code{@@quotation}
+command is most often used to indicate text that is excerpted from
+another (real or hypothetical) printed address@hidden
address@hidden quotation
+
+Write an @code{@@quotation} command as text on a line by itself. This
+line will disappear from the output. Mark the end of the quotation
+with a line beginning with and containing only @code{@@end quotation}.
+The @code{@@end quotation} line will likewise disappear from the
+output. Thus, the following,@refill
+
address@hidden
+@@quotation
+This is
+a foo.
+@@end quotation
address@hidden example
+
address@hidden
+produces
+
address@hidden
+This is a foo.
address@hidden quotation
+
+
address@hidden example
address@hidden @code{@@example}: Example Text
address@hidden Examples, formatting them
address@hidden Formatting examples
address@hidden example
+
+The @code{@@example} command is used to indicate an example that is
+not part of the running text, such as computer input or output.
+
address@hidden
address@hidden
+This is an example of text written between an
address@hidden@@example} command
+and an @code{@@end example} command.
+The text is indented but not filled.
address@hidden group
+
address@hidden
+In the printed manual, the text is typeset in a
+fixed-width font, and extra spaces and blank lines are
+significant. In the Info file, an analogous result is
+obtained by indenting each line with five spaces.
address@hidden group
address@hidden example
+
+Write an @code{@@example} command at the beginning of a line by itself.
+Mark the end of the example
+with an @code{@@end example} command, also written at the beginning of a
+line by address@hidden
+
address@hidden 700
+For example,
+
address@hidden
+@@example
+mv foo bar
+@@end example
address@hidden example
+
address@hidden
+produces
+
address@hidden
+mv foo bar
address@hidden example
+
+The lines containing @code{@@example} and @code{@@end example}
+will disappear from the output.
+To make the output look good,
+you should put a blank line before the
address@hidden@@example} and another blank line after the @code{@@end example}.
+Note that blank lines inside the beginning
address@hidden@@example} and the ending @code{@@end example} will appear in
+the address@hidden
+
address@hidden
address@hidden:} Do not use tabs in the lines of an example or anywhere
+else in Texinfo (except in verbatim environments)! The @TeX{}
+implementation of Texinfo treats tabs as single spaces, and that is not
+what they look like. (If necessary, in Emacs, you can use @kbd{M-x
+untabify} to convert tabs in a region to multiple spaces.)@refill
address@hidden quotation
+
+Examples are often, logically speaking, ``in the middle'' of a
+paragraph, and the text that continues after an example should not be
+indented. The @code{@@noindent} command prevents a piece of text from
+being indented as if it were a new paragraph.
+(@xref{noindent}.)
+
+(The @code{@@code} command is used for examples of code that are
+embedded within sentences, not set off from preceding and following
+text. @xref{code, , @code{@@code}}.)
+
+
address@hidden verbatim
address@hidden @code{@@verbatim}: Literal Text
address@hidden verbatim
address@hidden Verbatim environment
+
+Use the @code{@@verbatim} environment for printing of text that may
+contain special characters or commands that should not be interpreted,
+such as computer input or output (@code{@@example} interprets its text
+as regular Texinfo commands). This is especially useful for including
+automatically generated output in a Texinfo manual. Here is an example;
+the output you see is just the same as the input, with a line
address@hidden@@verbatim} before and a line @code{@@end verbatim} after.
+
address@hidden
+This is an example of text written in a @verbatim
+block. No character substitutions are made. All commands
+are ignored, until `<at>end verbatim'.
+
+In the printed manual, the text is typeset in a
+fixed-width font, and not indented or filled. All
+spaces and blank lines are significant, including tabs.
address@hidden verbatim
+
+Write a @code{@@verbatim} command at the beginning of a line by itself.
+This line will disappear from the output. Mark the end of the verbatim
+block with a @code{@@end verbatim} command, also written at the
+beginning of a line by itself. The @code{@@end verbatim} will also
+disappear from the output.
+
+For example:
address@hidden oops, got to trick this a bit: can't use @end verbatim inside
@verbatim
+
address@hidden
address@hidden @@verbatim
address@hidden @{
address@hidden <tab>@@command with strange characters: @@'e
address@hidden expand<tab>me
address@hidden @}
address@hidden @@end verbatim
address@hidden example
+
address@hidden
+produces
+
address@hidden
+{
+ @command with strange characters: @'e
+expand me
+}
address@hidden verbatim
+
+Since the lines containing @code{@@verbatim} and @code{@@end verbatim}
+produce no output, tyically you should put a blank line before the
address@hidden@@verbatim} and another blank line after the @code{@@end
+verbatim}. Blank lines between the beginning @code{@@verbatim} and the
+ending @code{@@end verbatim} will appear in the output.
+
+
address@hidden verbatiminclude
address@hidden @code{@@verbatiminclude} @var{file}: Include a File Verbatim
address@hidden Verbatim, include file
address@hidden Including a file verbatim
address@hidden verbatiminclude
+
+You can include the exact contents of a file in the document with the
address@hidden@@verbatiminclude} command:
+
address@hidden
+@@verbatiminclude @var{filename}
address@hidden example
+
+The contents of @var{filename} is printed in a verbatim environment
+(@pxref{verbatim,,@code{@@verbatim}}). Generally, the file is printed
+exactly as it is, with all special characters and white space retained.
+
+
address@hidden lisp
address@hidden @code{@@lisp}: Marking a Lisp Example
address@hidden lisp
address@hidden Lisp example
+
+The @code{@@lisp} command is used for Lisp code. It is synonymous
+with the @code{@@example} command.
+
address@hidden
+This is an example of text written between an
address@hidden@@lisp} command and an @code{@@end lisp} command.
address@hidden lisp
+
+Use @code{@@lisp} instead of @code{@@example} to preserve information
+regarding the nature of the example. This is useful, for example, if
+you write a function that evaluates only and all the Lisp code in a
+Texinfo file. Then you can use the Texinfo file as a Lisp
address@hidden would be straightforward to extend Texinfo to work
+in a similar fashion for C, Fortran, or other languages.}
+
+Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by
address@hidden
+
+
address@hidden small
address@hidden @code{@@address@hidden Block Commands
address@hidden Small examples
address@hidden Examples in smaller fonts
address@hidden Lisp examples in smaller fonts
address@hidden smalldisplay
address@hidden smallexample
address@hidden smallformat
address@hidden smalllisp
+
+In addition to the regular @code{@@example} and @code{@@lisp} commands,
+Texinfo has ``small'' example-style commands. These are
address@hidden@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, and
address@hidden@@smalllisp}.
+
+In @TeX{}, the @code{@@address@hidden commands typeset text in a smaller
+font than the non-small example commands. Consequently, many examples
+containing long lines fit on a page without needing to be shortened.
+
+In Info, the @code{@@address@hidden commands are equivalent to their
+non-small companion commands.
+
+Mark the end of an @code{@@address@hidden block with a corresponding
address@hidden@@end address@hidden For example, pair @code{@@smallexample} with
address@hidden@@end smallexample}.
+
address@hidden
+This is an example of text written between @code{@@smallexample} and
address@hidden@@end smallexample}. In Info this text appears in its normal
size;
+but in a 7 by 9.25 inch manual, this text appears in a smaller font.
address@hidden smallexample
+
+The @code{@@address@hidden commands make it easier to prepare manuals
+without forcing you to edit examples by hand to fit them onto narrower
+pages.
+
+As a general rule, a printed document looks better if you use only one
+of (for example) @code{@@example} or in @code{@@smallexample}
+consistently within a chapter. Only occasionally should you mix the two
+formats.
+
address@hidden, , Printing ``Small'' Books}, for more information
+about the @code{@@smallbook} command.
+
+
address@hidden display
address@hidden @code{@@display} and @code{@@smalldisplay}
address@hidden Display formatting
address@hidden display
+
+The @code{@@display} command begins a kind of example. It is like the
address@hidden@@example} command
+except that, in
+a printed manual, @code{@@display} does not select the fixed-width
+font. In fact, it does not specify the font at all, so that the text
+appears in the same font it would have appeared in without the
address@hidden@@display} address@hidden
+
address@hidden
+This is an example of text written between an @code{@@display} command
+and an @code{@@end display} command. The @code{@@display} command
+indents the text, but does not fill it.
address@hidden display
+
address@hidden smalldisplay
+Texinfo also provides a command @code{@@smalldisplay}, which is like
address@hidden@@display} but uses a smaller font in @code{@@smallbook} format.
address@hidden
+
+
address@hidden format
address@hidden @code{@@format} and @code{@@smallformat}
address@hidden format
+
+The @code{@@format} command is similar to @code{@@example} except
+that, in the printed manual, @code{@@format} does not select the
+fixed-width font and does not narrow the address@hidden
+
address@hidden
+This is an example of text written between an @code{@@format} command
+and an @code{@@end format} command. As you can see
+from this example,
+the @code{@@format} command does not fill the text.
address@hidden format
+
address@hidden smallformat
+Texinfo also provides a command @code{@@smallformat}, which is like
address@hidden@@format} but uses a smaller font in @code{@@smallbook} format.
address@hidden
+
+
+
address@hidden exdent
address@hidden @code{@@exdent}: Undoing a Line's Indentation
address@hidden Indentation undoing
address@hidden exdent
+
+The @code{@@exdent} command removes any indentation a line might have.
+The command is written at the beginning of a line and applies only to
+the text that follows the command that is on the same line. Do not use
+braces around the text. In a printed manual, the text on an
address@hidden@@exdent} line is printed in the roman address@hidden
+
address@hidden@@exdent} is usually used within examples. Thus,@refill
+
address@hidden
address@hidden
+@@example
+This line follows an @@@@example command.
+@@exdent This line is exdented.
+This line follows the exdented line.
+The @@@@end example comes on the next line.
+@@end group
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+This line follows an @@example command.
address@hidden This line is exdented.
+This line follows the exdented line.
+The @@end example comes on the next line.
address@hidden group
address@hidden example
+
+In practice, the @code{@@exdent} command is rarely used.
+Usually, you un-indent text by ending the example and
+returning the page to its normal address@hidden
+
+
address@hidden flushleft & flushright
address@hidden @code{@@flushleft} and @code{@@flushright}
address@hidden flushleft
address@hidden flushright
address@hidden ragged right
address@hidden ragged left
+
+The @code{@@flushleft} and @code{@@flushright} commands line up the
+ends of lines on the left and right margins of a page,
+but do not fill the text. The commands are written on lines of their
+own, without braces. The @code{@@flushleft} and @code{@@flushright}
+commands are ended by @code{@@end flushleft} and @code{@@end
+flushright} commands on lines of their address@hidden
+
address@hidden 1500
+For example,
+
address@hidden
address@hidden
+@@flushleft
+This text is
+written flushleft.
+@@end flushleft
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+This text is
+written flushleft.
address@hidden flushleft
address@hidden quotation
+
+
address@hidden@@flushright} produces the type of indentation often used in the
+return address of letters. For example,
+
address@hidden
address@hidden
+@@flushright
+Here is an example of text written
+flushright. The @@address@hidden@@address@hidden command
+right justifies every line but leaves the
+left end ragged.
+@@end flushright
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
+Here is an example of text written
+flushright. The @code{@@flushright} command
+right justifies every line but leaves the
+left end ragged.
address@hidden flushright
+
+
address@hidden noindent
address@hidden @code{@@noindent}: Omitting Indentation
address@hidden noindent
+
+An example or other inclusion can break a paragraph into segments.
+Ordinarily, the formatters indent text that follows an example as a new
+paragraph. However, you can prevent this by writing @code{@@noindent}
+at the beginning of a line by itself preceding the continuation
address@hidden
+
address@hidden 1500
+For example:
+
address@hidden
address@hidden
+@@example
+This is an example
+@@end example
+
+@@noindent
+This line is not indented. As you can see, the
+beginning of the line is fully flush left with the line
+that follows after it. (This whole example is between
+@@address@hidden@@@@address@hidden and @@address@hidden@@@@end address@hidden)
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+This is an example
address@hidden example
address@hidden
+% Remove extra vskip; this is a kludge to counter the effect of display
+\vskip-3.5\baselineskip
address@hidden tex
+
address@hidden
+This line is not indented. As you can see, the
+beginning of the line is fully flush left with the line
+that follows after it. (This whole example is between
address@hidden@@display} and @code{@@end display}.)
address@hidden display
+
+To adjust the number of blank lines properly in the Info file output,
+remember that the line containing @code{@@noindent} does not generate a
+blank line, and neither does the @code{@@end example} address@hidden
+
+In the Texinfo source file for this manual, each line that says
+`produces' is preceded by a line containing @code{@@address@hidden
+
+Do not put braces after an @code{@@noindent} command; they are not
+necessary, since @code{@@noindent} is a command used outside of
+paragraphs (@pxref{Command Syntax})address@hidden
+
+
address@hidden cartouche
address@hidden @code{@@cartouche}: Rounded Rectangles Around Examples
address@hidden cartouche
address@hidden Box with rounded corners
address@hidden Rounded rectangles, around examples
+
+In a printed manual, the @code{@@cartouche} command draws a box with
+rounded corners around its contents. You can use this command to
+further highlight an example or quotation. For instance, you could
+write a manual in which one type of example is surrounded by a cartouche
+for emphasis.
+
address@hidden@@cartouche} affects only the printed manual; it has no effect in
+other output files.
+
address@hidden 1500
+For example,
+
address@hidden
address@hidden
+@@example
+@@cartouche
+% pwd
+/usr/local/share/emacs
+@@end cartouche
+@@end example
address@hidden group
address@hidden example
+
address@hidden
+surrounds the two-line example with a box with rounded corners, in the
+printed manual.
+
+
+
address@hidden Lists and Tables
address@hidden Lists and Tables
address@hidden Making lists and tables
address@hidden Lists and tables, making
address@hidden Tables and lists, making
+
+Texinfo has several ways of making lists and tables. Lists can be
+bulleted or numbered; two-column tables can highlight the items in
+the first column; multi-column tables are also supported.
+
address@hidden
+* Introducing Lists:: Texinfo formats lists for you.
+* itemize:: How to construct a simple list.
+* 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.
address@hidden menu
+
address@hidden Introducing Lists, itemize, Lists and Tables, Lists and Tables
address@hidden Introducing Lists
+
+Texinfo automatically indents the text in lists or tables, and numbers
+an enumerated list. This last feature is useful if you modify the
+list, since you do not need to renumber it address@hidden
+
+Numbered lists and tables begin with the appropriate @@-command at the
+beginning of a line, and end with the corresponding @code{@@end}
+command on a line by itself. The table and itemized-list commands
+also require that you write formatting information on the same line as
+the beginning @@address@hidden
+
+Begin an enumerated list, for example, with an @code{@@enumerate}
+command and end the list with an @code{@@end enumerate} command.
+Begin an itemized list with an @code{@@itemize} command, followed on
+the same line by a formatting command such as @code{@@bullet}, and end
+the list with an @code{@@end itemize} address@hidden
address@hidden end
+
+Precede each element of a list with an @code{@@item} or @code{@@itemx}
address@hidden
+
address@hidden 1
address@hidden
+Here is an itemized list of the different kinds of table and lists:@refill
+
address@hidden @bullet
address@hidden
+Itemized lists with and without bullets.
+
address@hidden
+Enumerated lists, using numbers or letters.
+
address@hidden
+Two-column tables with highlighting.
address@hidden itemize
+
address@hidden 1
address@hidden
+Here is an enumerated list with the same items:@refill
+
address@hidden
address@hidden
+Itemized lists with and without bullets.
+
address@hidden
+Enumerated lists, using numbers or letters.
+
address@hidden
+Two-column tables with highlighting.
address@hidden enumerate
+
address@hidden 1
address@hidden
+And here is a two-column table with the same items and their
address@hidden@@-commands}:@refill
+
address@hidden @code
address@hidden @@itemize
+Itemized lists with and without bullets.
+
address@hidden @@enumerate
+Enumerated lists, using numbers or letters.
+
address@hidden @@table
address@hidden @@ftable
address@hidden @@vtable
+Two-column tables, optionally with indexing.
address@hidden table
+
+
address@hidden itemize
address@hidden @code{@@itemize}: Making an Itemized List
address@hidden Itemization
address@hidden itemize
+
+The @code{@@itemize} command produces sequences of indented
+paragraphs, with a bullet or other mark inside the left margin
+at the beginning of each paragraph for which such a mark is address@hidden
+
address@hidden @code{@@w}, for blank items
+Begin an itemized list by writing @code{@@itemize} at the beginning of
+a line. Follow the command, on the same line, with a character or a
+Texinfo command that generates a mark. Usually, you will write
address@hidden@@bullet} after @code{@@itemize}, but you can use
address@hidden@@minus}, or any command or character that results in a single
+character in the Info file. If you don't want any mark at all, use
address@hidden@@w}. (When you write the mark command such as
address@hidden@@bullet} after an @code{@@itemize} command, you may omit the
address@hidden@address@hidden) If you don't specify a mark command, the
default is
address@hidden@@bullet}.
+
+Write the text of the indented paragraphs themselves after the
address@hidden@@itemize}, up to another line that says @code{@@end
address@hidden
+
address@hidden item
+Before each paragraph for which a mark in the margin is desired, write a
+line that says just @code{@@item}. It is ok to have text following the
address@hidden@@item}.
+
+Usually, you should put a blank line before an @code{@@item}. This
+puts a blank line in the Info file. (@TeX{} inserts the proper
+interline whitespace in either case.) Except when the entries are
+very brief, these blank lines make the list look address@hidden
+
+Here is an example of the use of @code{@@itemize}, followed by the
+output it produces. @code{@@bullet} produces an @samp{*} in Info and a
+round dot in @TeX{}.
+
address@hidden
address@hidden
+@@itemize @@bullet
+@@item
+Some text for foo.
+
+@@item
+Some text
+for bar.
+@@end itemize
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
address@hidden @bullet
address@hidden
+Some text for foo.
+
address@hidden
+Some text
+for bar.
address@hidden itemize
address@hidden quotation
+
+Itemized lists may be embedded within other itemized lists. Here is a
+list marked with dashes embedded in a list marked with bullets:@refill
+
address@hidden
address@hidden
+@@itemize @@bullet
+@@item
+First item.
+
+@@itemize @@minus
+@@item
+Inner item.
+
+@@item
+Second inner item.
+@@end itemize
+
+@@item
+Second outer item.
+@@end itemize
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
address@hidden @bullet
address@hidden
+First item.
+
address@hidden @minus
address@hidden
+Inner item.
+
address@hidden
+Second inner item.
address@hidden itemize
+
address@hidden
+Second outer item.
address@hidden itemize
address@hidden quotation
+
+
address@hidden enumerate
address@hidden @code{@@enumerate}: Making a Numbered or Lettered List
address@hidden Enumeration
address@hidden enumerate
+
address@hidden@@enumerate} is like @code{@@itemize} (@pxref{itemize,,
address@hidden@@itemize}}), except that the labels on the items are
+successive integers or letters instead of bullets.
+
+Write the @code{@@enumerate} command at the beginning of a line. The
+command does not require an argument, but accepts either a number or a
+letter as an option. Without an argument, @code{@@enumerate} starts the
+list with the number @samp{1}. With a numeric argument, such as
address@hidden, the command starts the list with that number. With an upper
+or lower case letter, such as @samp{a} or @samp{A}, the command starts
+the list with that letter.
+
+Write the text of the enumerated list in the same way you write an
+itemized list: put @code{@@item} on a line of its own before the start
+of each paragraph that you want enumerated. Do not write any other text
+on the line beginning with @code{@@item}.
+
+You should put a blank line between entries in the list.
+This generally makes it easier to read the Info file.
+
address@hidden 1500
+Here is an example of @code{@@enumerate} without an argument:
+
address@hidden
address@hidden
+@@enumerate
+@@item
+Underlying causes.
+
+@@item
+Proximate causes.
+@@end enumerate
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
address@hidden
+Underlying causes.
+
address@hidden
+Proximate causes.
address@hidden enumerate
address@hidden 1
+Here is an example with an argument of @kbd{3}:@refill
address@hidden 1
address@hidden
address@hidden
+@@enumerate 3
+@@item
+Predisposing causes.
+
+@@item
+Precipitating causes.
+
+@@item
+Perpetuating causes.
+@@end enumerate
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden 3
address@hidden
+Predisposing causes.
+
address@hidden
+Precipitating causes.
+
address@hidden
+Perpetuating causes.
address@hidden enumerate
address@hidden 1
+Here is a brief summary of the alternatives. The summary is constructed
+using @code{@@enumerate} with an argument of @address@hidden
address@hidden 1
address@hidden a
address@hidden
address@hidden@@enumerate}
+
+Without an argument, produce a numbered list, starting with the number
address@hidden
+
address@hidden
address@hidden@@enumerate @var{positive-integer}}
+
+With a (positive) numeric argument, start a numbered list with that
+number. You can use this to continue a list that you interrupted with
+other address@hidden
+
address@hidden
address@hidden@@enumerate @var{upper-case-letter}}
+
+With an upper case letter as argument, start a list
+in which each item is marked
+by a letter, beginning with that upper case address@hidden
+
address@hidden
address@hidden@@enumerate @var{lower-case-letter}}
+
+With a lower case letter as argument, start a list
+in which each item is marked by
+a letter, beginning with that lower case address@hidden
address@hidden enumerate
+
+You can also nest enumerated lists, as in an address@hidden
+
address@hidden Two-column Tables, Multi-column Tables, enumerate, Lists and
Tables
address@hidden Making a Two-column Table
address@hidden Tables, making two-column
address@hidden table
+
address@hidden@@table} is similar to @code{@@itemize} (@pxref{itemize,,
address@hidden@@itemize}}), but allows you to specify a name or heading line for
+each item. The @code{@@table} command is used to produce two-column
+tables, and is especially useful for glossaries, explanatory
+exhibits, and command-line option summaries.
+
address@hidden
+* table:: How to construct a two-column table.
+* ftable vtable:: Automatic indexing for two-column tables.
+* itemx:: How to put more entries in the first column.
address@hidden menu
+
address@hidden table, ftable vtable, Two-column Tables, Two-column Tables
address@hidden Using the @code{@@table} Command
+
+Use the @code{@@table} command to produce two-column address@hidden
+
+Write the @code{@@table} command at the beginning of a line and follow
+it on the same line with an argument that is a Texinfo ``indicating''
+command such as @code{@@code}, @code{@@samp}, @code{@@var}, or
address@hidden@@kbd} (@pxref{Indicating}). Although these commands are usually
+followed by arguments in braces, in this case you use the command name
+without an argument because @code{@@item} will supply the argument.
+This command will be applied to the text that goes into the first column
+of each item and determines how it will be highlighted. For example,
address@hidden@@code} will cause the text in the first column to be highlighted
+with an @code{@@code} command. (We recommend @code{@@code} for
address@hidden@@table}'s of command-line options.)
+
address@hidden asis
+You may also choose to use the @code{@@asis} command as an argument to
address@hidden@@table}. @code{@@asis} is a command that does nothing; if you
+use this command after @code{@@table}, @TeX{} and the Info formatting
+commands output the first column entries without added highlighting
+(``as is'')address@hidden
+
+(The @code{@@table} command may work with other commands besides those
+listed here. However, you can only use commands that normally take
+arguments in braces.)@refill
+
address@hidden item
+Begin each table entry with an @code{@@item} command at the beginning
+of a line. Write the first column text on the same line as the
address@hidden@@item} command. Write the second column text on the line
+following the @code{@@item} line and on subsequent lines. (You do not
+need to type anything for an empty second column entry.) You may
+write as many lines of supporting text as you wish, even several
+paragraphs. But only text on the same line as the @code{@@item} will
+be placed in the first column, including any footnote.
+
+Normally, you should put a blank line before an @code{@@item} line.
+This puts a blank like in the Info file. Except when the entries are
+very brief, a blank line looks address@hidden
+
address@hidden 1500
+The following table, for example, highlights the text in the first
+column with an @code{@@samp} command:@refill
+
address@hidden
address@hidden
+@@table @@samp
+@@item foo
+This is the text for
+@@address@hidden@}.
+
+@@item bar
+Text for @@address@hidden@}.
+@@end table
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden @samp
address@hidden foo
+This is the text for
address@hidden
address@hidden bar
+Text for @samp{bar}.
address@hidden table
+
+If you want to list two or more named items with a single block of
+text, use the @code{@@itemx} command. (@xref{itemx, ,
address@hidden@@itemx}}.)@refill
+
+
address@hidden ftable vtable
address@hidden @code{@@ftable} and @code{@@vtable}
address@hidden Tables with indexes
address@hidden Indexing table entries automatically
address@hidden ftable
address@hidden vtable
+
+The @code{@@ftable} and @code{@@vtable} commands are the same as the
address@hidden@@table} command except that @code{@@ftable} automatically enters
+each of the items in the first column of the table into the index of
+functions and @code{@@vtable} automatically enters each of the items in
+the first column of the table into the index of variables. This
+simplifies the task of creating indices. Only the items on the same
+line as the @code{@@item} commands are indexed, and they are indexed in
+exactly the form that they appear on that line. @xref{Indices},
+for more information about address@hidden
+
+Begin a two-column table using @code{@@ftable} or @code{@@vtable} by
+writing the @@-command at the beginning of a line, followed on the same
+line by an argument that is a Texinfo command such as @code{@@code},
+exactly as you would for an @code{@@table} command; and end the table
+with an @code{@@end ftable} or @code{@@end vtable} command on a line by
+itself.
+
+See the example for @code{@@table} in the previous section.
+
address@hidden itemx
address@hidden @code{@@itemx}
address@hidden Two named items for @code{@@table}
address@hidden itemx
+
+Use the @code{@@itemx} command inside a table when you have two or more
+first column entries for the same item, each of which should appear on a
+line of its own. Use @code{@@itemx} for all but the first entry;
address@hidden@@itemx} should always follow an @code{@@item} command. The
address@hidden@@itemx} command works exactly like @code{@@item} except that it
+does not generate extra vertical space above the first column text.
+
+For example,
+
address@hidden
address@hidden
+@@table @@code
+@@item upcase
+@@itemx downcase
+These two functions accept a character or a string as
+argument, and return the corresponding upper case (lower
+case) character or string.
+@@end table
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden @code
address@hidden upcase
address@hidden downcase
+These two functions accept a character or a string as
+argument, and return the corresponding upper case (lower
+case) character or address@hidden
address@hidden table
+
address@hidden
+(Note also that this example illustrates multi-line supporting text in
+a two-column table.)@refill
+
+
address@hidden Multi-column Tables, , Two-column Tables, Lists and Tables
address@hidden Multi-column Tables
address@hidden Tables, making multi-column
address@hidden multitable
+
address@hidden@@multitable} allows you to construct tables with any number of
+columns, with each column having any width you like.
+
+You define the column widths on the @code{@@multitable} line itself, and
+write each row of the actual table following an @code{@@item} command,
+with columns separated by an @code{@@tab} command. Finally, @code{@@end
+multitable} completes the table. Details in the sections below.
+
address@hidden
+* Multitable Column Widths:: Defining multitable column widths.
+* Multitable Rows:: Defining multitable rows, with examples.
address@hidden menu
+
address@hidden Multitable Column Widths
address@hidden Multitable Column Widths
address@hidden Multitable column widths
address@hidden Column widths, defining for multitables
address@hidden Widths, defining multitable column
+
+You can define the column widths for a multitable in two ways: as
+fractions of the line length; or with a prototype row. Mixing the two
+methods is not supported. In either case, the widths are defined
+entirely on the same line as the @code{@@multitable} command.
+
address@hidden
address@hidden
address@hidden columnfractions
address@hidden Line length, column widths as fraction of
+To specify column widths as fractions of the line length, write
address@hidden@@columnfractions} and the decimal numbers (presumably less than
+1) after the @code{@@multitable} command, as in:
+
address@hidden
+@@multitable @@columnfractions .33 .33 .33
address@hidden example
+
address@hidden The fractions need not add up exactly to 1.0, as these do
+not. This allows you to produce tables that do not need the full line
+length. You can use a leading zero if you wish.
+
address@hidden
address@hidden Prototype row, column widths defined by
+To specify a prototype row, write the longest entry for each column
+enclosed in braces after the @code{@@multitable} command. For example:
+
address@hidden
+@@multitable @{some text for column address@hidden @{for column address@hidden
address@hidden example
+
address@hidden
+The first column will then have the width of the typeset `some text for
+column one', and the second column the width of `for column two'.
+
+The prototype entries need not appear in the table itself.
+
+Although we used simple text in this example, the prototype entries can
+contain Texinfo commands; markup commands such as @code{@@code} are
+particularly likely to be useful.
+
address@hidden enumerate
+
+
address@hidden Multitable Rows, , Multitable Column Widths, Multi-column Tables
address@hidden Multitable Rows
address@hidden Multitable rows
address@hidden Rows, of a multitable
+
address@hidden item
address@hidden tab
+After the @code{@@multitable} command defining the column widths (see
+the previous section), you begin each row in the body of a multitable
+with @code{@@item}, and separate the column entries with @code{@@tab}.
+Line breaks are not special within the table body, and you may break
+input lines in your source file as necessary.
+
+Here is a complete example of a multi-column table (the text is from
address@hidden GNU Emacs Manual}, @pxref{Split Window,, Splitting Windows,
+emacs, The GNU Emacs Manual}):
+
address@hidden
+@@multitable @@columnfractions .15 .45 .4
+@@item Key @@tab Command @@tab Description
+@@item C-x 2
+@@tab @@address@hidden@}
+@@tab Split the selected window into two windows,
+with one above the other.
+@@item C-x 3
+@@tab @@address@hidden@}
+@@tab Split the selected window into two windows
+positioned side by side.
+@@item C-Mouse-2
+@@tab
+@@tab In the mode line or scroll bar of a window,
+split that window.
+@@end multitable
address@hidden example
+
address@hidden produces:
+
address@hidden @columnfractions .15 .45 .4
address@hidden Key @tab Command @tab Description
address@hidden C-x 2
address@hidden @code{split-window-vertically}
address@hidden Split the selected window into two windows,
+with one above the other.
address@hidden C-x 3
address@hidden @code{split-window-horizontally}
address@hidden Split the selected window into two windows
+positioned side by side.
address@hidden C-Mouse-2
address@hidden
address@hidden In the mode line or scroll bar of a window,
+split that window.
address@hidden multitable
+
+
address@hidden Indices, Insertions, Lists and Tables, Top
address@hidden node-name, next, previous, up
address@hidden Indices
address@hidden Indices
+
+Using Texinfo, you can generate indices without having to sort and
+collate entries manually. In an index, the entries are listed in
+alphabetical order, together with information on how to find the
+discussion of each entry. In a printed manual, this information
+consists of page numbers. In an Info file, this information is a menu
+entry leading to the first node address@hidden
+
+Texinfo provides several predefined kinds of index: an index
+for functions, an index for variables, an index for concepts, and so
+on. You can combine indices or use them for other than their
+canonical purpose. If you wish, you can define your own address@hidden
+
address@hidden
+* Index Entries:: Choose different words for index entries.
+* Predefined Indices:: Use different indices for different kinds
+ of entry.
+* Indexing Commands:: How to make an index entry.
+* Combining Indices:: How to combine indices.
+* New Indices:: How to define your own indices.
address@hidden menu
+
address@hidden Index Entries, Predefined Indices, Indices, Indices
address@hidden node-name, next, previous, up
address@hidden Making Index Entries
address@hidden Index entries, making
address@hidden Entries, making index
+
+When you are making index entries, it is good practice to think of the
+different ways people may look for something. Different people
address@hidden not} think of the same words when they look something up. A
+helpful index will have items indexed under all the different words
+that people may use. For example, one reader may think it obvious that
+the two-letter names for indices should be listed under ``Indices,
+two-letter names'', since the word ``Index'' is the general concept.
+But another reader may remember the specific concept of two-letter
+names and search for the entry listed as ``Two letter names for
+indices''. A good index will have both entries and will help both
address@hidden
+
+Like typesetting, the construction of an index is a highly skilled,
+professional art, the subtleties of which are not appreciated until you
+need to do it address@hidden
+
address@hidden Indices & Menus}, for information about printing an index
+at the end of a book or creating an index menu in an Info address@hidden
+
address@hidden Predefined Indices, Indexing Commands, Index Entries, Indices
address@hidden node-name, next, previous, up
address@hidden Predefined Indices
+
+Texinfo provides six predefined indices:@refill
+
address@hidden @bullet
address@hidden
+A @dfn{concept index} listing concepts that are address@hidden
+
address@hidden
+A @dfn{function index} listing functions (such as entry points of
+libraries)address@hidden
+
address@hidden
+A @dfn{variables index} listing variables (such as global variables
+of libraries)address@hidden
+
address@hidden
+A @dfn{keystroke index} listing keyboard address@hidden
+
address@hidden
+A @dfn{program index} listing names of address@hidden
+
address@hidden
+A @dfn{data type index} listing data types (such as structures defined in
+header files)address@hidden
address@hidden itemize
+
address@hidden
+Not every manual needs all of these, and most manuals use two or three
+of them. This manual has two indices: a
+concept index and an @@-command index (that is actually the function
+index but is called a command index in the chapter heading). Two or
+more indices can be combined into one using the @code{@@synindex} or
address@hidden@@syncodeindex} commands. @xref{Combining address@hidden
+
address@hidden Indexing Commands, Combining Indices, Predefined Indices, Indices
address@hidden node-name, next, previous, up
address@hidden Defining the Entries of an Index
address@hidden Defining indexing entries
address@hidden Index entries
address@hidden Entries for an index
address@hidden Specifying index entries
address@hidden Creating index entries
+
+The data to make an index come from many individual indexing commands
+scattered throughout the Texinfo source file. Each command says to add
+one entry to a particular index; after formatting, the index will give
+the current page number or node name as the address@hidden
+
+An index entry consists of an indexing command at the beginning of a
+line followed, on the rest of the line, by the address@hidden
+
+For example, this section begins with the following five entries for
+the concept index:@refill
+
address@hidden
+@@cindex Defining indexing entries
+@@cindex Index entries
+@@cindex Entries for an index
+@@cindex Specifying index entries
+@@cindex Creating index entries
address@hidden example
+
+Each predefined index has its own indexing address@hidden@@cindex}
+for the concept index, @code{@@findex} for the function index, and so
address@hidden
+
address@hidden Writing index entries
address@hidden Index entry writing
+Concept index entries consist of text. The best way to write an index
+is to choose entries that are terse yet clear. If you can do this,
+the index often looks better if the entries are not capitalized, but
+written just as they would appear in the middle of a sentence.
+(Capitalize proper names and acronyms that always call for upper case
+letters.) This is the case convention we use in most GNU manuals'
+indices.
+
+If you don't see how to make an entry terse yet clear, make it longer
+and clear---not terse and confusing. If many of the entries are several
+words long, the index may look better if you use a different convention:
+to capitalize the first word of each entry. But do not capitalize a
+case-sensitive name such as a C or Lisp function name or a shell
+command; that would be a spelling error.
+
+Whichever case convention you use, please use it consistently!
+
+Entries in indices other than the concept index are symbol names in
+programming languages, or program names; these names are usually
+case-sensitive, so use upper and lower case as required for them.
+
+By default, entries for a concept index are printed in a small roman
+font and entries for the other indices are printed in a small
address@hidden@@code} font. You may change the way part of an entry is
+printed with the usual Texinfo commands, such as @code{@@file} for
+file names and @code{@@emph} for emphasis (@pxref{Marking
+Text})address@hidden
address@hidden Index font types
+
address@hidden Predefined indexing commands
address@hidden Indexing commands, predefined
+The six indexing commands for predefined indices are:
+
address@hidden @code
address@hidden @@cindex @var{concept}
address@hidden cindex
+Make an entry in the concept index for @address@hidden
+
address@hidden @@findex @var{function}
address@hidden findex
+Make an entry in the function index for @address@hidden
+
address@hidden @@vindex @var{variable}
address@hidden vindex
+Make an entry in the variable index for @address@hidden
+
address@hidden @@kindex @var{keystroke}
address@hidden kindex
+Make an entry in the key index for @address@hidden
+
address@hidden @@pindex @var{program}
address@hidden pindex
+Make an entry in the program index for @address@hidden
+
address@hidden @@tindex @var{data type}
address@hidden tindex
+Make an entry in the data type index for @var{data address@hidden
address@hidden table
+
address@hidden
address@hidden:} Do not use a colon in an index entry. In Info, a
+colon separates the menu entry name from the node name, so a colon in
+the entry itself confuses Info. @xref{Menu Parts, , The Parts of a
+Menu}, for more information about the structure of a menu entry.
address@hidden quotation
+
+You are not actually required to use the predefined indices for their
+canonical purposes. For example, suppose you wish to index some C
+preprocessor macros. You could put them in the function index along
+with actual functions, just by writing @code{@@findex} commands for
+them; then, when you print the ``Function Index'' as an unnumbered
+chapter, you could give it the title `Function and Macro Index' and
+all will be consistent for the reader. Or you could put the macros in
+with the data types by writing @code{@@tindex} commands for them, and
+give that index a suitable title so the reader will understand.
+(@xref{Printing Indices & Menus}.)@refill
+
address@hidden Combining Indices, New Indices, Indexing Commands, Indices
address@hidden node-name, next, previous, up
address@hidden Combining Indices
address@hidden Combining indices
address@hidden Indices, combining them
+
+Sometimes you will want to combine two disparate indices such as functions
+and concepts, perhaps because you have few enough of one of them that
+a separate index for them would look address@hidden
+
+You could put functions into the concept index by writing
address@hidden@@cindex} commands for them instead of @code{@@findex} commands,
+and produce a consistent manual by printing the concept index with the
+title `Function and Concept Index' and not printing the `Function
+Index' at all; but this is not a robust procedure. It works only if
+your document is never included as part of another
+document that is designed to have a separate function index; if your
+document were to be included with such a document, the functions from
+your document and those from the other would not end up together.
+Also, to make your function names appear in the right font in the
+concept index, you would need to enclose every one of them between
+the braces of @code{@@address@hidden
+
address@hidden
+* syncodeindex:: How to merge two indices, using @code{@@code}
+ font for the merged-from index.
+* synindex:: How to merge two indices, using the
+ default font of the merged-to index.
address@hidden menu
+
address@hidden syncodeindex
address@hidden @code{@@syncodeindex}
address@hidden syncodeindex
+
+When you want to combine functions and concepts into one index, you
+should index the functions with @code{@@findex} and index the concepts
+with @code{@@cindex}, and use the @code{@@syncodeindex} command to
+redirect the function index entries into the concept address@hidden
address@hidden syncodeindex
+
+The @code{@@syncodeindex} command takes two arguments; they are the name
+of the index to redirect, and the name of the index to redirect it to.
+The template looks like this:@refill
+
address@hidden
+@@syncodeindex @var{from} @var{to}
address@hidden example
+
address@hidden Predefined names for indices
address@hidden Two letter names for indices
address@hidden Indices, two letter names
address@hidden Names for indices
+For this purpose, the indices are given two-letter names:@refill
+
address@hidden @samp
address@hidden cp
+concept index
address@hidden fn
+function index
address@hidden vr
+variable index
address@hidden ky
+key index
address@hidden pg
+program index
address@hidden tp
+data type index
address@hidden table
+
+Write an @code{@@syncodeindex} command before or shortly after the
+end-of-header line at the beginning of a Texinfo file. For example,
+to merge a function index with a concept index, write the
+following:@refill
+
address@hidden
+@@syncodeindex fn cp
address@hidden example
+
address@hidden
+This will cause all entries designated for the function index to merge
+in with the concept index address@hidden
+
+To merge both a variables index and a function index into a concept
+index, write the following:@refill
+
address@hidden
address@hidden
+@@syncodeindex vr cp
+@@syncodeindex fn cp
address@hidden group
address@hidden example
+
address@hidden Fonts for indices
+The @code{@@syncodeindex} command puts all the entries from the `from'
+index (the redirected index) into the @code{@@code} font, overriding
+whatever default font is used by the index to which the entries are
+now directed. This way, if you direct function names from a function
+index into a concept index, all the function names are printed in the
address@hidden@@code} font as you would address@hidden
+
address@hidden synindex, , syncodeindex, Combining Indices
address@hidden @code{@@synindex}
address@hidden synindex
+
+The @code{@@synindex} command is nearly the same as the
address@hidden@@syncodeindex} command, except that it does not put the
+`from' index entries into the @code{@@code} font; rather it puts
+them in the roman font. Thus, you use @code{@@synindex} when you
+merge a concept index into a function address@hidden
+
address@hidden Indices & Menus}, for information about printing an index
+at the end of a book or creating an index menu in an Info address@hidden
+
address@hidden New Indices, , Combining Indices, Indices
address@hidden Defining New Indices
address@hidden Defining new indices
address@hidden Indices, defining new
address@hidden New index defining
address@hidden defindex
address@hidden defcodeindex
+
+In addition to the predefined indices, you may use the
address@hidden@@defindex} and @code{@@defcodeindex} commands to define new
+indices. These commands create new indexing @@-commands with which
+you mark index entries. The @code{@@defindex }command is used like
+this:@refill
+
address@hidden
+@@defindex @var{name}
address@hidden example
+
+The name of an index should be a two letter word, such as @samp{au}.
+For example:@refill
+
address@hidden
+@@defindex au
address@hidden example
+
+This defines a new index, called the @samp{au} index. At the same
+time, it creates a new indexing command, @code{@@auindex}, that you
+can use to make index entries. Use the new indexing command just as
+you would use a predefined indexing address@hidden
+
+For example, here is a section heading followed by a concept index
+entry and two @samp{au} index address@hidden
+
address@hidden
+@@section Cognitive Semantics
+@@cindex kinesthetic image schemas
+@@auindex Johnson, Mark
+@@auindex Lakoff, George
address@hidden example
+
address@hidden
+(Evidently, @samp{au} serves here as an abbreviation for ``author''.)
+Texinfo constructs the new indexing command by concatenating the name
+of the index with @samp{index}; thus, defining an @samp{au} index
+leads to the automatic creation of an @code{@@auindex} address@hidden
+
+Use the @code{@@printindex} command to print the index, as you do with
+the predefined indices. For example:@refill
+
address@hidden
address@hidden
+@@node Author Index, Subject Index, , Top
+@@unnumbered Author Index
+
+@@printindex au
address@hidden group
address@hidden example
+
+The @code{@@defcodeindex} is like the @code{@@defindex} command, except
+that, in the printed output, it prints entries in an @code{@@code} font
+instead of a roman font. Thus, it parallels the @code{@@findex} command
+rather than the @code{@@cindex} address@hidden
+
+You should define new indices within or right after the end-of-header
+line of a Texinfo file, before any @code{@@synindex} or
address@hidden@@syncodeindex} commands (@pxref{Texinfo File Header}).
+
+
address@hidden Insertions
address@hidden Special Insertions
address@hidden Inserting special characters and symbols
address@hidden Special insertions
+
+Texinfo provides several commands for inserting characters that have
+special meaning in Texinfo, such as braces, and for other graphic
+elements that do not correspond to simple characters you can type.
+
+
address@hidden
+* Braces Atsigns:: How to insert braces, @samp{@@}.
+* Inserting Space:: How to insert the right amount of space
+ within a sentence.
+* Inserting Accents:: How to insert accents and special characters.
+* Dots Bullets:: How to insert dots and bullets.
+* TeX and copyright:: How to insert the @TeX{} logo
+ and the copyright symbol.
+* pounds:: How to insert the pounds currency symbol.
+* minus:: How to insert a minus sign.
+* math:: How to format a mathematical expression.
+* Glyphs:: How to indicate results of evaluation,
+ expansion of macros, errors, etc.
+* Footnotes:: How to include footnotes.
+* Images:: How to include graphics.
address@hidden menu
+
+
address@hidden Braces Atsigns, Inserting Space, Insertions, Insertions
address@hidden Inserting @@ and Braces
address@hidden Inserting @@, braces
address@hidden Braces, inserting
address@hidden Special characters, commands to insert
address@hidden Commands to insert special characters
+
address@hidden@@} and curly braces are special characters in Texinfo. To insert
+these characters so they appear in text, you must put an @samp{@@} in
+front of these characters to prevent Texinfo from misinterpreting
+them.
+
+Do not put braces after any of these commands; they are not
+necessary.
+
address@hidden
+* Inserting An Atsign:: How to insert @samp{@@}.
+* Inserting Braces:: How to insert @address@hidden and
@address@hidden
address@hidden menu
+
address@hidden Inserting An Atsign, Inserting Braces, Braces Atsigns, Braces
Atsigns
address@hidden Inserting @samp{@@} with @@@@
address@hidden @@ @r{(literal @samp{@@})}
+
address@hidden@@@@} stands for a single @samp{@@} in either printed or Info
+output.
+
+Do not put braces after an @code{@@@@} command.
+
+
address@hidden Inserting Braces
address@hidden Inserting @address@hidden and @address@hidden @@@{ and @@@}
address@hidden @{ @r{(literal @address@hidden)}
address@hidden @} @r{(literal @address@hidden)}
+
address@hidden@@@{} stands for a single @address@hidden in either printed or
Info
+output.
+
address@hidden@@@}} stands for a single @address@hidden in either printed or
Info
+output.
+
+Do not put braces after either an @code{@@@{} or an @code{@@@}}
+command.
+
+
address@hidden Inserting Space
address@hidden Inserting Space
+
address@hidden Inserting space
address@hidden Spacing, inserting
+The following sections describe commands that control spacing of various
+kinds within and after sentences.
+
address@hidden
+* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
+* Ending a Sentence:: Sometimes it does.
+* Multiple Spaces:: Inserting multiple spaces.
+* dmn:: How to format a dimension.
address@hidden menu
+
+
address@hidden Not Ending a Sentence
address@hidden Not Ending a Sentence
+
address@hidden Not ending a sentence
address@hidden Sentence non-ending punctuation
address@hidden Periods, inserting
+Depending on whether a period or exclamation point or question mark is
+inside or at the end of a sentence, less or more space is inserted after
+a period in a typeset manual. Since it is not always possible
+to determine when a period ends a sentence and when it is used
+in an abbreviation, special commands are needed in some circumstances.
+Usually, Texinfo can guess how to handle periods, so you do not need to
+use the special commands; you just enter a period as you would if you
+were using a typewriter, which means you put two spaces after the
+period, question mark, or exclamation mark that ends a sentence.
+
address@hidden <colon> @r{(suppress widening)}
+Use the @code{@@:}@: command after a period, question mark,
+exclamation mark, or colon that should not be followed by extra space.
+For example, use @code{@@:}@: after periods that end abbreviations
+which are not at the ends of sentences.
+
+For example,
+
address@hidden
+The s.o.p.@@: has three parts @dots{}
+The s.o.p. has three parts @dots{}
address@hidden example
+
address@hidden
+produces
+
address@hidden
+The s.o.p.@: has three parts @address@hidden
+The s.o.p. has three parts @dots{}
address@hidden quotation
+
address@hidden
+(Incidentally, @samp{s.o.p.} is an abbreviation for ``Standard Operating
+Procedure''.)
+
address@hidden@@:} has no effect on the Info output. Do not put braces after
address@hidden@@:}.
+
+
address@hidden Ending a Sentence, Multiple Spaces, Not Ending a Sentence,
Inserting Space
address@hidden Ending a Sentence
+
address@hidden Ending a Sentence
address@hidden Sentence ending punctuation
+
address@hidden . @r{(end of sentence)}
address@hidden ! @r{(end of sentence)}
address@hidden ? @r{(end of sentence)}
+Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an
+exclamation point, and @code{@@?}@: instead of a question mark at the end
+of a sentence that ends with a single capital letter. Otherwise, @TeX{}
+will think the letter is an abbreviation and will not insert the correct
+end-of-sentence spacing. Here is an example:
+
address@hidden
+Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@.
+Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+Give it to M.I.B. and to address@hidden Also, give it to address@hidden@*
+Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
address@hidden quotation
+
+In the Info file output, @code{@@.}@: is equivalent to a simple
address@hidden; likewise for @code{@@!}@: and @code{@@?}@:.
+
+The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to
+work well with the Emacs sentence motion commands (@pxref{Sentences,,,
+emacs, The GNU Emacs Manual}).
+
+Do not put braces after any of these commands.
+
+
address@hidden Multiple Spaces, dmn, Ending a Sentence, Inserting Space
address@hidden Multiple Spaces
+
address@hidden Multiple spaces
address@hidden Whitespace, inserting
address@hidden Space, inserting horizontal
address@hidden (space)
address@hidden (tab)
address@hidden (newline)
+
+Ordinarily, @TeX{} collapses multiple whitespace characters (space, tab,
+and newline) into a single space. Info output, on the other hand,
+preserves whitespace as you type it, except for changing a newline into
+a space; this is why it is important to put two spaces at the end of
+sentences in Texinfo documents.
+
+Occasionally, you may want to actually insert several consecutive
+spaces, either for purposes of example (what your program does with
+multiple spaces as input), or merely for purposes of appearance in
+headings or lists. Texinfo supports three commands:
address@hidden@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all of
+which insert a single space into the output. (Here,
address@hidden@@@kbd{SPACE}} represents an @samp{@@} character followed by a
+space, i.e., @samp{@@ }, and @kbd{TAB} and @kbd{NL} represent the tab
+character and end-of-line, i.e., when @samp{@@} is the last character on
+a line.)
+
+For example,
address@hidden
+Spacey@@ @@ @@ @@
+example.
address@hidden example
+
address@hidden produces
+
address@hidden
+Spacey@ @ @ @
+example.
address@hidden example
+
+Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by
address@hidden@@multitable} (@pxref{Multi-column Tables}).
+
+Do not follow any of these commands with braces.
+
+To produce a non-breakable space, see @ref{w, non-breakable space}.
+
+
address@hidden dmn
address@hidden @code{@@address@hidden@address@hidden: Format a Dimension
address@hidden Thin space between number, dimension
address@hidden Dimension formatting
address@hidden Format a dimension
address@hidden dmn
+
+At times, you may want to write @address@hidden or
address@hidden@dmn{in}} with little or no space between the number and the
+abbreviation for the dimension. You can use the @code{@@dmn} command
+to do this. On seeing the command, @TeX{} inserts just enough space
+for proper typesetting; the Info formatting commands insert no space
+at all, since the Info file does not require it.
+
+To use the @code{@@dmn} command, write the number and then follow it
+immediately, with no intervening space, by @code{@@dmn}, and then by
+the dimension within braces. For example,
+
address@hidden
+A4 paper is 8.27@@address@hidden@} wide.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+A4 paper is address@hidden wide.
address@hidden quotation
+
+Not everyone uses this style. Some people prefer @address@hidden in.@@:}}
+or @address@hidden inches}} to @samp{8.27@@address@hidden@}} in the Texinfo
file.
+In these cases, however, the formatters may insert a line break between
+the number and the dimension, so use @code{@@w} (@pxref{w}). Also, if
+you write a period after an abbreviation within a sentence, you should
+write @samp{@@:} after the period to prevent @TeX{} from inserting extra
+whitespace, as shown here. @xref{Not Ending a Sentence}.
+
+
address@hidden Inserting Accents
address@hidden Inserting Accents
+
address@hidden Inserting accents
address@hidden Accents, inserting
address@hidden Floating accents, inserting
+
+Here is a table with the commands Texinfo provides for inserting
+floating accents. The commands with non-alphabetic names do not take
+braces around their argument (which is taken to be the next character).
+(Exception: @code{@@,} @emph{does} take braces around its argument.)
+This is so as to make the source as convenient to type and read as
+possible, since accented characters are very common in some languages.
+
address@hidden " @r{(umlaut accent)}
address@hidden Umlaut accent
address@hidden ' @r{(umlaut accent)}
address@hidden Acute accent
address@hidden = @r{(macron accent)}
address@hidden Macron accent
address@hidden ^ @r{(circumflex accent)}
address@hidden Circumflex accent
address@hidden ` @r{(grave accent)}
address@hidden Grave accent
address@hidden ~ @r{(tilde accent)}
address@hidden Tilde accent
address@hidden , @r{(cedilla accent)}
address@hidden Cedilla accent
address@hidden dotaccent
address@hidden Dot accent
address@hidden H @r{(Hungarian umlaut accent)}
address@hidden Hungarian umlaut accent
address@hidden ringaccent
address@hidden Ring accent
address@hidden tieaccent
address@hidden Tie-after accent
address@hidden u @r{(breve accent)}
address@hidden Breve accent
address@hidden ubaraccent
address@hidden Underbar accent
address@hidden udotaccent
address@hidden Underdot accent
address@hidden v @r{(check accent)}
address@hidden Check accent
address@hidden {@@address@hidden@}} {Output} {macron/overbar accent}
address@hidden Command @tab Output @tab What
address@hidden @t{@@"o} @tab @"o @tab umlaut accent
address@hidden @t{@@'o} @tab @'o @tab acute accent
address@hidden @t{@@,@address@hidden @tab @,{c} @tab cedilla
accent
address@hidden @t{@@=o} @tab @=o @tab macron/overbar
accent
address@hidden @t{@@^o} @tab @^o @tab circumflex accent
address@hidden @t{@@`o} @tab @`o @tab grave accent
address@hidden @t{@@~o} @tab @~o @tab tilde accent
address@hidden @t{@@address@hidden@}} @tab @dotaccent{o} @tab overdot accent
address@hidden @t{@@address@hidden@}} @tab @H{o} @tab long
Hungarian umlaut
address@hidden @t{@@address@hidden@}} @tab @ringaccent{o} @tab ring accent
address@hidden @t{@@address@hidden@}} @tab @tieaccent{oo} @tab tie-after accent
address@hidden @t{@@address@hidden@}} @tab @u{o} @tab breve
accent
address@hidden @t{@@address@hidden@}} @tab @ubaraccent{o} @tab underbar accent
address@hidden @t{@@address@hidden@}} @tab @udotaccent{o} @tab underdot accent
address@hidden @t{@@address@hidden@}} @tab @v{o} @tab hacek
or check accent
address@hidden multitable
+
+This table lists the Texinfo commands for inserting other characters
+commonly used in languages other than English.
+
address@hidden questiondown
address@hidden @questiondown{}
address@hidden exclamdown
address@hidden @exclamdown{}
address@hidden aa
address@hidden @aa{}
address@hidden AA
address@hidden @AA{}
address@hidden ae
address@hidden @ae{}
address@hidden AE
address@hidden @AE{}
address@hidden dotless
address@hidden @dotless{i}
address@hidden @dotless{j}
address@hidden Dotless i, j
address@hidden l
address@hidden @l{}
address@hidden L
address@hidden @L{}
address@hidden o
address@hidden @o{}
address@hidden O
address@hidden @O{}
address@hidden oe
address@hidden @oe{}
address@hidden OE
address@hidden @OE{}
address@hidden ss
address@hidden @ss{}
address@hidden Es-zet
address@hidden Sharp S
address@hidden German S
address@hidden {x@@address@hidden@}} {oe,OE} {es-zet or sharp S}
address@hidden @t{@@address@hidden@}} @tab @exclamdown{} @tab upside-down !
address@hidden @t{@@address@hidden@}} @tab @questiondown{} @tab upside-down ?
address@hidden @t{@@address@hidden@},@@address@hidden@}} @tab @aa{},@AA{}
@tab a,A with circle
address@hidden @t{@@address@hidden@},@@address@hidden@}} @tab @ae{},@AE{}
@tab ae,AE ligatures
address@hidden @t{@@address@hidden@}} @tab @dotless{i} @tab dotless i
address@hidden @t{@@address@hidden@}} @tab @dotless{j} @tab dotless j
address@hidden @t{@@address@hidden@},@@address@hidden@}} @tab @l{},@L{}
@tab suppressed-L,l
address@hidden @t{@@address@hidden@},@@address@hidden@}} @tab @o{},@O{}
@tab O,o with slash
address@hidden @t{@@address@hidden@},@@address@hidden@}} @tab @oe{},@OE{}
@tab oe,OE ligatures
address@hidden @t{@@address@hidden@}} @tab @ss{} @tab
es-zet or sharp S
address@hidden multitable
+
+
address@hidden Dots Bullets
address@hidden Inserting Ellipsis and Bullets
address@hidden Dots, inserting
address@hidden Bullets, inserting
address@hidden Ellipsis, inserting
address@hidden Inserting ellipsis
address@hidden Inserting dots
address@hidden Special typesetting commands
address@hidden Typesetting commands for dots, etc.
+
+An @dfn{ellipsis} (a line of dots) is not typeset as a string of
+periods, so a special command is used for ellipsis in Texinfo. The
address@hidden@@bullet} command is special, too. Each of these commands is
+followed by a pair of braces, @address@hidden@}}, without any whitespace
+between the name of the command and the braces. (You need to use braces
+with these commands because you can use them next to other text; without
+the braces, the formatters would be confused. @xref{Command Syntax, ,
+@@-Command Syntax}, for further information.)@refill
+
address@hidden
+* dots:: How to insert dots @dots{}
+* bullet:: How to insert a bullet.
address@hidden menu
+
+
address@hidden dots
address@hidden @code{@@address@hidden@} (@dots{}) and @code{@@address@hidden@}
(@enddots{})
address@hidden dots
address@hidden enddots
address@hidden Inserting dots
address@hidden Dots, inserting
+
+Use the @code{@@address@hidden@}} command to generate an ellipsis, which is
+three dots in a row, appropriately spaced, like this: address@hidden'. Do
+not simply write three periods in the input file; that would work for
+the Info file output, but would produce the wrong amount of space
+between the periods in the printed manual.
+
+Similarly, the @code{@@address@hidden@}} command generates an
+end-of-sentence ellipsis (four dots) @enddots{}
+
+
+
address@hidden bullet
address@hidden @code{@@address@hidden@} (@bullet{})
address@hidden bullet
+
+Use the @code{@@address@hidden@}} command to generate a large round dot, or
+the closest possible thing to one. In Info, an asterisk is address@hidden
+
+Here is a bullet: @bullet{}
+
+When you use @code{@@bullet} in @code{@@itemize}, you do not need to
+type the braces, because @code{@@itemize} supplies them.
+(@xref{itemize, , @code{@@itemize}}.)@refill
+
+
address@hidden TeX and copyright, pounds, Dots Bullets, Insertions
address@hidden Inserting @TeX{} and the Copyright Symbol
+
+The logo address@hidden' is typeset in a special fashion and it needs an
+@@-command. The copyright symbol, address@hidden', is also special.
+Each of these commands is followed by a pair of braces, @address@hidden@}},
+without any whitespace between the name of the command and the
address@hidden
+
address@hidden
+* tex:: How to insert the @TeX{} logo.
+* copyright symbol:: How to use @code{@@address@hidden@}.
address@hidden menu
+
+
address@hidden tex
address@hidden @code{@@address@hidden@} (@TeX{})
address@hidden tex (command)
+
+Use the @code{@@address@hidden@}} command to generate address@hidden'. In a
printed
+manual, this is a special logo that is different from three ordinary
+letters. In Info, it just looks like @samp{TeX}. The
address@hidden@@address@hidden@}} command is unique among Texinfo commands in
that the
address@hidden and the @samp{X} are in upper address@hidden
+
+
address@hidden copyright symbol
address@hidden @code{@@address@hidden@} (@copyright{})
address@hidden copyright
+
+Use the @code{@@address@hidden@}} command to generate address@hidden'. In
+a printed manual, this is a @samp{c} inside a circle, and in Info,
+this is @samp{(C)address@hidden
+
+
address@hidden pounds, minus, TeX and copyright, Insertions
address@hidden @code{@@address@hidden@} (@pounds{}): Pounds Sterling
address@hidden pounds
+
+Use the @code{@@address@hidden@}} command to generate address@hidden'. In a
+printed manual, this is the symbol for the currency pounds sterling.
+In Info, it is a @samp{#}. Other currency symbols are unfortunately not
+available.
+
+
address@hidden minus, math, pounds, Insertions
address@hidden @code{@@address@hidden@} (@minus{}): Inserting a Minus Sign
address@hidden minus
+
address@hidden em-dash
address@hidden hyphen
+Use the @code{@@address@hidden@}} command to generate a minus sign. In a
+fixed-width font, this is a single hyphen, but in a proportional font,
+the symbol is the customary length for a minus sign---a little longer
+than a hyphen, shorter than an em-dash:
+
address@hidden
address@hidden@minus{}} is a minus sign generated with
@samp{@@address@hidden@}},
+
+`-' is a hyphen generated with the character @samp{-},
+
+`---' is an em-dash for text.
address@hidden display
+
address@hidden
+In the fixed-width font used by Info, @code{@@address@hidden@}} is the same
+as a hyphen.
+
+You should not use @code{@@address@hidden@}} inside @code{@@code} or
address@hidden@@example} because the width distinction is not made in the
+fixed-width font they use.
+
+When you use @code{@@minus} to specify the mark beginning each entry in
+an itemized list, you do not need to type the braces
+(@pxref{itemize, , @code{@@itemize}}.)
+
+
address@hidden math
address@hidden @code{@@math}: Inserting Mathematical Expressions
address@hidden math
address@hidden Mathematical expressions
address@hidden Formulas, mathematical
+
+You can write a short mathematical expression with the @code{@@math}
+command. Write the mathematical expression between braces, like this:
+
address@hidden
+@@address@hidden(a + b)(a + b) = a^2 + 2ab + address@hidden
address@hidden example
+
address@hidden This produces the following in Info:
+
address@hidden
+(a + b)(a + b) = a^2 + 2ab + b^2
address@hidden example
+
+Thus, the @code{@@math} command has no effect on the Info output.
+
address@hidden@@math} implies @code{@@tex}. This not only makes it possible to
+write superscripts and subscripts (as in the above example), but also
+allows you to use any of the plain @TeX{} math control sequences. It's
+conventional to use @samp{\} instead of @samp{@@} for these commands.
+As in:
address@hidden
+@@address@hidden 2\pi \equiv \cos address@hidden
address@hidden example
+
address@hidden which looks like the input in Info and HTML:
address@hidden
+\sin 2\pi \equiv \cos 3\pi
address@hidden example
+
address@hidden \ @r{(literal \ in @code{@@math})}
+Since @samp{\} is an escape character inside @code{@@math}, you can use
address@hidden@@\} to get a literal backslash (@code{\\} will work in @TeX{},
+but you'll get the literal @samp{\\} in Info). @code{@@\} is not
+defined outside of @code{@@math}, since a @samp{\} ordinarily produces a
+literal @samp{\}.
+
+
address@hidden Displayed equations
address@hidden Equations, displayed
+For displayed equations, you must at present use @TeX{} directly
+(@pxref{Raw Formatter Commands}).
+
+
address@hidden Glyphs
address@hidden Glyphs for Examples
address@hidden Glyphs
address@hidden Examples, glyphs for
+
+In Texinfo, code is often illustrated in examples that are delimited
+by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and
address@hidden@@end lisp}. In such examples, you can indicate the results of
+evaluation or an expansion using @address@hidden or
address@hidden@expansion{}}. Likewise, there are commands to insert glyphs
+to indicate
+printed output, error messages, equivalence of expressions, and the
+location of address@hidden
+
+The glyph-insertion commands do not need to be used within an example, but
+most often they are. Every glyph-insertion command is followed by a pair of
+left- and right-hand address@hidden
+
address@hidden
+* Glyphs Summary::
+* result:: How to show the result of expression.
+* expansion:: How to indicate an expansion.
+* Print Glyph:: How to indicate printed output.
+* Error Glyph:: How to indicate an error message.
+* Equivalence:: How to indicate equivalence.
+* Point Glyph:: How to indicate the location of point.
address@hidden menu
+
+
address@hidden Glyphs Summary
address@hidden Glyphs Summary
+
+Here are the different glyph commands:@refill
+
address@hidden @asis
address@hidden @result{}
address@hidden@@address@hidden@}} points to the result of an address@hidden
+
address@hidden @expansion{}
address@hidden@@address@hidden@}} shows the results of a macro address@hidden
+
address@hidden @print{}
address@hidden@@address@hidden@}} indicates printed address@hidden
+
address@hidden @error{}
address@hidden@@address@hidden@}} indicates that the following text is an error
address@hidden
+
address@hidden @equiv{}
address@hidden@@address@hidden@}} indicates the exact equivalence of two
address@hidden
+
address@hidden @point{}
address@hidden@@address@hidden@}} shows the location of address@hidden
address@hidden table
+
address@hidden
+* result::
+* expansion::
+* Print Glyph::
+* Error Glyph::
+* Equivalence::
+* Point Glyph::
address@hidden menu
+
+
address@hidden result
address@hidden @code{@@address@hidden@}} (@result{}): Indicating Evaluation
address@hidden Result of an expression
address@hidden Indicating evaluation
address@hidden Evaluation glyph
address@hidden Value of an expression, indicating
address@hidden result
+
+Use the @code{@@address@hidden@}} command to indicate the result of
+evaluating an address@hidden
+
+The @code{@@address@hidden@}} command is displayed as @address@hidden in Info
+and as a double stemmed arrow in the printed address@hidden
+
+Thus, the following,
+
address@hidden
+(cdr '(1 2 3))
+ @result{} (2 3)
address@hidden lisp
+
address@hidden
+may be read as address@hidden(cdr '(1 2 3))} evaluates to @code{(2 3)}''.
+
+
address@hidden expansion, Print Glyph, result, Glyphs
address@hidden @code{@@address@hidden@}} (@expansion{}): Indicating an Expansion
address@hidden Expansion, indicating it
address@hidden expansion
+
+When an expression is a macro call, it expands into a new expression.
+You can indicate the result of the expansion with the
address@hidden@@address@hidden@}} address@hidden
+
+The @code{@@address@hidden@}} command is displayed as @address@hidden
+in Info and as a long arrow with a flat base in the printed address@hidden
+
address@hidden 700
+For example, the following
+
address@hidden
address@hidden
+@@lisp
+(third '(a b c))
+ @@address@hidden@} (car (cdr (cdr '(a b c))))
+ @@address@hidden@} c
+@@end lisp
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+(third '(a b c))
+ @expansion{} (car (cdr (cdr '(a b c))))
+ @result{} c
address@hidden group
address@hidden lisp
+
address@hidden
+which may be read as:
+
address@hidden
address@hidden(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))};
+the result of evaluating the expression is @code{c}.
address@hidden quotation
+
address@hidden
+Often, as in this case, an example looks better if the
address@hidden@@address@hidden@}} and @code{@@address@hidden@}} commands are
indented
+five address@hidden
+
+
address@hidden Print Glyph, Error Glyph, expansion, Glyphs
address@hidden @code{@@address@hidden@}} (@print{}): Indicating Printed Output
address@hidden Printed output, indicating it
address@hidden print
+
+Sometimes an expression will print output during its execution. You
+can indicate the printed output with the @code{@@address@hidden@}}
address@hidden
+
+The @code{@@address@hidden@}} command is displayed as @address@hidden in Info
+and similarly, as a horizontal dash butting against a vertical bar, in
+the printed address@hidden
+
+In the following example, the printed text is indicated with
address@hidden@print{}}, and the value of the expression follows on the
+last address@hidden
+
address@hidden
address@hidden
+(progn (print 'foo) (print 'bar))
+ @print{} foo
+ @print{} bar
+ @result{} bar
address@hidden group
address@hidden lisp
+
address@hidden
+In a Texinfo source file, this example is written as follows:
+
address@hidden
address@hidden
+@@lisp
+(progn (print 'foo) (print 'bar))
+ @@address@hidden@} foo
+ @@address@hidden@} bar
+ @@address@hidden@} bar
+@@end lisp
address@hidden group
address@hidden lisp
+
+
address@hidden Error Glyph, Equivalence, Print Glyph, Glyphs
address@hidden @code{@@address@hidden@}} (@error{}): Indicating an Error Message
address@hidden Error message, indicating it
address@hidden error
+
+A piece of code may cause an error when you evaluate it. You can
+designate the error message with the @code{@@address@hidden@}} address@hidden
+
+The @code{@@address@hidden@}} command is displayed as @address@hidden in Info
+and as the word `error' in a box in the printed address@hidden
+
address@hidden 700
+Thus,
+
address@hidden
+@@lisp
+(+ 23 'x)
+@@address@hidden@} Wrong type argument: integer-or-marker-p, x
+@@end lisp
address@hidden example
+
address@hidden
+produces
+
address@hidden
+(+ 23 'x)
address@hidden Wrong type argument: integer-or-marker-p, x
address@hidden lisp
+
address@hidden
+This indicates that the following error message is printed
+when you evaluate the expression:
+
address@hidden
+Wrong type argument: integer-or-marker-p, x
address@hidden lisp
+
address@hidden@error{}} itself is not part of the error message.
+
+
address@hidden Equivalence, Point Glyph, Error Glyph, Glyphs
address@hidden @code{@@address@hidden@}} (@equiv{}): Indicating Equivalence
address@hidden Equivalence, indicating it
address@hidden equiv
+
+Sometimes two expressions produce identical results. You can indicate the
+exact equivalence of two forms with the @code{@@address@hidden@}}
address@hidden
+
+The @code{@@address@hidden@}} command is displayed as @address@hidden in Info
+and as a three parallel horizontal lines in the printed address@hidden
+
+Thus,
+
address@hidden
+@@lisp
+(make-sparse-keymap) @@address@hidden@} (list 'keymap)
+@@end lisp
address@hidden example
+
address@hidden
+produces
+
address@hidden
+(make-sparse-keymap) @equiv{} (list 'keymap)
address@hidden lisp
+
address@hidden
+This indicates that evaluating @code{(make-sparse-keymap)} produces
+identical results to evaluating @code{(list 'keymap)}.
+
+
address@hidden Point Glyph
address@hidden @code{@@address@hidden@}} (@point{}): Indicating Point in a
Buffer
address@hidden Point, indicating in a buffer
address@hidden point
+
+Sometimes you need to show an example of text in an Emacs buffer. In
+such examples, the convention is to include the entire contents of the
+buffer in question between two lines of dashes containing the buffer
address@hidden
+
+You can use the @samp{@@address@hidden@}} command to show the location of point
+in the text in the buffer. (The symbol for point, of course, is not
+part of the text in the buffer; it indicates the place @emph{between}
+two characters where point is located.)@refill
+
+The @code{@@address@hidden@}} command is displayed as @address@hidden in Info
+and as a small five pointed star in the printed address@hidden
+
+The following example shows the contents of buffer @file{foo} before
+and after evaluating a Lisp command to insert the word @address@hidden
+
address@hidden
address@hidden
+---------- Buffer: foo ----------
+This is the @point{}contents of foo.
+---------- Buffer: foo ----------
+
address@hidden group
address@hidden example
+
address@hidden
address@hidden
+(insert "changed ")
+ @result{} nil
+---------- Buffer: foo ----------
+This is the changed @point{}contents of foo.
+---------- Buffer: foo ----------
+
address@hidden group
address@hidden example
+
+In a Texinfo source file, the example is written like this:@refill
+
address@hidden
+@@example
+---------- Buffer: foo ----------
+This is the @@address@hidden@}contents of foo.
+---------- Buffer: foo ----------
+
+(insert "changed ")
+ @@address@hidden@} nil
+---------- Buffer: foo ----------
+This is the changed @@address@hidden@}contents of foo.
+---------- Buffer: foo ----------
+@@end example
address@hidden example
+
+
address@hidden Footnotes
address@hidden Footnotes
address@hidden Footnotes
address@hidden footnote
+
+A @dfn{footnote} is for a reference that documents or elucidates the
+primary address@hidden footnote should complement or expand upon
+the primary text, but a reader should not need to read a footnote to
+understand the primary text. For a thorough discussion of footnotes,
+see @cite{The Chicago Manual of Style}, which is published by the
+University of Chicago Press.}
+
address@hidden
+* Footnote Commands:: How to write a footnote in Texinfo.
+* Footnote Styles:: Controlling how footnotes appear in Info.
address@hidden menu
+
+
address@hidden Footnote Commands
address@hidden Footnote Commands
+
+In Texinfo, footnotes are created with the @code{@@footnote} command.
+This command is followed immediately by a left brace, then by the text
+of the footnote, and then by a terminating right brace. Footnotes may
+be of any length (they will be broken across pages if necessary), but
+are usually short. The template is:
+
address@hidden
+ordinary text@@address@hidden@var{text of address@hidden
address@hidden example
+
+As shown here, the @code{@@footnote} command should come right after the
+text being footnoted, with no intervening space; otherwise, the footnote
+marker might end up starting a line.
+
+For example, this clause is followed by a sample address@hidden
+is the sample footnote.}; in the Texinfo source, it looks like
+this:
+
address@hidden
address@hidden sample footnote@@address@hidden is the sample
address@hidden; in the Texinfo address@hidden
address@hidden example
+
+As you can see, the source includes two punctuation marks next to each
+other; in this case, @address@hidden;} is the sequence. This is normal (the
+first ends the footnote and the second belongs to the sentence being
+footnoted), so don't worry that it looks odd.
+
+In a printed manual or book, the reference mark for a footnote is a
+small, superscripted number; the text of the footnote appears at the
+bottom of the page, below a horizontal line.
+
+In Info, the reference mark for a footnote is a pair of parentheses
+with the footnote number between them, like this: @samp{(1)}. The
+reference mark is followed by a cross-reference link to the footnote's
+text.
+
+In the HTML output, footnote references are marked with a small,
+superscripted number which is rendered as a hypertext link to the
+footnote text.
+
+By the way, footnotes in the argument of an @code{@@item} command for a
address@hidden@@table} must be on the same line as the @code{@@item}
+(as usual). @xref{Two-column Tables}.
+
+
address@hidden Footnote Styles
address@hidden Footnote Styles
+
+Info has two footnote styles, which determine where the text of the
+footnote is located:@refill
+
address@hidden @bullet
address@hidden @address@hidden node footnote style
address@hidden
+In the `End' node style, all the footnotes for a single node
+are placed at the end of that node. The footnotes are separated from
+the rest of the node by a line of dashes with the word
address@hidden within it. Each footnote begins with an
address@hidden(@var{n})} reference address@hidden
+
address@hidden 700
address@hidden
+Here is an example of a single footnote in the end of node style:@refill
+
address@hidden
address@hidden
+ --------- Footnotes ---------
+
+(1) Here is a sample footnote.
address@hidden group
address@hidden example
+
address@hidden @address@hidden footnote style
address@hidden
+In the `Separate' node style, all the footnotes for a single
+node are placed in an automatically constructed node of
+their own. In this style, a ``footnote reference'' follows
+each @samp{(@var{n})} reference mark in the body of the
+node. The footnote reference is actually a cross reference
+which you use to reach the footnote address@hidden
+
+The name of the node with the footnotes is constructed
+by appending @address@hidden to the name of the node
+that contains the footnotes. (Consequently, the footnotes'
+node for the @file{Footnotes} node is
address@hidden@file{Footnotes-Footnotes}}!) The footnotes' node has an
+`Up' node pointer that leads back to its parent address@hidden
+
address@hidden
+Here is how the first footnote in this manual looks after being
+formatted for Info in the separate node style:@refill
+
address@hidden
address@hidden
+File: texinfo.info Node: Overview-Footnotes, Up: Overview
+
+(1) The first syllable of "Texinfo" is pronounced like "speck", not
+"hex". @dots{}
address@hidden group
address@hidden smallexample
address@hidden itemize
+
+A Texinfo file may be formatted into an Info file with either footnote
address@hidden
+
address@hidden footnotestyle
+Use the @code{@@footnotestyle} command to specify an Info file's
+footnote style. Write this command at the beginning of a line followed
+by an argument, either @samp{end} for the end node style or
address@hidden for the separate node style.
+
address@hidden 700
+For example,
+
address@hidden
+@@footnotestyle end
address@hidden example
address@hidden
+or
address@hidden
+@@footnotestyle separate
address@hidden example
+
+Write an @code{@@footnotestyle} command before or shortly after the
+end-of-header line at the beginning of a Texinfo file. (If you
+include the @code{@@footnotestyle} command between the start-of-header
+and end-of-header lines, the region formatting commands will format
+footnotes as specified.)@refill
+
+If you do not specify a footnote style, the formatting commands use
+their default style. Currently, @code{texinfo-format-buffer} and
address@hidden use the `separate' style and
address@hidden uses the `end' address@hidden
+
address@hidden !!! note: makeinfo's --footnote-style option overrides
footnotestyle
+This chapter contains two address@hidden
+
+
address@hidden this should be described with figures when we have them
address@hidden perhaps in the quotation/example chapter.
address@hidden Images
address@hidden Inserting Images
+
address@hidden Images, inserting
address@hidden Pictures, inserting
address@hidden image
+
+You can insert an image given in an external file with the
address@hidden@@image} command:
+
address@hidden
+@@address@hidden@var{filename}, @address@hidden@r{]}, @address@hidden@r{]},
@address@hidden@r{]}, @address@hidden@address@hidden
address@hidden example
+
address@hidden Formats for images
address@hidden Image formats
+The @var{filename} argument is mandatory, and must not have an
+extension, because the different processors support different formats:
address@hidden @bullet
address@hidden
address@hidden reads the file @address@hidden (Encapsulated PostScript
+format).
address@hidden
address@hidden address@hidden, and images}
address@hidden reads @address@hidden (Adobe's Portable Document Format).
address@hidden
address@hidden uses @address@hidden verbatim for
+Info output (more or less as if it was an @code{@@example}).
address@hidden
address@hidden
+uses the optional fifth argument to @code{@@image} for the extension if
+you supply it. For example:
+
address@hidden XPM image format
address@hidden
+@@address@hidden,,,,address@hidden
address@hidden example
+
address@hidden
+will cause @samp{makeinfo --html} to try @file{foo.xpm}.
+
address@hidden GIF, unsupported due to patents
address@hidden PNG image format
address@hidden JPG image format
+If you do not supply the optional fifth argument, @samp{makeinfo
+---html} first tries @address@hidden; if that does not exist,
+it tries @address@hidden If that does not exist either, it
+complains. (We cannot support GIF format directly due to software
+patents.)
address@hidden itemize
+
address@hidden Width of images
address@hidden Height of images
address@hidden Aspect ratio of images
address@hidden Distorting images
+The optional @var{width} and @var{height} arguments specify the size to
+scale the image to (they are ignored for Info output). If neither is
+specified, the image is presented in its natural size (given in the
+file); if only one is specified, the other is scaled proportionately;
+and if both are specified, both are respected, thus possibly distorting
+the original image by changing its aspect ratio.
+
address@hidden Dimensions and image sizes
+The @var{width} and @var{height} may be specified using any valid @TeX{}
+dimension, namely:
+
address@hidden @asis
address@hidden pt
address@hidden Points (dimension)
+point (72.27pt = 1in)
address@hidden pc
address@hidden Picas
+pica (1pc = 12pt)
address@hidden bp
address@hidden Big points
+big point (72bp = 1in)
address@hidden in
address@hidden Inches
+inch
address@hidden cm
address@hidden Centimeters
+centimeter (2.54cm = 1in)
address@hidden mm
address@hidden Millimeters
+millimeter (10mm = 1cm)
address@hidden dd
address@hidden address@hidden points
address@hidden point (1157dd = 1238pt)
address@hidden cc
address@hidden Ciceros
+cicero (1cc = 12dd)
address@hidden sp
address@hidden Scaled points
+scaled point (65536sp = 1pt)
address@hidden table
+
address@hidden ridt.eps
+For example, the following will scale a file @file{ridt.eps} to one
+inch vertically, with the width scaled proportionately:
+
address@hidden
+@@address@hidden,,address@hidden
address@hidden example
+
address@hidden epsf.tex
+For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be
+installed somewhere that @TeX{} can find it. (The standard location is
address@hidden@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a
+root of your @TeX{} directory tree.) This file is included in the
+Texinfo distribution and is also available from
address@hidden://tug.org/tex/epsf.tex}, among other places.
+
address@hidden@@image} can be used within a line as well as for displayed
+figures. Therefore, if you intend it to be displayed, be sure to leave
+a blank line before the command, or the output will run into the
+preceding text.
+
address@hidden alt attribute for images
address@hidden alternate text for images
+When producing html, @code{makeinfo} sets the @dfn{alt attribute} for
+inline images to the optional fourth argument to @code{@@image}, if
+supplied. If not supplied, @code{makeinfo} uses the full file name of
+the image being displayed.
+
+
address@hidden Breaks
address@hidden Making and Preventing Breaks
address@hidden Making line and page breaks
address@hidden Preventing line and page breaks
+
address@hidden Line breaks
+Usually, a Texinfo file is processed both by @TeX{} and by one of the
+Info formatting commands. Line, paragraph, or page breaks sometimes
+occur in the `wrong' place in one or other form of output. You must
+ensure that text looks right both in the printed manual and in the
+Info file.
+
address@hidden White space, excessive
address@hidden Page breaks
+For example, in a printed manual, page breaks may occur awkwardly in
+the middle of an example; to prevent this, you can hold text together
+using a grouping command that keeps the text from being split across
+two pages. Conversely, you may want to force a page break where none
+would occur normally. Fortunately, problems like these do not often
+arise. When they do, use the break, break prevention, or pagination
+commands.
+
address@hidden
+* Break Commands:: Cause and prevent splits.
+* Line Breaks:: How to force a single line to use two lines.
+* - and hyphenation:: How to tell @TeX{} about hyphenation points.
+* w:: How to prevent unwanted line breaks.
+* sp:: How to insert blank lines.
+* page:: How to force the start of a new page.
+* group:: How to prevent unwanted page breaks.
+* need:: Another way to prevent unwanted page breaks.
address@hidden menu
+
+
address@hidden Break Commands, Line Breaks, Breaks, Breaks
address@hidden Break Commands
+
+The break commands create or allow line and paragraph breaks:@refill
+
address@hidden @code
address@hidden @@*
+Force a line break.
+
address@hidden @@sp @var{n}
+Skip @var{n} blank address@hidden
+
address@hidden @@-
+Insert a discretionary hyphen.
+
address@hidden @@address@hidden@var{hy-phen-a-ted address@hidden
+Define hyphen points in @var{hy-phen-a-ted words}.
address@hidden table
+
+The line-break-prevention command holds text together all on one
+line:@refill
+
address@hidden @code
address@hidden @@address@hidden@address@hidden
+Prevent @var{text} from being split and hyphenated across two address@hidden
address@hidden table
+
+The pagination commands apply only to printed output, since Info
+files do not have address@hidden
+
address@hidden @code
address@hidden @@page
+Start a new page in the printed address@hidden
+
address@hidden @@group
+Hold text together that must appear on one printed address@hidden
+
address@hidden @@need @var{mils}
+Start a new printed page if not enough space on this address@hidden
address@hidden table
+
address@hidden Line Breaks
address@hidden @code{@@*}: Generate Line Breaks
address@hidden * @r{(force line break)}
address@hidden Line breaks
address@hidden Breaks in a line
+
+The @code{@@*} command forces a line break in both the printed manual and
+in address@hidden
+
address@hidden 700
+For example,
+
address@hidden
+This line @@* is broken @@*in two places.
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+This line
+ is broken
+in two places.
address@hidden group
address@hidden example
+
address@hidden
+(Note that the space after the first @code{@@*} command is faithfully
+carried down to the next line.)@refill
+
address@hidden 800
+The @code{@@*} command is often used in a file's copyright page:@refill
+
address@hidden
address@hidden
+This is edition 2.0 of the Texinfo documentation,@@*
+and is for @dots{}
address@hidden group
address@hidden example
+
address@hidden
+In this case, the @code{@@*} command keeps @TeX{} from stretching the
+line across the whole page in an ugly address@hidden
+
address@hidden
address@hidden note:} Do not write braces after an @code{@@*} command;
+they are not address@hidden
+
+Do not write an @code{@@refill} command at the end of a paragraph
+containing an @code{@@*} command; it will cause the paragraph to be
+refilled after the line break occurs, negating the effect of the line
address@hidden
address@hidden quotation
+
+
address@hidden - and hyphenation
address@hidden @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate
+
address@hidden - @r{(discretionary hyphen)}
address@hidden hyphenation
address@hidden Hyphenation, helping @TeX{} do
address@hidden Fine-tuning, and hyphenation
+
+Although @TeX{}'s hyphenation algorithm is generally pretty good, it
+does miss useful hyphenation points from time to time. (Or, far more
+rarely, insert an incorrect hyphenation.) So, for documents with an
+unusual vocabulary or when fine-tuning for a printed edition, you may
+wish to help @TeX{} out. Texinfo supports two commands for this:
+
address@hidden @code
address@hidden @@-
+Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does
+not have to) hyphenate. This is especially useful when you notice an
+overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull
+hboxes}). @TeX{} will not insert any hyphenation points itself into a
+word containing @code{@@-}.
+
address@hidden @@address@hidden@var{hy-phen-a-ted address@hidden
+Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you
+put a @samp{-} at each hyphenation point. For example:
address@hidden
+@@address@hidden address@hidden
address@hidden example
address@hidden @TeX{} only uses the specified hyphenation points when the
+words match exactly, so give all necessary variants.
address@hidden table
+
+Info output is not hyphenated, so these commands have no effect there.
+
address@hidden w
address@hidden @code{@@address@hidden@address@hidden: Prevent Line Breaks
address@hidden w @r{(prevent line break)}
address@hidden Line breaks, preventing
address@hidden Hyphenation, preventing
+
address@hidden@@address@hidden@address@hidden outputs @var{text} and prohibits
line breaks
+within @address@hidden
+
+You can use the @code{@@w} command to prevent @TeX{} from automatically
+hyphenating a long name or phrase that happens to fall near the end of a
+line. For example:
+
address@hidden
+You can copy GNU software from @@address@hidden@@address@hidden@address@hidden
address@hidden example
+
address@hidden
+produces
+
address@hidden
+You can copy GNU software from @address@hidden
address@hidden quotation
+
address@hidden Non-breakable space
address@hidden Unbreakable space
address@hidden Tied space
+You can also use @code{@@w} to produce a non-breakable space:
+
address@hidden
+None of the formatters will break at this@@address@hidden @}space.
address@hidden example
+
+
address@hidden sp
address@hidden @code{@@sp} @var{n}: Insert Blank Lines
address@hidden sp @r{(line spacing)}
address@hidden Space, inserting vertical
address@hidden Blank lines
address@hidden Line spacing
+
+A line beginning with and containing only @code{@@sp @var{n}}
+generates @var{n} blank lines of space in both the printed manual and
+the Info file. @code{@@sp} also forces a paragraph break. For
+example,
+
address@hidden
+@@sp 2
address@hidden example
+
address@hidden
+generates two blank lines.
+
+The @code{@@sp} command is most often used in the title address@hidden
+
+
+
address@hidden page
address@hidden @code{@@page}: Start a New Page
address@hidden Page breaks
address@hidden page
+
+A line containing only @code{@@page} starts a new page in a printed
+manual. The command has no effect on Info files since they are not
+paginated. An @code{@@page} command is often used in the @code{@@titlepage}
+section of a Texinfo file to start the copyright page.
+
+
address@hidden group, need, page, Breaks
address@hidden node-name, next, previous, up
address@hidden @code{@@group}: Prevent Page Breaks
address@hidden Group (hold text together vertically)
address@hidden Holding text together vertically
address@hidden Vertically holding text together
address@hidden group
+
+The @code{@@group} command (on a line by itself) is used inside an
address@hidden@@example} or similar construct to begin an unsplittable vertical
+group, which will appear entirely on one page in the printed output.
+The group is terminated by a line containing only @code{@@end group}.
+These two lines produce no output of their own, and in the Info file
+output they have no effect at address@hidden
+
address@hidden Once said that these environments
address@hidden turn off vertical spacing between ``paragraphs''.
address@hidden Also, quotation used to work, but doesn't in texinfo-2.72
+Although @code{@@group} would make sense conceptually in a wide
+variety of contexts, its current implementation works reliably only
+within @code{@@example} and variants, and within @code{@@display},
address@hidden@@format}, @code{@@flushleft} and @code{@@flushright}.
address@hidden and Examples}. (What all these commands have in
+common is that each line of input produces a line of output.) In
+other contexts, @code{@@group} can cause anomalous vertical
address@hidden
+
address@hidden 750
+This formatting requirement means that you should write:
+
address@hidden
address@hidden
+@@example
+@@group
address@hidden
+@@end group
+@@end example
address@hidden group
address@hidden example
+
address@hidden
+with the @code{@@group} and @code{@@end group} commands inside the
address@hidden@@example} and @code{@@end example} commands.
+
+The @code{@@group} command is most often used to hold an example
+together on one page. In this Texinfo manual, more than 100 examples
+contain text that is enclosed between @code{@@group} and @code{@@end
+group}.
+
+If you forget to end a group, you may get strange and unfathomable
+error messages when you run @TeX{}. This is because @TeX{} keeps
+trying to put the rest of the Texinfo file onto the one page and does
+not start to generate error messages until it has processed
+considerable text. It is a good rule of thumb to look for a missing
address@hidden@@end group} if you get incomprehensible error messages in
address@hidden@refill
+
address@hidden need, , group, Breaks
address@hidden node-name, next, previous, up
address@hidden @code{@@need @var{mils}}: Prevent Page Breaks
address@hidden Need space at page bottom
address@hidden need
+
+A line containing only @code{@@need @var{n}} starts
+a new page in a printed manual if fewer than @var{n} mils (thousandths
+of an inch) remain on the current page. Do not use
+braces around the argument @var{n}. The @code{@@need} command has no
+effect on Info files since they are not address@hidden
+
address@hidden 800
+This paragraph is preceded by an @code{@@need} command that tells
address@hidden to start a new page if fewer than 800 mils (eight-tenths
+inch) remain on the page. It looks like this:@refill
+
address@hidden
address@hidden
+@@need 800
+This paragraph is preceded by @dots{}
address@hidden group
address@hidden example
+
+The @code{@@need} command is useful for preventing orphans (single
+lines at the bottoms of printed pages)address@hidden
+
+
address@hidden Definition Commands
address@hidden Definition Commands
address@hidden Definition commands
+
+The @code{@@deffn} command and the other @dfn{definition commands}
+enable you to describe functions, variables, macros, commands, user
+options, special forms and other such artifacts in a uniform
address@hidden
+
+In the Info file, a definition causes the entity
+category---`Function', `Variable', or whatever---to appear at the
+beginning of the first line of the definition, followed by the
+entity's name and arguments. In the printed manual, the command
+causes @TeX{} to print the entity's name and its arguments on the left
+margin and print the category next to the right margin. In both
+output formats, the body of the definition is indented. Also, the
+name of the entity is entered into the appropriate index:
address@hidden@@deffn} enters the name into the index of functions,
address@hidden@@defvr} enters it into the index of variables, and so
address@hidden
+
+A manual need not and should not contain more than one definition for
+a given name. An appendix containing a summary should use
address@hidden@@table} rather than the definition address@hidden
+
address@hidden
+* Def Cmd Template:: How to structure a description using a
+ definition command.
+* Optional Arguments:: How to handle optional and repeated arguments.
+* deffnx:: How to group two or more `first' lines.
+* Def Cmds in Detail:: All the definition commands.
+* Def Cmd Conventions:: Conventions for writing definitions.
+* Sample Function Definition::
address@hidden menu
+
address@hidden Def Cmd Template, Optional Arguments, Definition Commands,
Definition Commands
address@hidden The Template for a Definition
address@hidden Definition template
address@hidden Template for a definition
+
+The @code{@@deffn} command is used for definitions of entities that
+resemble functions. To write a definition using the @code{@@deffn}
+command, write the @code{@@deffn} command at the beginning of a line
+and follow it on the same line by the category of the entity, the name
+of the entity itself, and its arguments (if any). Then write the body
+of the definition on succeeding lines. (You may embed examples in the
+body.) Finally, end the definition with an @code{@@end deffn} command
+written on a line of its own. (The other definition commands follow
+the same format.)@refill
+
+The template for a definition looks like this:
+
address@hidden
address@hidden
+@@deffn @var{category} @var{name} @address@hidden
address@hidden
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden 700
address@hidden
+For example,
+
address@hidden
address@hidden
+@@deffn Command forward-word count
+This command moves point forward @@address@hidden@} words
+(or backward if @@address@hidden@} is negative). @dots{}
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden Command forward-word count
+This function moves point forward @var{count} words
+(or backward if @var{count} is negative). @dots{}
address@hidden deffn
address@hidden quotation
+
+Capitalize the category name like a title. If the name of the
+category contains spaces, as in the phrase `Interactive Command',
+write braces around it. For example:@refill
+
address@hidden
address@hidden
+@@deffn @{Interactive address@hidden isearch-forward
address@hidden
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden
+Otherwise, the second word will be mistaken for the name of the
address@hidden
+
+Some of the definition commands are more general than others. The
address@hidden@@deffn} command, for example, is the general definition command
+for functions and the like---for entities that may take arguments. When
+you use this command, you specify the category to which the entity
+belongs. The @code{@@deffn} command possesses three predefined,
+specialized variations, @code{@@defun}, @code{@@defmac}, and
address@hidden@@defspec}, that specify the category for you: ``Function'',
+``Macro'', and ``Special Form'' respectively. (In Lisp, a special form
+is an entity much like a function.) The @code{@@defvr} command also is
+accompanied by several predefined, specialized variations for describing
+particular kinds of address@hidden
+
+The template for a specialized definition, such as @code{@@defun}, is
+similar to the template for a generalized definition, except that you
+do not need to specify the category:@refill
+
address@hidden
address@hidden
+@@defun @var{name} @address@hidden
address@hidden
+@@end defun
address@hidden group
address@hidden example
+
address@hidden
+Thus,
+
address@hidden
address@hidden
+@@defun buffer-end flag
+This function returns @@address@hidden(point-min)@} if @@address@hidden@}
+is less than 1, @@address@hidden(point-max)@} otherwise.
address@hidden
+@@end defun
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden buffer-end flag
+This function returns @code{(point-min)} if @var{flag} is less than 1,
address@hidden(point-max)} otherwise. @dots{}
address@hidden defun
address@hidden quotation
+
address@hidden
address@hidden Function Definition, Sample Function Definition, A Sample
+Function Definition}, for a more detailed example of a function
+definition, including the use of @code{@@example} inside the
address@hidden
+
+The other specialized commands work like @code{@@address@hidden
+
address@hidden Macros in definition commands
+Note that, due to implementation difficulties, macros are not expanded
+in @code{@@deffn} and all the other definition commands.
+
address@hidden Optional Arguments, deffnx, Def Cmd Template, Definition Commands
address@hidden Optional and Repeated Arguments
address@hidden Optional and repeated arguments
address@hidden Repeated and optional arguments
address@hidden Arguments, repeated and optional
address@hidden Syntax, optional & repeated arguments
address@hidden Meta-syntactic chars for arguments
+
+Some entities take optional or repeated arguments, which may be
+specified by a distinctive glyph that uses square brackets and
+ellipses. For @w{example}, a special form often breaks its argument list
+into separate arguments in more complicated ways than a
+straightforward address@hidden
+
address@hidden The following looks better in Info (no `r', `samp' and `code'):
+An argument enclosed within square brackets is optional.
+Thus, address@hidden means that @var{optional-arg} is optional.
+An argument followed by an ellipsis is optional
+and may be repeated more than once.
address@hidden This is consistent with Emacs Lisp Reference manual
+Thus, @address@hidden stands for zero or more arguments.
+Parentheses are used when several arguments are grouped
+into additional levels of list structure in Lisp.
+
+Here is the @code{@@defspec} line of an example of an imaginary
+special form:@refill
+
address@hidden
address@hidden foobar (@var{var} address@hidden @var{to} address@hidden)
@address@hidden
address@hidden defspec
address@hidden
+\vskip \parskip
address@hidden tex
address@hidden quotation
+
address@hidden
+In this example, the arguments @var{from} and @var{to} are optional,
+but must both be present or both absent. If they are present,
address@hidden may optionally be specified as well. These arguments are
+grouped with the argument @var{var} into a list, to distinguish them
+from @var{body}, which includes all remaining elements of the
address@hidden
+
+In a Texinfo source file, this @code{@@defspec} line is written like
+this (except it would not be split over two lines, as it is in this
+example)address@hidden
+
address@hidden
address@hidden
+@@defspec foobar (@@address@hidden@} [@@address@hidden@} @@address@hidden@}
+ [@@address@hidden@}]]) @@address@hidden@}@@address@hidden@}
address@hidden group
address@hidden example
+
address@hidden
+The function is listed in the Command and Variable Index under
address@hidden@refill
+
address@hidden deffnx, Def Cmds in Detail, Optional Arguments, Definition
Commands
address@hidden Two or More `First' Lines
address@hidden Two `First' Lines for @code{@@deffn}
address@hidden Grouping two definitions together
address@hidden Definitions grouped together
address@hidden deffnx
+
+To create two or more `first' or header lines for a definition, follow
+the first @code{@@deffn} line by a line beginning with @code{@@deffnx}.
+The @code{@@deffnx} command works exactly like @code{@@deffn}
+except that it does not generate extra vertical white space between it
+and the preceding address@hidden
+
address@hidden 1000
+For example,
+
address@hidden
address@hidden
+@@deffn @{Interactive address@hidden isearch-forward
+@@deffnx @{Interactive address@hidden isearch-backward
+These two search commands are similar except @dots{}
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden {Interactive Command} isearch-forward
address@hidden {Interactive Command} isearch-backward
+These two search commands are similar except @dots{}
address@hidden deffn
+
+Each definition command has an `x' form: @code{@@defunx},
address@hidden@@defvrx}, @code{@@deftypefunx}, etc.
+
+The `x' forms work just like @code{@@itemx}; see @ref{itemx, , @code{@@itemx}}.
+
address@hidden Def Cmds in Detail, Def Cmd Conventions, deffnx, Definition
Commands
address@hidden The Definition Commands
+
+Texinfo provides more than a dozen definition commands, all of which
+are described in this address@hidden
+
+The definition commands automatically enter the name of the entity in
+the appropriate index: for example, @code{@@deffn}, @code{@@defun},
+and @code{@@defmac} enter function names in the index of functions;
address@hidden@@defvr} and @code{@@defvar} enter variable names in the index
+of address@hidden
+
+Although the examples that follow mostly illustrate Lisp, the commands
+can be used for other programming address@hidden
+
address@hidden
+* 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.
+* Abstract Objects:: Commands for object-oriented programming.
+* Data Types:: The definition command for data types.
address@hidden menu
+
address@hidden Functions Commands, Variables Commands, Def Cmds in Detail, Def
Cmds in Detail
address@hidden Functions and Similar Entities
+
+This section describes the commands for describing functions and similar
+entities:@refill
+
address@hidden @code
address@hidden deffn
address@hidden @@deffn @var{category} @var{name} @address@hidden
+The @code{@@deffn} command is the general definition command for
+functions, interactive commands, and similar entities that may take
+arguments. You must choose a term to describe the category of entity
+being defined; for example, ``Function'' could be used if the entity is
+a function. The @code{@@deffn} command is written at the beginning of a
+line and is followed on the same line by the category of entity being
+described, the name of this particular entity, and its arguments, if
+any. Terminate the definition with @code{@@end deffn} on a line of its
address@hidden
+
address@hidden 750
+For example, here is a definition:
+
address@hidden
address@hidden
+@@deffn Command forward-char nchars
+Move point forward @@address@hidden@} characters.
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden
+This shows a rather terse definition for a ``command'' named
address@hidden with one argument, @var{nchars}.
+
address@hidden@@deffn} prints argument names such as @var{nchars} in italics or
+upper case, as if @code{@@var} had been used, because we think of these
+names as metasyntactic variables---they stand for the actual argument
+values. Within the text of the description, write an argument name
+explicitly with @code{@@var} to refer to the value of the argument. In
+the example above, we used @samp{@@address@hidden@}} in this way.
+
+The template for @code{@@deffn} is:
+
address@hidden
address@hidden
+@@deffn @var{category} @var{name} @address@hidden
address@hidden
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden defun
address@hidden @@defun @var{name} @address@hidden
+The @code{@@defun} command is the definition command for functions.
address@hidden@@defun} is equivalent to @samp{@@deffn Function
address@hidden@refill
+
address@hidden 800
address@hidden
+For example,
+
address@hidden
address@hidden
+@@defun set symbol new-value
+Change the value of the symbol @@address@hidden@}
+to @@address@hidden@}.
+@@end defun
address@hidden group
address@hidden example
+
address@hidden
+shows a rather terse definition for a function @code{set} whose
+arguments are @var{symbol} and @var{new-value}. The argument names on
+the @code{@@defun} line automatically appear in italics or upper case as
+if they were enclosed in @code{@@var}. Terminate the definition with
address@hidden@@end defun} on a line of its address@hidden
+
+The template is:
+
address@hidden
address@hidden
+@@defun @var{function-name} @address@hidden
address@hidden
+@@end defun
address@hidden group
address@hidden example
+
address@hidden@@defun} creates an entry in the index of functions.
+
address@hidden defmac
address@hidden @@defmac @var{name} @address@hidden
+The @code{@@defmac} command is the definition command for macros.
address@hidden@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and
+works like @code{@@address@hidden
+
address@hidden defspec
address@hidden @@defspec @var{name} @address@hidden
+The @code{@@defspec} command is the definition command for special
+forms. (In Lisp, a special form is an entity much like a function,
address@hidden Forms,,, elisp, GNU Emacs Lisp Reference Manual}.)
address@hidden@@defspec} is equivalent to @samp{@@deffn @{Special address@hidden
address@hidden and works like @code{@@address@hidden
address@hidden table
+
address@hidden Variables Commands, Typed Functions, Functions Commands, Def
Cmds in Detail
address@hidden Variables and Similar Entities
+
+Here are the commands for defining variables and similar
+entities:@refill
+
address@hidden @code
address@hidden defvr
address@hidden @@defvr @var{category} @var{name}
+The @code{@@defvr} command is a general definition command for
+something like a variable---an entity that records a value. You must
+choose a term to describe the category of entity being defined; for
+example, ``Variable'' could be used if the entity is a variable.
+Write the @code{@@defvr} command at the beginning of a line and
+follow it on the same line by the category of the entity and the
+name of the entity.
+
+Capitalize the category name like a title. If the name of the category
+contains spaces, as in the name ``User Option'', enclose it in braces.
+Otherwise, the second word will be mistaken for the name of the entity.
+For example,
+
address@hidden
address@hidden
+@@defvr @{User address@hidden fill-column
+This buffer-local variable specifies
+the maximum width of filled lines.
address@hidden
+@@end defvr
address@hidden group
address@hidden example
+
+Terminate the definition with @code{@@end defvr} on a line of its
address@hidden
+
+The template is:
+
address@hidden
address@hidden
+@@defvr @var{category} @var{name}
address@hidden
+@@end defvr
address@hidden group
address@hidden example
+
address@hidden@@defvr} creates an entry in the index of variables for
@var{name}.
+
address@hidden defvar
address@hidden @@defvar @var{name}
+The @code{@@defvar} command is the definition command for variables.
address@hidden@@defvar} is equivalent to @samp{@@defvr Variable
address@hidden@refill
+
address@hidden 750
+For example:
+
address@hidden
address@hidden
+@@defvar kill-ring
address@hidden
+@@end defvar
address@hidden group
address@hidden example
+
+The template is:
+
address@hidden
address@hidden
+@@defvar @var{name}
address@hidden
+@@end defvar
address@hidden group
address@hidden example
+
address@hidden@@defvar} creates an entry in the index of variables for
address@hidden@refill
+
address@hidden defopt
address@hidden @@defopt @var{name}
address@hidden User options, marking
+The @code{@@defopt} command is the definition command for @dfn{user
+options}, i.e., variables intended for users to change according to
+taste; Emacs has many such (@pxref{Variables,,, emacs, The GNU Emacs
+Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User
address@hidden @dots{}} and works like @code{@@address@hidden
address@hidden table
+
+
address@hidden Typed Functions, Typed Variables, Variables Commands, Def Cmds
in Detail
address@hidden Functions in Typed Languages
+
+The @code{@@deftypefn} command and its variations are for describing
+functions in languages in which you must declare types of variables and
+functions, such as C and C++.
+
address@hidden @code
address@hidden deftypefn
address@hidden @@deftypefn @var{category} @var{data-type} @var{name}
@address@hidden
+The @code{@@deftypefn} command is the general definition command for
+functions and similar entities that may take arguments and that are
+typed. The @code{@@deftypefn} command is written at the beginning of
+a line and is followed on the same line by the category of entity
+being described, the type of the returned value, the name of this
+particular entity, and its arguments, if address@hidden
+
address@hidden 800
address@hidden
+For example,
+
address@hidden
address@hidden
+@@deftypefn @{Library address@hidden int foobar
+ (int @@address@hidden@}, float @@address@hidden@})
address@hidden
+@@end deftypefn
address@hidden group
address@hidden example
+
address@hidden 1000
address@hidden
+(where the text before the address@hidden'', shown above as two lines, would
+actually be a single line in a real Texinfo file) produces the following
+in Info:
+
address@hidden
address@hidden
+-- Library Function: int foobar (int FOO, float BAR)
address@hidden
address@hidden group
address@hidden smallexample
+
+This means that @code{foobar} is a ``library function'' that returns an
address@hidden, and its arguments are @var{foo} (an @code{int}) and
address@hidden (a @code{float})address@hidden
+
+The argument names that you write in @code{@@deftypefn} are not subject
+to an implicit @code{@@var}---since the actual names of the arguments in
address@hidden@@deftypefn} are typically scattered among data type names and
+keywords, Texinfo cannot find them without help. Instead, you must write
address@hidden@@var} explicitly around the argument names. In the example
+above, the argument names are @samp{foo} and @address@hidden
+
+The template for @code{@@deftypefn} is:@refill
+
address@hidden
address@hidden
+@@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{}
address@hidden
+@@end deftypefn
address@hidden group
address@hidden example
+
address@hidden
+Note that if the @var{category} or @var{data type} is more than one
+word then it must be enclosed in braces to make it a single address@hidden
+
+If you are describing a procedure in a language that has packages,
+such as Ada, you might consider using @code{@@deftypefn} in a manner
+somewhat contrary to the convention described in the preceding
address@hidden
+
address@hidden 800
address@hidden
+For example:
+
address@hidden
address@hidden
+@@deftypefn stacks private push
+ (@@address@hidden@}:in out stack;
+ @@address@hidden@}:in integer)
address@hidden
+@@end deftypefn
address@hidden group
address@hidden example
+
address@hidden
+(The @code{@@deftypefn} arguments are shown split into three lines, but
+would be a single line in a real Texinfo file.)
+
+In this instance, the procedure is classified as belonging to the
+package @code{stacks} rather than classified as a `procedure' and its
+data type is described as @code{private}. (The name of the procedure
+is @code{push}, and its arguments are @var{s} and @var{n}.)@refill
+
address@hidden@@deftypefn} creates an entry in the index of functions for
address@hidden@refill
+
address@hidden @@deftypefun @var{data-type} @var{name} @address@hidden
address@hidden deftypefun
+The @code{@@deftypefun} command is the specialized definition command
+for functions in typed languages. The command is equivalent to
address@hidden@@deftypefn Function @address@hidden
+
address@hidden 800
address@hidden
+Thus,
+
address@hidden
address@hidden
+@@deftypefun int foobar (int @@address@hidden@}, float @@address@hidden@})
address@hidden
+@@end deftypefun
address@hidden group
address@hidden smallexample
+
address@hidden
+produces the following in Info:
+
address@hidden
address@hidden
+-- Function: int foobar (int FOO, float BAR)
address@hidden
address@hidden group
address@hidden example
+
address@hidden 800
+The template is:
+
address@hidden
address@hidden
+@@deftypefun @var{type} @var{name} @address@hidden
address@hidden
+@@end deftypefun
address@hidden group
address@hidden example
+
address@hidden@@deftypefun} creates an entry in the index of functions for
address@hidden@refill
+
address@hidden table
+
+
address@hidden Typed Variables, Abstract Objects, Typed Functions, Def Cmds in
Detail
address@hidden Variables in Typed Languages
+
+Variables in typed languages are handled in a manner similar to
+functions in typed languages. @xref{Typed Functions}. The general
+definition command @code{@@deftypevr} corresponds to
address@hidden@@deftypefn} and the specialized definition command
address@hidden@@deftypevar} corresponds to @code{@@address@hidden
+
address@hidden @code
address@hidden deftypevr
address@hidden @@deftypevr @var{category} @var{data-type} @var{name}
+The @code{@@deftypevr} command is the general definition command for
+something like a variable in a typed language---an entity that records
+a value. You must choose a term to describe the category of the
+entity being defined; for example, ``Variable'' could be used if the
+entity is a address@hidden
+
+The @code{@@deftypevr} command is written at the beginning of a line
+and is followed on the same line by the category of the entity
+being described, the data type, and the name of this particular
address@hidden
+
address@hidden 800
address@hidden
+For example:
+
address@hidden
address@hidden
+@@deftypevr @{Global address@hidden int enable
address@hidden
+@@end deftypevr
address@hidden group
address@hidden example
+
address@hidden
+produces the following in Info:
+
address@hidden
address@hidden
+-- Global Flag: int enable
address@hidden
address@hidden group
address@hidden example
+
address@hidden 800
+The template is:
+
address@hidden
+@@deftypevr @var{category} @var{data-type} @var{name}
address@hidden
+@@end deftypevr
address@hidden example
+
address@hidden@@deftypevr} creates an entry in the index of variables for
address@hidden@refill
+
address@hidden deftypevar
address@hidden @@deftypevar @var{data-type} @var{name}
+The @code{@@deftypevar} command is the specialized definition command
+for variables in typed languages. @code{@@deftypevar} is equivalent
+to @samp{@@deftypevr Variable @address@hidden
+
address@hidden 800
address@hidden
+For example:
+
address@hidden
address@hidden
+@@deftypevar int fubar
address@hidden
+@@end deftypevar
address@hidden group
address@hidden example
+
address@hidden
+produces the following in Info:
+
address@hidden
address@hidden
+-- Variable: int fubar
address@hidden
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+The template is:
+
address@hidden
address@hidden
+@@deftypevar @var{data-type} @var{name}
address@hidden
+@@end deftypevar
address@hidden group
address@hidden example
+
address@hidden@@deftypevar} creates an entry in the index of variables for
address@hidden@refill
address@hidden table
+
address@hidden Abstract Objects
address@hidden Object-Oriented Programming
+
+Here are the commands for formatting descriptions about abstract
+objects, such as are used in object-oriented programming. A class is
+a defined type of abstract object. An instance of a class is a
+particular object that has the type of the class. An instance
+variable is a variable that belongs to the class but for which each
+instance has its own address@hidden
+
+In a definition, if the name of a class is truly a name defined in the
+programming system for a class, then you should write an @code{@@code}
+around it. Otherwise, it is printed in the usual text address@hidden
+
address@hidden @code
address@hidden defcv
address@hidden @@defcv @var{category} @var{class} @var{name}
+The @code{@@defcv} command is the general definition command for
+variables associated with classes in object-oriented programming. The
address@hidden@@defcv} command is followed by three arguments: the category of
+thing being defined, the class to which it belongs, and its
+name. Thus,@refill
+
address@hidden
address@hidden
+@@defcv @{Class address@hidden Window border-pattern
address@hidden
+@@end defcv
address@hidden group
address@hidden example
+
address@hidden
+illustrates how you would write the first line of a definition of the
address@hidden class option of the class @address@hidden
+
+The template is:
address@hidden
address@hidden
+@@defcv @var{category} @var{class} @var{name}
address@hidden
+@@end defcv
address@hidden group
address@hidden example
+
address@hidden@@defcv} creates an entry in the index of variables.
+
address@hidden defivar
address@hidden @@defivar @var{class} @var{name}
+The @code{@@defivar} command is the definition command for instance
+variables in object-oriented programming. @code{@@defivar} is
+equivalent to @samp{@@defcv @{Instance address@hidden @address@hidden
+
+The template is:
address@hidden
address@hidden
+@@defivar @var{class} @var{instance-variable-name}
address@hidden
+@@end defivar
address@hidden group
address@hidden example
+
address@hidden@@defivar} creates an entry in the index of variables.
+
address@hidden deftypeivar
address@hidden @@deftypeivar @var{class} @var{data-type} @var{name}
+The @code{@@deftypeivar} command is the definition command for typed
+instance variables in object-oriented programming. It is similar to
address@hidden@@defivar} with the addition of the @var{data-type} parameter to
+specify the type of the instance variable. @code{@@deftypeivar} creates an
+entry in the index of variables.
+
address@hidden defop
address@hidden @@defop @var{category} @var{class} @var{name} @address@hidden
+The @code{@@defop} command is the general definition command for
+entities that may resemble methods in object-oriented programming.
+These entities take arguments, as functions do, but are associated with
+particular classes of address@hidden
+
+For example, some systems have constructs called @dfn{wrappers} that
+are associated with classes as methods are, but that act more like
+macros than like functions. You could use @code{@@defop Wrapper} to
+describe one of address@hidden
+
+Sometimes it is useful to distinguish methods and @dfn{operations}.
+You can think of an operation as the specification for a method.
+Thus, a window system might specify that all window classes have a
+method named @code{expose}; we would say that this window system
+defines an @code{expose} operation on windows in general. Typically,
+the operation has a name and also specifies the pattern of arguments;
+all methods that implement the operation must accept the same
+arguments, since applications that use the operation do so without
+knowing which method will implement address@hidden
+
+Often it makes more sense to document operations than methods. For
+example, window application developers need to know about the
address@hidden operation, but need not be concerned with whether a
+given class of windows has its own method to implement this operation.
+To describe this operation, you would write:@refill
+
address@hidden
+@@defop Operation windows expose
address@hidden example
+
+The @code{@@defop} command is written at the beginning of a line and
+is followed on the same line by the overall name of the category of
+operation, the name of the class of the operation, the name of the
+operation, and its arguments, if address@hidden
+
+The template is:
address@hidden
address@hidden
+@@defop @var{category} @var{class} @var{name} @address@hidden
address@hidden
+@@end defop
address@hidden group
address@hidden example
+
address@hidden@@defop} creates an entry, such as address@hidden on
address@hidden', in the index of address@hidden
+
address@hidden deftypeop
address@hidden @@deftypeop @var{category} @var{class} @var{data-type}
@var{name} @address@hidden
+The @code{@@deftypeop} command is the definition command for typed
+operations in object-oriented programming. It is similar to
address@hidden@@defop} with the addition of the @var{data-type} parameter to
+specify the return type of the method. @code{@@deftypeop} creates an
+entry in the index of functions.
+
address@hidden @@defmethod @var{class} @var{name} @address@hidden
address@hidden defmethod
+The @code{@@defmethod} command is the definition command for methods
+in object-oriented programming. A method is a kind of function that
+implements an operation for a particular class of objects and its
+subclasses.
+
address@hidden@@defmethod} is equivalent to @samp{@@defop Method @dots{}}.
+The command is written at the beginning of a line and is followed by
+the name of the class of the method, the name of the method, and its
+arguments, if address@hidden
+
address@hidden
+For example:
address@hidden
address@hidden
+@@defmethod @code{bar-class} bar-method argument
address@hidden
+@@end defmethod
address@hidden group
address@hidden example
+
address@hidden
+illustrates the definition for a method called @code{bar-method} of
+the class @code{bar-class}. The method takes an address@hidden
+
+The template is:
+
address@hidden
address@hidden
+@@defmethod @var{class} @var{method-name} @address@hidden
address@hidden
+@@end defmethod
address@hidden group
address@hidden example
+
address@hidden@@defmethod} creates an entry, such as address@hidden on
address@hidden', in the index of address@hidden
+
+
address@hidden @@deftypemethod @var{class} @var{data-type} @var{name}
@address@hidden
address@hidden defmethod
+The @code{@@deftypemethod} command is the definition command for methods
+in object-oriented typed languages, such as C++ and Java. It is similar
+to the @code{@@defmethod} command with the addition of the
address@hidden parameter to specify the return type of the method.
+
address@hidden table
+
+
address@hidden Data Types
address@hidden Data Types
+
+Here is the command for data types:@refill
+
address@hidden @code
address@hidden deftp
address@hidden @@deftp @var{category} @var{name} @address@hidden
+The @code{@@deftp} command is the generic definition command for data
+types. The command is written at the beginning of a line and is
+followed on the same line by the category, by the name of the type
+(which is a word like @code{int} or @code{float}), and then by names of
+attributes of objects of that type. Thus, you could use this command
+for describing @code{int} or @code{float}, in which case you could use
address@hidden type} as the category. (A data type is a category of
+certain objects for purposes of deciding which operations can be
+performed on them.)@refill
+
+In Lisp, for example, @dfn{pair} names a particular data
+type, and an object of that type has two slots called the
address@hidden and the @sc{cdr}. Here is how you would write the first line
+of a definition of @address@hidden
+
address@hidden
address@hidden
+@@deftp @{Data address@hidden pair car cdr
address@hidden
+@@end deftp
address@hidden group
address@hidden example
+
address@hidden 950
+The template is:
+
address@hidden
address@hidden
+@@deftp @var{category} @var{name-of-type} @address@hidden
address@hidden
+@@end deftp
address@hidden group
address@hidden example
+
address@hidden@@deftp} creates an entry in the index of data types.
address@hidden table
+
address@hidden Def Cmd Conventions, Sample Function Definition, Def Cmds in
Detail, Definition Commands
address@hidden Conventions for Writing Definitions
address@hidden Definition conventions
address@hidden Conventions for writing definitions
+
+When you write a definition using @code{@@deffn}, @code{@@defun}, or
+one of the other definition commands, please take care to use
+arguments that indicate the meaning, as with the @var{count} argument
+to the @code{forward-word} function. Also, if the name of an argument
+contains the name of a type, such as @var{integer}, take care that the
+argument actually is of that address@hidden
+
address@hidden Sample Function Definition, , Def Cmd Conventions, Definition
Commands
address@hidden A Sample Function Definition
address@hidden Function definitions
address@hidden Command definitions
address@hidden Macro definitions
address@hidden Sample function definition
+
+A function definition uses the @code{@@defun} and @code{@@end defun}
+commands. The name of the function follows immediately after the
address@hidden@@defun} command and it is followed, on the same line, by the
+parameter address@hidden
+
+Here is a definition from @ref{Calling Functions,,, elisp, The GNU Emacs
+Lisp Reference Manual}.
+
address@hidden
address@hidden apply function &rest arguments
address@hidden calls @var{function} with @var{arguments}, just
+like @code{funcall} but with one difference: the last of
address@hidden is a list of arguments to give to
address@hidden, rather than a single argument. We also say
+that this list is @dfn{appended} to the other arguments.
+
address@hidden returns the result of calling @var{function}.
+As with @code{funcall}, @var{function} must either be a Lisp
+function or a primitive function; special forms and macros
+do not make sense in @code{apply}.
+
address@hidden
+(setq f 'list)
+ @result{} list
+(apply f 'x 'y 'z)
address@hidden Wrong type argument: listp, z
+(apply '+ 1 2 '(3 4))
+ @result{} 10
+(apply '+ '(1 2 3 4))
+ @result{} 10
+
+(apply 'append '((a b c) nil (x y z) nil))
+ @result{} (a b c x y z)
address@hidden example
+
+An interesting example of using @code{apply} is found in the description
+of @address@hidden
address@hidden defun
address@hidden quotation
+
address@hidden 1200
+In the Texinfo source file, this example looks like this:
+
address@hidden
address@hidden
+@@defun apply function &rest arguments
+@@address@hidden@} calls @@address@hidden@} with
+@@address@hidden@}, just like @@address@hidden@} but with one
+difference: the last of @@address@hidden@} is a list of
+arguments to give to @@address@hidden@}, rather than a single
+argument. We also say that this list is @@address@hidden@}
+to the other arguments.
address@hidden group
+
address@hidden
+@@address@hidden@} returns the result of calling
+@@address@hidden@}. As with @@address@hidden@},
+@@address@hidden@} must either be a Lisp function or a
+primitive function; special forms and macros do not make
+sense in @@address@hidden@}.
address@hidden group
+
address@hidden
+@@example
+(setq f 'list)
+ @@address@hidden@} list
+(apply f 'x 'y 'z)
+@@address@hidden@} Wrong type argument: listp, z
+(apply '+ 1 2 '(3 4))
+ @@address@hidden@} 10
+(apply '+ '(1 2 3 4))
+ @@address@hidden@} 10
+
+(apply 'append '((a b c) nil (x y z) nil))
+ @@address@hidden@} (a b c x y z)
+@@end example
address@hidden group
+
address@hidden
+An interesting example of using @@address@hidden@} is found
+in the description of @@address@hidden@}.
+@@end defun
address@hidden group
address@hidden example
+
address@hidden
+In this manual, this function is listed in the Command and Variable
+Index under @address@hidden
+
+Ordinary variables and user options are described using a format like
+that for functions except that variables do not take arguments.
+
+
address@hidden Conditionals
address@hidden Conditionally Visible Text
address@hidden Conditionally visible text
address@hidden Text, conditionally visible
address@hidden Visibility of conditional text
address@hidden If text conditionally visible
+
+Sometimes it is good to use different text for different output formats.
+For example, you can use the @dfn{conditional commands} to specify
+different text for the printed manual and the Info output.
+
+Conditional commands may not be nested.
+
+The conditional commands comprise the following categories.
+
address@hidden @bullet
address@hidden Commands for HTML, Info, or @TeX{}.
address@hidden Commands for not HTML, Info, or @TeX{}.
address@hidden Raw @TeX{} or HTML commands.
address@hidden
+Substituting text for all formats, and testing if a flag is set or clear.
address@hidden itemize
+
address@hidden
+* Conditional Commands:: Specifying text for HTML, Info, or @TeX{}.
+* Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}.
+* Raw Formatter Commands:: Using raw @TeX{} or HTML commands.
+* set clear value:: Designating which text to format (for
+ all output formats); and how to set a
+ flag to a string that you can insert.
address@hidden menu
+
+
address@hidden Conditional Commands
address@hidden Conditional Commands
+
+Texinfo has a pair of commands for each output format, to allow
+conditional inclusion of text for a particular output format.
+
address@hidden ifinfo
address@hidden@@ifinfo} begins segments of text that should be ignored by @TeX{}
+when it typesets the printed manual. The segment of text appears only
+in the Info file and (for historical compatibility) the plain text
+output. The @code{@@ifinfo} command should appear on a line by itself;
+end the Info-only text with a line containing @code{@@end ifinfo} by
+itself.
+
address@hidden iftex
address@hidden ifhtml
address@hidden ifplaintext
+The @code{@@iftex} and @code{@@end iftex} commands are analogous to the
address@hidden@@ifinfo} and @code{@@end ifinfo} commands; they specify text that
+will appear in the printed manual but not in the Info file. Likewise
+for @code{@@ifhtml} and @code{@@end ifhtml}, which specify text to
+appear only in HTML output. And for @code{@@ifplaintext} and
address@hidden@@end ifplaintext}, which specify text to appear only in plain
+text output.
+
+For example,
+
address@hidden
+@@iftex
+This text will appear only in the printed manual.
+@@end iftex
+@@ifinfo
+However, this text will appear only in Info (or plain text).
+@@end ifinfo
+@@ifhtml
+And this text will only appear in HTML.
+@@end ifhtml
+@@ifplaintext
+Whereas this text will only appear in plain text.
+@@end ifplaintext
address@hidden example
+
address@hidden
+The preceding example produces the following line:
+However, this text will appear only in Info (or plain text).
+Whereas this text will only appear in plain text.
+
address@hidden
+Notice that you only see one of the input lines, depending on which
+version of the manual you are reading.
+
+
address@hidden Conditional Not Commands
address@hidden Conditional Not Commands
address@hidden ifnothtml
address@hidden ifnotinfo
address@hidden ifnotplaintext
address@hidden ifnottex
+
+You can specify text to be included in any output format @emph{other}
+than some given one with the @code{@@address@hidden commands:
address@hidden
+@@ifnothtml @dots{} @@end ifnothtml
+@@ifnotinfo @dots{} @@end ifnotinfo
+@@ifnotplaintext @dots{} @@end ifnotplaintext
+@@ifnottex @dots{} @@end ifnottex
address@hidden example
address@hidden
+(The @code{@@address@hidden command and the @code{@@end} command must
+appear on lines by themselves in your actual source file.)
+
+If the output file is @emph{not} being made for the given format, the
+region is included. Otherwise, it is ignored.
+
+With one exception (for historical compatibility): @code{@@ifnotinfo}
+text is omitted for both Info and plain text output, not just Info. To
+specify text which appears only in Info and not in plain text, use
address@hidden@@ifnotplaintext}, like this:
address@hidden
address@hidden example
+
+The regions delimited by these commands are ordinary Texinfo source as
+with @code{@@iftex}, not raw formatter source as with @code{@@tex}
+(@pxref{Raw Formatter Commands}).
+
+
address@hidden Raw Formatter Commands
address@hidden Raw Formatter Commands
address@hidden @TeX{} commands, using ordinary
address@hidden HTML commands, using ordinary
address@hidden Raw formatter commands
address@hidden Ordinary @TeX{} commands, using
address@hidden Ordinary HTML commands, using
address@hidden Commands using raw @TeX{}
address@hidden Commands using raw HTML
address@hidden plain @TeX{}
+
+Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, you
+can embed some raw @TeX{} commands. Info will ignore these commands
+since they are only in that part of the file which is seen by @TeX{}.
+You can write the @TeX{} commands as you would write them in a normal
address@hidden file, except that you must replace the @samp{\} used by @TeX{}
+with an @samp{@@}. For example, in the @code{@@titlepage} section of a
+Texinfo file, you can use the @TeX{} command @code{@@vskip} to format
+the copyright page. (The @code{@@titlepage} command causes Info to
+ignore the region automatically, as it does with the @code{@@iftex}
+command.)
+
+However, many features of plain @TeX{} will not work, as they are
+overridden by Texinfo features.
+
address@hidden tex
+You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{}
+commands, by delineating a region with the @code{@@tex} and @code{@@end
+tex} commands. (The @code{@@tex} command also causes Info to ignore the
+region, like the @code{@@iftex} command.) The sole exception is that the
address@hidden@@} character still introduces a command, so that @code{@@end tex}
+can be recognized properly.
+
address@hidden Mathematical expressions
+For example, here is a mathematical expression written in
+plain @TeX{}:
+
address@hidden
+@@tex
+$$ \chi^2 = address@hidden@}^N
+ \left (y_i - (a + b x_i)
+ \over \sigma_i\right)^2 $$
+@@end tex
address@hidden example
+
address@hidden
+The output of this example will appear only in a printed manual. If
+you are reading this in Info, you will not see the equation that appears
+in the printed manual.
+
address@hidden
+$$ \chi^2 = \sum_{i=1}^N
+ \left(y_i - (a + b x_i)
+ \over \sigma_i\right)^2 $$
address@hidden tex
+
address@hidden ifhtml
address@hidden html
+Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to delimit
+a region to be included in HTML output only, and @code{@@html @dots{}
+@@end html} for a region of raw HTML (again, except that @code{@@} is
+still the escape character, so the @code{@@end} command can be
+recognized.)
+
+
address@hidden set clear value
address@hidden @code{@@set}, @code{@@clear}, and @code{@@value}
+
+You can direct the Texinfo formatting commands to format or ignore parts
+of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset},
+and @code{@@ifclear} address@hidden
+
+Brief descriptions:
+
address@hidden @code
address@hidden @@set @var{flag} address@hidden
+Set the variable @var{flag}, to the optional @var{value} if specifed.
+
address@hidden @@clear @var{flag}
+Undefine the variable @var{flag}, whether or not it was previously defined.
+
address@hidden @@ifset @var{flag}
+If @var{flag} is set, text through the next @code{@@end ifset} command
+is formatted. If @var{flag} is clear, text through the following
address@hidden@@end ifset} command is ignored.
+
address@hidden @@ifclear @var{flag}
+If @var{flag} is set, text through the next @code{@@end ifclear} command
+is ignored. If @var{flag} is clear, text through the following
address@hidden@@end ifclear} command is formatted.
address@hidden table
+
address@hidden
+* set value:: Expand a flag variable to a string.
+* ifset ifclear:: Format a region if a flag is set.
+* value Example:: An easy way to update edition information.
address@hidden menu
+
+
address@hidden set value
address@hidden @code{@@set} and @code{@@value}
address@hidden value
+
+You use the @code{@@set} command to specify a value for a flag, which is
+later expanded by the @code{@@value} command.
+
+A @dfn{flag} is an identifier. In general, it is best to use only
+letters and numerals in a flag name, not @samp{-} or @samp{_}---they
+will work in some contexts, but not all, due to limitations in @TeX{}.
+
+The value is the remainder of the input line, and can contain anything.
+
+Write the @code{@@set} command like this:
+
address@hidden
+@@set foo This is a string.
address@hidden example
+
address@hidden
+This sets the value of the flag @code{foo} to ``This is a string.''.
+
+The Texinfo formatters then replace an @code{@@address@hidden@address@hidden
+command with the string to which @var{flag} is set. Thus, when
address@hidden is set as shown above, the Texinfo formatters convert this:
+
address@hidden
address@hidden
+@@address@hidden@}
address@hidden @r{to this:}
+This is a string.
address@hidden group
address@hidden example
+
+You can write an @code{@@value} command within a paragraph; but you
+must write an @code{@@set} command on a line of its own.
+
+If you write the @code{@@set} command like this:
+
address@hidden
+@@set foo
address@hidden example
+
address@hidden
+without specifying a string, the value of @code{foo} is the empty string.
+
+If you clear a previously set flag with @code{@@clear @var{flag}}, a
+subsequent @code{@@address@hidden@}} command will report an error.
+
+For example, if you set @code{foo} as follows:@refill
+
address@hidden
+@@set how-much very, very, very
address@hidden example
+
address@hidden
+then the formatters transform
+
address@hidden
address@hidden
+It is a @@address@hidden@} wet day.
address@hidden @r{into}
+It is a very, very, very wet day.
address@hidden group
address@hidden example
+
+If you write
+
address@hidden
+@@clear how-much
address@hidden example
+
address@hidden
+then the formatters transform
+
address@hidden
address@hidden
+It is a @@address@hidden@} wet day.
address@hidden @r{into}
+It is a @{No value for "how-much"@} wet day.
address@hidden group
address@hidden example
+
+
address@hidden ifset ifclear
address@hidden @code{@@ifset} and @code{@@ifclear}
+
address@hidden ifset
+When a @var{flag} is set, the Texinfo formatting commands format text
+between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end
+ifset} commands. When the @var{flag} is cleared, the Texinfo formatting
+commands do @emph{not} format the text. @code{@@ifclear} operates
+analogously.
+
+Write the conditionally formatted text between @code{@@ifset @var{flag}}
+and @code{@@end ifset} commands, like this:
+
address@hidden
address@hidden
+@@ifset @var{flag}
address@hidden
+@@end ifset
address@hidden group
address@hidden example
+
+For example, you can create one document that has two variants, such as
+a manual for a `large' and `small' model:
+
address@hidden shrubbery
address@hidden
+You can use this machine to dig up shrubs
+without hurting them.
+
+@@set large
+
+@@ifset large
+It can also dig up fully grown trees.
+@@end ifset
+
+Remember to replant promptly @dots{}
address@hidden example
+
address@hidden
+In the example, the formatting commands will format the text between
address@hidden@@ifset large} and @code{@@end ifset} because the @code{large}
+flag is set.
+
+When @var{flag} is cleared, the Texinfo formatting commands do
address@hidden format the text between @code{@@ifset @var{flag}} and
address@hidden@@end ifset}; that text is ignored and does not appear in either
+printed or Info output.
+
+For example, if you clear the flag of the preceding example by writing
+an @code{@@clear large} command after the @code{@@set large} command
+(but before the conditional text), then the Texinfo formatting commands
+ignore the text between the @code{@@ifset large} and @code{@@end ifset}
+commands. In the formatted output, that text does not appear; in both
+printed and Info output, you see only the lines that say, ``You can use
+this machine to dig up shrubs without hurting them. Remember to replant
+promptly @dots{}''.
+
address@hidden ifclear
+If a flag is cleared with an @code{@@clear @var{flag}} command, then
+the formatting commands format text between subsequent pairs of
address@hidden@@ifclear} and @code{@@end ifclear} commands. But if the flag
+is set with @code{@@set @var{flag}}, then the formatting commands do
address@hidden format text between an @code{@@ifclear} and an @code{@@end
+ifclear} command; rather, they ignore that text. An @code{@@ifclear}
+command looks like this:
+
address@hidden
+@@ifclear @var{flag}
address@hidden example
+
+
address@hidden value Example
address@hidden @code{@@value} Example
+
+You can use the @code{@@value} command to minimize the number of places
+you need to change when you record an update to a manual. @xref{GNU
+Sample Texts}, for an example of this same principle can work with
+Automake distributions, and full texts.
+
+Here is an example adapted from @ref{Top,, Overview, make, The GNU Make
+Manual}):
+
address@hidden
address@hidden
+Set the flags:
+
address@hidden
address@hidden
+@@set EDITION 0.35 Beta
+@@set VERSION 3.63 Beta
+@@set UPDATED 14 August 1992
+@@set UPDATE-MONTH August 1992
address@hidden group
address@hidden example
+
address@hidden
+Write text for the @code{@@copying} section (@pxref{copying}):
+
address@hidden
address@hidden
+@@copying
+This is Edition @@address@hidden@},
+last updated @@address@hidden@},
+of @@address@hidden GNU Make address@hidden,
+for @@address@hidden@}, version @@address@hidden@}.
+
+Copyright @dots{}
+
+Permission is granted @dots{}
+@@end copying
address@hidden group
address@hidden example
+
address@hidden
+Write text for the title page, for people reading the printed manual:
+
address@hidden
address@hidden
+@@titlepage
+@@title GNU Make
+@@subtitle A Program for Directing Recompilation
+@@subtitle Edition @@address@hidden@}, @dots{}
+@@subtitle @@address@hidden@}
+@@page
+@@insertcopying
address@hidden
+@@end titlepage
address@hidden group
address@hidden example
+
address@hidden
+(On a printed cover, a date listing the month and the year looks less
+fussy than a date listing the day as well as the month and year.)
+
address@hidden
+Write text for the Top node, for people reading the Info file:
+
address@hidden
address@hidden
+@@ifnottex
+@@node Top
+@@top Make
+
+@@insertcopying
address@hidden
+@@end ifnottex
address@hidden group
address@hidden example
+
+After you format the manual, the @code{@@value} constructs have been
+expanded, so the output contains text like this:
+
address@hidden
address@hidden
+This is Edition 0.35 Beta, last updated 14 August 1992,
+of `The GNU Make Manual', for `make', Version 3.63 Beta.
address@hidden group
address@hidden example
address@hidden enumerate
+
+When you update the manual, you change only the values of the flags; you
+do not need to edit the three sections.
+
+
address@hidden Internationalization
address@hidden Internationalization
+
address@hidden Internationalization
+Texinfo has some support for writing in languages other than English,
+although this area still needs considerable work.
+
+For a list of the various accented and special characters Texinfo
+supports, see @ref{Inserting Accents}.
+
address@hidden
+* documentlanguage:: Declaring the current language.
+* documentencoding:: Declaring the input encoding.
address@hidden menu
+
+
address@hidden documentlanguage
address@hidden @code{@@documentlanguage @var{cc}}: Set the Document Language
+
address@hidden documentlanguage
address@hidden Language, declaring
address@hidden Document language, declaring
+
+The @code{@@documentlanguage} command declares the current document
+language. Write it on a line by itself, with a two-letter ISO-639
+language code following (list is included below). If you have a
+multilingual document, the intent is to be able to use this command
+multiple times, to declare each language change. If the command is not
+used at all, the default is @code{en} for English.
+
address@hidden @address@hidden
+At present, this command is ignored in Info and HTML output. For
address@hidden, it causes the file @address@hidden to be read (if it
+exists). Such a file appropriately redefines the various English words
+used in @TeX{} output, such as `Chapter', `See', and so on.
+
address@hidden Hyphenation patterns, language-dependent
+It would be good if this command also changed @TeX{}'s ideas of the
+current hyphenation patterns (via the @TeX{} primitive
address@hidden), but this is unfortunately not currently implemented.
+
address@hidden ISO 639 codes
address@hidden Language codes
+Hereare the valid language codes, from ISO-639.
+
address@hidden @columnfractions .07 .26 .07 .26 .07 .26
address@hidden
address@hidden @tab Afar @tab
address@hidden @tab Abkhazian @tab
address@hidden @tab Afrikaans
address@hidden
address@hidden @tab Amharic @tab
address@hidden @tab Arabic @tab
address@hidden @tab Assamese
address@hidden
address@hidden @tab Aymara @tab
address@hidden @tab Azerbaijani @tab
address@hidden @tab Bashkir
address@hidden
address@hidden @tab Byelorussian @tab
address@hidden @tab Bulgarian @tab
address@hidden @tab Bihari
address@hidden
address@hidden @tab Bislama @tab
address@hidden @tab Bengali; Bangla @tab
address@hidden @tab Tibetan
address@hidden
address@hidden @tab Breton @tab
address@hidden @tab Catalan @tab
address@hidden @tab Corsican
address@hidden
address@hidden @tab Czech @tab
address@hidden @tab Welsh @tab
address@hidden @tab Danish
address@hidden
address@hidden @tab German @tab
address@hidden @tab Bhutani @tab
address@hidden @tab Greek
address@hidden
address@hidden @tab English @tab
address@hidden @tab Esperanto @tab
address@hidden @tab Spanish
address@hidden
address@hidden @tab Estonian @tab
address@hidden @tab Basque @tab
address@hidden @tab Persian
address@hidden
address@hidden @tab Finnish @tab
address@hidden @tab Fiji @tab
address@hidden @tab Faroese
address@hidden
address@hidden @tab French @tab
address@hidden @tab Frisian @tab
address@hidden @tab Irish
address@hidden
address@hidden @tab Scots Gaelic @tab
address@hidden @tab Galician @tab
address@hidden @tab Guarani
address@hidden
address@hidden @tab Gujarati @tab
address@hidden @tab Hausa @tab
address@hidden @tab Hebrew
address@hidden
address@hidden @tab Hindi @tab
address@hidden @tab Croatian @tab
address@hidden @tab Hungarian
address@hidden
address@hidden @tab Armenian @tab
address@hidden @tab Interlingua @tab
address@hidden @tab Indonesian
address@hidden
address@hidden @tab Interlingue @tab
address@hidden @tab Inupiak @tab
address@hidden @tab Icelandic
address@hidden
address@hidden @tab Italian @tab
address@hidden @tab Inuktitut @tab
address@hidden @tab Japanese
address@hidden
address@hidden @tab Javanese @tab
address@hidden @tab Georgian @tab
address@hidden @tab Kazakh
address@hidden
address@hidden @tab Greenlandic @tab
address@hidden @tab Cambodian @tab
address@hidden @tab Kannada
address@hidden
address@hidden @tab Kashmiri @tab
address@hidden @tab Korean @tab
address@hidden @tab Kurdish
address@hidden
address@hidden @tab Kirghiz @tab
address@hidden @tab Latin @tab
address@hidden @tab Lingala
address@hidden
address@hidden @tab Lithuanian @tab
address@hidden @tab Laothian @tab
address@hidden @tab Latvian, Lettish
address@hidden
address@hidden @tab Malagasy @tab
address@hidden @tab Maori @tab
address@hidden @tab Macedonian
address@hidden
address@hidden @tab Malayalam @tab
address@hidden @tab Mongolian @tab
address@hidden @tab Moldavian
address@hidden
address@hidden @tab Marathi @tab
address@hidden @tab Malay @tab
address@hidden @tab Maltese
address@hidden
address@hidden @tab Burmese @tab
address@hidden @tab Nauru @tab
address@hidden @tab Nepali
address@hidden
address@hidden @tab Dutch @tab
address@hidden @tab Norwegian @tab
address@hidden @tab Occitan
address@hidden
address@hidden @tab (Afan) Oromo @tab
address@hidden @tab Oriya @tab
address@hidden @tab Punjabi
address@hidden
address@hidden @tab Polish @tab
address@hidden @tab Pashto, Pushto @tab
address@hidden @tab Portuguese
address@hidden
address@hidden @tab Quechua @tab
address@hidden @tab Rhaeto-Romance @tab
address@hidden @tab Kirundi
address@hidden
address@hidden @tab Romanian @tab
address@hidden @tab Russian @tab
address@hidden @tab Kinyarwanda
address@hidden
address@hidden @tab Sanskrit @tab
address@hidden @tab Sindhi @tab
address@hidden @tab Sangro
address@hidden
address@hidden @tab Serbo-Croatian @tab
address@hidden @tab Sinhalese @tab
address@hidden @tab Slovak
address@hidden
address@hidden @tab Slovenian @tab
address@hidden @tab Samoan @tab
address@hidden @tab Shona
address@hidden
address@hidden @tab Somali @tab
address@hidden @tab Albanian @tab
address@hidden @tab Serbian
address@hidden
address@hidden @tab Siswati @tab
address@hidden @tab Sesotho @tab
address@hidden @tab Sundanese
address@hidden
address@hidden @tab Swedish @tab
address@hidden @tab Swahili @tab
address@hidden @tab Tamil
address@hidden
address@hidden @tab Telugu @tab
address@hidden @tab Tajik @tab
address@hidden @tab Thai
address@hidden
address@hidden @tab Tigrinya @tab
address@hidden @tab Turkmen @tab
address@hidden @tab Tagalog
address@hidden
address@hidden @tab Setswana @tab
address@hidden @tab Tonga @tab
address@hidden @tab Turkish
address@hidden
address@hidden @tab Tsonga @tab
address@hidden @tab Tatar @tab
address@hidden @tab Twi
address@hidden
address@hidden @tab Uighur @tab
address@hidden @tab Ukrainian @tab
address@hidden @tab Urdu
address@hidden
address@hidden @tab Uzbek @tab
address@hidden @tab Vietnamese @tab
address@hidden @tab Volapuk
address@hidden
address@hidden @tab Wolof @tab
address@hidden @tab Xhosa @tab
address@hidden @tab Yiddish
address@hidden
address@hidden @tab Yoruba @tab
address@hidden @tab Zhuang @tab
address@hidden @tab Chinese
address@hidden
address@hidden @tab Zulu
address@hidden multitable
+
+
address@hidden documentencoding
address@hidden @code{@@documentencoding @var{enc}}: Set Input Encoding
+
address@hidden documentencoding
address@hidden Encoding, declaring
address@hidden Input encoding, declaring
address@hidden Document input encoding
+
+The @code{@@documentencoding} command declares the input document
+encoding. Write it on a line by itself, with a valid encoding
+specification following, such as @samp{ISO-8859-1}.
+
address@hidden http-equiv, and charset
address@hidden meta HTML tag, and charset
+At present, this is used only in HTML output from @code{makeinfo}. If a
+document encoding @var{enc} is specified, it is used in a
address@hidden<meta>} tag included in the @samp{<head>} of the output:
+
address@hidden
+<meta http-equiv="Content-Type" content="text/html;
+ address@hidden">
address@hidden example
+
+
address@hidden Defining New Texinfo Commands
address@hidden Defining New Texinfo Commands
address@hidden Macros
address@hidden Defining new Texinfo commands
address@hidden New Texinfo commands, defining
address@hidden Texinfo commands, defining new
address@hidden User-defined Texinfo commands
+
+Texinfo provides several ways to define new commands:
+
address@hidden @bullet
address@hidden
+A Texinfo @dfn{macro} allows you to define a new Texinfo command as any
+sequence of text and/or existing commands (including other macros). The
+macro can have any number of @dfn{parameters}---text you supply each
+time you use the macro.
+
+Incidentally, these macros have nothing to do with the @code{@@defmac}
+command, which is for documenting macros in the subject of the manual
+(@pxref{Def Cmd Template}).
+
address@hidden
address@hidden@@alias} is a convenient way to define a new name for an existing
+command.
+
address@hidden
address@hidden@@definfoenclose} allows you to define new commands with
+customized output in the Info file.
+
address@hidden itemize
+
address@hidden
+* Defining Macros:: Defining and undefining new commands.
+* Invoking Macros:: Using a macro, once you've defined it.
+* Macro Details:: Beyond basic macro usage.
+* alias:: Command aliases.
+* definfoenclose:: Customized highlighting.
address@hidden menu
+
+
address@hidden Defining Macros
address@hidden Defining Macros
address@hidden Defining macros
address@hidden Macro definitions
+
address@hidden macro
+You use the Texinfo @code{@@macro} command to define a macro, like this:
+
address@hidden
+@@macro @address@hidden@var{param1}, @var{param2}, @address@hidden
address@hidden @dots{} address@hidden @dots{}
+@@end macro
address@hidden example
+
+The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to
+arguments supplied when the macro is subsequently used in the document
+(described in the next section).
+
+For a macro to work with @TeX{}, @var{macroname} must consist entirely
+of letters: no digits, hyphens, underscores, or other special characters.
+
+If a macro needs no parameters, you can define it either with an empty
+list (@samp{@@macro foo @address@hidden) or with no braces at all
(@samp{@@macro
+foo}).
+
address@hidden Body of a macro
address@hidden Mutually recursive macros
address@hidden Recursion, mutual
+The definition or @dfn{body} of the macro can contain most Texinfo
+commands, including previously-defined macros. Not-yet-defined macro
+invocations are not allowed; thus, it is not possible to have mutually
+recursive Texinfo macros. Also, a macro definition that defines another
+macro does not work in @TeX{} due to limitations in the design of
address@hidden@@macro}.
+
address@hidden Parameters to macros
+In the macro body, instances of a parameter name surrounded by
+backslashes, as in @address@hidden in the example above, are
+replaced by the corresponding argument from the macro invocation. You
+can use parameter names any number of times in the body, including zero.
+
address@hidden Backslash in macros
+To get a single @samp{\} in the macro expansion, use @samp{\\}. Any
+other use of @samp{\} in the body yields a warning.
+
address@hidden Spaces in macros
address@hidden Whitespace in macros
+The newlines after the @code{@@macro} line and before the @code{@@end
+macro} line are ignored, that is, not included in the macro body. All
+other whitespace is treated according to the usual Texinfo rules.
+
address@hidden Recursive macro invocations
address@hidden rmacro
+To allow a macro to be used recursively, that is, in an argument to a
+call to itself, you must define it with @samp{@@rmacro}, like this:
+
address@hidden
+@@rmacro rmac @address@hidden
+a\arg\b
+@@end rmacro
address@hidden
+@@address@hidden@@address@hidden@address@hidden
address@hidden example
+
+This produces the output `a1atextb2b'. With @samp{@@macro} instead of
address@hidden@@rmacro}, an error message is given.
+
address@hidden unmacro
address@hidden Macros, undefining
address@hidden Undefining macros
+You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}.
+It is not an error to undefine a macro that is already undefined.
+For example:
+
address@hidden
+@@unmacro foo
address@hidden example
+
+
address@hidden Invoking Macros
address@hidden Invoking Macros
address@hidden Invoking macros
address@hidden Expanding macros
address@hidden Running macros
address@hidden Macro invocation
+
+After a macro is defined (see the previous section), you can use
+(@dfn{invoke}) it in your document like this:
+
address@hidden
+@@@var{macroname} @address@hidden, @var{arg2}, @address@hidden
address@hidden example
+
address@hidden and the result will be just as if you typed the body of
address@hidden at that spot. For example:
+
address@hidden
+@@macro foo @{p, address@hidden
+Together: \p\ & \q\.
+@@end macro
+@@address@hidden, address@hidden
address@hidden example
+
address@hidden produces:
+
address@hidden
+Together: a & b.
address@hidden display
+
address@hidden Backslash, and macros
+Thus, the arguments and parameters are separated by commas and delimited
+by braces; any whitespace after (but not before) a comma is ignored.
+The braces are required in the invocation (but not the definition), even
+when the macro takes no arguments, consistent with all other Texinfo
+commands. For example:
+
address@hidden
+@@macro argless @address@hidden
+No arguments here.
+@@end macro
+@@address@hidden@}
address@hidden example
+
address@hidden produces:
+
address@hidden
+No arguments here.
address@hidden display
+
address@hidden Comma, in macro arguments
address@hidden Braces, in macro arguments
+To insert a comma, brace, or backslash in an argument, prepend a
+backslash, as in
+
address@hidden
+@@@var{macname} @address@hidden@}\,@}
address@hidden example
+
address@hidden
+which will pass the (almost certainly error-producing) argument
address@hidden@address@hidden,} to @var{macname}. However, commas in
parameters, even
+if escaped by a backslash, might cause trouble in @TeX{}.
+
+If the macro is defined to take a single argument, and is invoked
+without any braces, the entire rest of the line after the macro name is
+supplied as the argument. For example:
+
address@hidden
+@@macro bar @address@hidden
+Twice: \p\ & \p\.
+@@end macro
+@@bar aah
address@hidden example
+
address@hidden produces:
+
address@hidden Sorry for cheating, but let's not require macros to process the
manual.
address@hidden
+Twice: aah & aah.
address@hidden display
+
+If the macro is defined to take a single argument, and is invoked with
+braces, the braced text is passed as the argument, regardless of
+commas. For example:
+
address@hidden
+@@macro bar @address@hidden
+Twice: \p\ & \p\.
+@@end macro
+@@address@hidden,address@hidden
address@hidden example
+
address@hidden produces:
+
address@hidden
+Twice: a,b & a,b.
address@hidden display
+
+
address@hidden Macro Details
address@hidden Macro Details
address@hidden Macro details
address@hidden Details of macro usage
+
+Due to unavoidable disparities in the @TeX{} and @command{makeinfo}
+implementations, Texinfo macros have the following limitations.
+
address@hidden @bullet
address@hidden
+All macros are expanded inside at least one @TeX{} group. This means
+that @code{@@set} and other such commands will have no effect inside a
+macro.
+
address@hidden
+Macros containing a command which must be on a line by itself, such as a
+conditional, cannot be invoked in the middle of a line.
+
address@hidden
+Commas in macro arguments, even if escaped by a backslash, don't
+always work.
+
address@hidden
+The @TeX{} implementation cannot construct macros that define macros in
+the natural way. To do this, you must use conditionals and raw @TeX{}.
+For example:
+
address@hidden
+@@ifnottex
+@@macro ctor @{name, address@hidden
+@@macro \name\
+something involving \arg\ somehow
+@@end macro
+@@end macro
+@@end ifnottex
+@@tex
address@hidden,@}
+\gdef\ctorx#1,#2,@address@hidden involving #2 address@hidden@}
+@@end tex
address@hidden example
+
address@hidden
+It is best to avoid comments inside macro definitions.
+
address@hidden itemize
+
+If some macro feature causes errors when producing the printed version
+of a manual, try expanding the macros with @command{makeinfo} by
+invoking @command{texi2dvi} with the @samp{-e} option; see @ref{Format
+with texi2dvi}.
+
address@hidden alias
address@hidden @samp{@@alias @address@hidden
address@hidden Aliases, command
address@hidden Command aliases
address@hidden alias
+
+The @samp{@@alias} command defines a new command to be just like an
+existing one. This is useful for defining additional markup names, thus
+preserving semantic information in the input even though the output
+result may be the same.
+
+Write the @samp{@@alias} command on a line by itself, followed by the
+new command name, an equals sign, and the existing command name.
+Whitespace around the equals sign is ignored. Thus:
address@hidden
+@@alias @var{new} = @var{existing}
address@hidden example
+
+For example, if your document contains citations for both books and
+some other media (movies, for example), you might like to define a
+macro @code{@@address@hidden@}} that does the same thing as an ordinary
address@hidden@@address@hidden@}} but conveys the extra semantic information as
well.
+You'd do this as follows:
+
address@hidden
+@@alias moviecite = cite
address@hidden example
+
+Macros do not always have the same effect due to vagaries of argument
+parsing. Also, aliases are much simpler to define than macros. So the
+command is not redundant. (It was also heavily used in the Jargon File!)
+
+Aliases must not be recursive, directly or indirectly.
+
address@hidden definfoenclose
address@hidden @samp{definfoenclose}: Customized Highlighting
address@hidden Highlighting, customized
address@hidden Customized highlighting
address@hidden definfoenclose
+
+A @code{@@definfoenclose} command may be used to define a highlighting
+command for Info, but not for @TeX{}. A command defined using
address@hidden@@definfoenclose} marks text by enclosing it in strings that
+precede and follow the text. You can use this to get closer control of
+your Info output.
+
+Presumably, if you define a command with @code{@@definfoenclose} for Info,
+you will create a corresponding command for @TeX{}, either in
address@hidden, @file{texinfo.cnf}, or within an @samp{@@iftex} in
+your document.
+
+Write a @code{@@definfoenclose} command on a line and follow it with
+three arguments separated by commas. The first argument to
address@hidden@@definfoenclose} is the @@-command name (without the @code{@@});
+the second argument is the Info start delimiter string; and the third
+argument is the Info end delimiter string. The latter two arguments
+enclose the highlighted text in the Info file. A delimiter string may
+contain spaces. Neither the start nor end delimiter is required. If
+you do not want a start delimiter but do want an end delimiter, you must
+follow the command name with two commas in a row; otherwise, the Info
+formatting commands will naturally misinterpret the end delimiter string
+you intended as the start delimiter string.
+
+If you do a @code{@@definfoenclose} on the name of a pre-defined macro
+(such as @code{@@emph}, @code{@@strong}, @code{@@t}, or @code{@@i}), the
+enclosure definition will override the built-in definition.
+
+An enclosure command defined this way takes one argument in braces; this
+is intended for new markup commands (@pxref{Marking Text}).
+
address@hidden phoo
+For example, you can write:
+
address@hidden
+@@definfoenclose phoo,//,\\
address@hidden example
+
address@hidden
+near the beginning of a Texinfo file to define @code{@@phoo} as an Info
+formatting command that inserts `//' before and `\\' after the argument
+to @code{@@phoo}. You can then write @code{@@address@hidden@}} wherever you
+want `//bar\\' highlighted in Info.
+
+Also, for @TeX{} formatting, you could write
+
address@hidden
+@@iftex
+@@global@@let@@phoo=@@i
+@@end iftex
address@hidden example
+
address@hidden
+to define @code{@@phoo} as a command that causes @TeX{} to typeset the
+argument to @code{@@phoo} in italics.
+
+Each definition applies to its own formatter: one for @TeX{}, the other
+for @code{texinfo-format-buffer} or @code{texinfo-format-region}. The
address@hidden@@definfoenclose} command need not be within @samp{@@ifinfo}, but
+the raw @TeX{} commands do need to be in @samp{@@iftex}.
+
address@hidden headword
+Here is another example: write
+
address@hidden
+@@definfoenclose headword, , :
address@hidden example
+
address@hidden
+near the beginning of the file, to define @code{@@headword} as an Info
+formatting command that inserts nothing before and a colon after the
+argument to @code{@@headword}.
+
address@hidden@@definfoenclose} definitions must not be recursive, directly or
+indirectly.
+
+
address@hidden Hardcopy
address@hidden Formatting and Printing Hardcopy
address@hidden Format and print hardcopy
address@hidden Printing hardcopy
address@hidden Hardcopy, printing it
address@hidden Making a printed manual
address@hidden Sorting indices
address@hidden Indices, sorting
address@hidden @TeX{} index sorting
address@hidden texindex
+
+There are three major shell commands for making a printed manual from a
+Texinfo file: one for converting the Texinfo file into a file that will be
+printed, a second for sorting indices, and a third for printing the
+formatted document. When you use the shell commands, you can either
+work directly in the operating system shell or work within a shell
+inside GNU Emacs.
+
+If you are using GNU Emacs, you can use commands provided by Texinfo
+mode instead of shell commands. In addition to the three commands to
+format a file, sort the indices, and print the result, Texinfo mode
+offers key bindings for commands to recenter the output buffer, show the
+print queue, and delete a job from the print queue.
+
address@hidden
+* Use TeX:: Use @TeX{} to format for hardcopy.
+* Format with tex/texindex:: How to format with explicit shell commands.
+* Format with texi2dvi:: A simpler way to format.
+* Print with 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.
+* smallbook:: How to print small format books and manuals.
+* A4 Paper:: How to print on A4 or A5 paper.
+* 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.
address@hidden menu
+
address@hidden Use TeX
address@hidden Use @TeX{}
+
+The typesetting program called @TeX{} is used for formatting a Texinfo
+file. @TeX{} is a very powerful typesetting program and, if used correctly,
+does an exceptionally good job. (@xref{Obtaining TeX, , How to Obtain
address@hidden, for information on how to obtain @TeX{}.)
+
+The standalone @code{makeinfo} program and Emacs functions
address@hidden and @code{texinfo-format-buffer} commands
+read the very same @@-commands in the Texinfo file as does @TeX{}, but
+process them differently to make an Info file (@pxref{Creating an Info
+File}).
+
+
address@hidden Format with tex/texindex
address@hidden Format with @code{tex} and @code{texindex}
address@hidden Shell formatting with @code{tex} and @code{texindex}
address@hidden Formatting with @code{tex} and @code{texindex}
address@hidden DVI file
+
+Format the Texinfo file with the shell command @code{tex} followed by
+the name of the Texinfo file. For example:
+
address@hidden
+tex foo.texi
address@hidden example
+
address@hidden @TeX{} will produce a @dfn{DVI file} as well as several auxiliary
+files containing information for indices, cross references, etc. The
+DVI file (for @dfn{DeVice Independent} file) can be printed on virtually
+any device (see the following sections).
+
address@hidden texindex
+The @code{tex} formatting command itself does not sort the indices; it
+writes an output file of unsorted index data. (The @code{texi2dvi}
+command automatically generates indices; @pxref{Format with texi2dvi,,
+Format with @code{texi2dvi}}.) To generate a printed index after
+running the @code{tex} command, you first need a sorted index to work
+from. The @code{texindex} command sorts indices. (The source file
address@hidden comes as part of the standard Texinfo distribution,
+among other places.)@refill
+
address@hidden Names of index files
address@hidden Index file names
+The @code{tex} formatting command outputs unsorted index files under
+names that obey a standard convention: the name of your main input file
+with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c,
+Web2c}) extension removed, followed by the two letter names of indices.
+For example, the raw index output files for the input file
address@hidden would be @file{foo.cp}, @file{foo.vr}, @file{foo.fn},
address@hidden, @file{foo.pg} and @file{foo.ky}. Those are exactly the
+arguments to give to @code{texindex}.
+
address@hidden 1000
address@hidden Wildcards
address@hidden Globbing
+Instead of specifying all the unsorted index file names explicitly, you
+can use @samp{??} as shell wildcards and give the command in this
+form:
+
address@hidden
+texindex foo.??
address@hidden example
+
address@hidden
+This command will run @code{texindex} on all the unsorted index files,
+including any that you have defined yourself using @code{@@defindex}
+or @code{@@defcodeindex}. (You may execute @samp{texindex foo.??}
+even if there are similarly named files with two letter extensions
+that are not index files, such as @samp{foo.el}. The @code{texindex}
+command reports but otherwise ignores such files.)
+
+For each file specified, @code{texindex} generates a sorted index file
+whose name is made by appending @samp{s} to the input file name. The
address@hidden@@printindex} command looks for a file with that name
+(@pxref{Printing Indices & Menus}). @code{texindex} does not alter the
+raw index output file.
+
+After you have sorted the indices, you need to rerun the @code{tex}
+formatting command on the Texinfo file. This regenerates the DVI file,
+this time with up-to-date index entries.
+
+Finally, you may need to run @code{tex} one more time, to get the page
+numbers in the cross-references correct.
+
+To summarize, this is a five step process:
+
address@hidden
address@hidden
+Run @code{tex} on your Texinfo file. This generates a DVI file (with
+undefined cross-references and no indices), and the raw index files
+(with two letter extensions).
+
address@hidden
+Run @code{texindex} on the raw index files. This creates the
+corresponding sorted index files (with three letter extensions).
+
address@hidden
+Run @code{tex} again on your Texinfo file. This regenerates the DVI
+file, this time with indices and defined cross-references, but with page
+numbers for the cross-references from last time, generally incorrect.
+
address@hidden
+Sort the indices again, with @code{texindex}.
+
address@hidden
+Run @code{tex} one last time. This time the correct page numbers are
+written for the cross-references.
address@hidden enumerate
+
address@hidden texi2dvi
+Alternatively, it's a one-step process: run @code{texi2dvi}
+(@pxref{Format with texi2dvi}).
+
+You need not run @code{texindex} each time after you run @code{tex}. If
+you do not, on the next run, the @code{tex} formatting command will use
+whatever sorted index files happen to exist from the previous use of
address@hidden This is usually ok while you are debugging.
+
address@hidden Auxiliary files, avoiding
address@hidden novalidate
address@hidden Pointer validation, suppressing
address@hidden Chapters, formatting one at a time
+Sometimes you may wish to print a document while you know it is
+incomplete, or to print just one chapter of a document. In that case,
+the usual auxiliary files that @TeX{} creates and warnings @TeX{} gives
+when cross-references are not satisfied are just nuisances. You can
+avoid them with the @code{@@novalidate} command, which you must give
address@hidden the @code{@@setfilename} command
+(@pxref{setfilename,,@code{@@setfilename}}). Thus, the beginning of
+your file would look approximately like this:
+
address@hidden
+\input texinfo
+@@novalidate
+@@setfilename myfile.info
address@hidden
address@hidden example
+
address@hidden @code{@@novalidate} also turns off validation in
address@hidden, just like its @code{--no-validate} option
+(@pxref{Pointer Validation}).
+
+
address@hidden Format with texi2dvi
address@hidden Format with @code{texi2dvi}
address@hidden texi2dvi @r{(shell script)}
+
+The @code{texi2dvi} command automatically runs both @code{tex} and
address@hidden as many times as necessary to produce a DVI file with
+sorted indices and all cross-references resolved. It simplifies the
address@hidden@address@hidden@code{tex} sequence
+described in the previous section.
+
+To run @code{texi2dvi} on an input file @file{foo.texi}, do this (where
address@hidden } is your shell prompt):
+
address@hidden
+prompt$ @kbd{texi2dvi foo.texi}
address@hidden example
+
+As shown in this example, the input filenames to @code{texi2dvi} must
+include any extension (@samp{.texi}, @samp{.texinfo}, etc.). Under
+MS-DOS and perhaps in other circumstances, you may need to run @samp{sh
+texi2dvi foo.texi} instead of relying on the operating system to invoke
+the shell on the @samp{texi2dvi} script.
+
+Perhaps the most useful option to @code{texi2dvi} is
address@hidden@var{cmd}}. This inserts @var{cmd} on a line by itself
+after the @code{@@setfilename} in a temporary copy of the input file
+before running @TeX{}. With this, you can specify different printing
+formats, such as @code{@@smallbook} (@pxref{smallbook}),
address@hidden@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes}
+(@pxref{pagesizes}), without actually changing the document source.
+(You can also do this on a site-wide basis with @file{texinfo.cnf};
address@hidden for TeX,,Preparing for @TeX{}}).
+
+For a list of other options, run @samp{texi2dvi --help}.
+
+
address@hidden Print with lpr
address@hidden Shell Print Using @code{lpr -d}
address@hidden lpr @r{(DVI print command)}
+
+The precise command to print a DVI file depends on your system
+installation. Two common ones are @samp{dvips foo.dvi -o} and @samp{lpr
+-d foo.dvi}.
+
+For example, the following commands will (perhaps) suffice to sort the
+indices, format, and print the @cite{Bison Manual}:
+
address@hidden
address@hidden
+tex bison.texinfo
+texindex bison.??
+tex bison.texinfo
+lpr -d bison.dvi
address@hidden group
address@hidden example
+
address@hidden
+(Remember that the shell commands may be different at your site; but
+these are commonly used versions.)
+
+Using the @code{texi2dvi} shell script (see the previous section):
+
address@hidden
address@hidden
+texi2dvi bison.texinfo
+lpr -d bison.dvi
+# or perhaps dvips bison.dvi -o
address@hidden group
address@hidden example
+
address@hidden Shell printing, on MS-DOS/MS-Windows
address@hidden Printing DVI files, on MS-DOS/MS-Windows
address@hidden address@hidden, replacements on MS-DOS/MS-Windows}
address@hidden is a standard program on Unix systems, but it is usually
+absent on MS-DOS/MS-Windows. Some network packages come with a
+program named @code{lpr}, but these are usually limited to sending files
+to a print server over the network, and generally don't support the
address@hidden option. If you are unfortunate enough to work on one of these
+systems, you have several alternative ways of printing DVI files:
+
address@hidden @bullet{}
address@hidden Find and install a Unix-like @code{lpr} program, or its clone.
+If you can do that, you will be able to print DVI files just like
+described above.
+
address@hidden Send the DVI files to a network printer queue for DVI files.
+Some network printers have special queues for printing DVI files. You
+should be able to set up your network software to send files to that
+queue. In some cases, the version of @code{lpr} which comes with your
+network software will have a special option to send a file to specific
+queues, like this:
+
address@hidden
+lpr -Qdvi -hprint.server.domain bison.dvi
address@hidden example
+
address@hidden Convert the DVI file to a Postscript or PCL file and send it to
your
+local printer. @xref{dvips invocation,,, dvips, Dvips}, and the man
+pages for @code{dvilj}, for detailed description of these tools. Once
+the DVI file is converted to the format your local printer understands
+directly, just send it to the appropriate port, usually @samp{PRN}.
address@hidden itemize
+
+
address@hidden Within Emacs
address@hidden From an Emacs Shell
address@hidden Print, format from Emacs shell
address@hidden Format, print from Emacs shell
address@hidden Shell, format, print from
address@hidden Emacs shell, format, print from
address@hidden GNU Emacs shell, format, print from
+
+You can give formatting and printing commands from a shell within GNU
+Emacs. To create a shell within Emacs, type @kbd{M-x shell}. In this
+shell, you can format and print the document. @xref{Hardcopy, , Format
+and Print Hardcopy}, for details.
+
+You can switch to and from the shell buffer while @code{tex} is
+running and do other editing. If you are formatting a long document
+on a slow machine, this can be very address@hidden
+
+You can also use @code{texi2dvi} from an Emacs shell. For example,
+here is how to use @code{texi2dvi} to format and print @cite{Using and
+Porting GNU CC} from a shell within Emacs:
+
address@hidden
address@hidden
+texi2dvi gcc.texinfo
+lpr -d gcc.dvi
address@hidden group
address@hidden example
+
address@hidden Mode Printing}, for more information about formatting
+and printing in Texinfo address@hidden
+
+
address@hidden Texinfo Mode Printing, Compile-Command, Within Emacs, Hardcopy
address@hidden Formatting and Printing in Texinfo Mode
address@hidden Region printing in Texinfo mode
address@hidden Format and print in Texinfo mode
address@hidden Print and format in Texinfo mode
+
+Texinfo mode provides several predefined key commands for @TeX{}
+formatting and printing. These include commands for sorting indices,
+looking at the printer queue, killing the formatting job, and
+recentering the display of the buffer in which the operations
address@hidden
+
address@hidden @kbd
address@hidden C-c C-t C-b
address@hidden M-x texinfo-tex-buffer
+Run @code{texi2dvi} on the current address@hidden
+
address@hidden C-c C-t C-r
address@hidden M-x texinfo-tex-region
+Run @TeX{} on the current address@hidden
+
address@hidden C-c C-t C-i
address@hidden M-x texinfo-texindex
+Sort the indices of a Texinfo file formatted with
address@hidden@refill
+
address@hidden C-c C-t C-p
address@hidden M-x texinfo-tex-print
+Print a DVI file that was made with @code{texinfo-tex-region} or
address@hidden@refill
+
address@hidden C-c C-t C-q
address@hidden M-x tex-show-print-queue
+Show the print address@hidden
+
address@hidden C-c C-t C-d
address@hidden M-x texinfo-delete-from-print-queue
+Delete a job from the print queue; you will be prompted for the job
+number shown by a preceding @kbd{C-c C-t C-q} command
+(@code{texinfo-show-tex-print-queue})address@hidden
+
address@hidden C-c C-t C-k
address@hidden M-x tex-kill-job
+Kill the currently running @TeX{} job started by either
address@hidden or @code{texinfo-tex-buffer}, or any other
+process running in the Texinfo shell address@hidden
+
address@hidden C-c C-t C-x
address@hidden M-x texinfo-quit-job
+Quit a @TeX{} formatting job that has stopped because of an error by
+sending an @key{x} to it. When you do this, @TeX{} preserves a record
+of what it did in a @file{.log} address@hidden
+
address@hidden C-c C-t C-l
address@hidden M-x tex-recenter-output-buffer
+Redisplay the shell buffer in which the @TeX{} printing and formatting
+commands are run to show its most recent address@hidden
address@hidden table
+
address@hidden 1000
+Thus, the usual sequence of commands for formatting a buffer is as
+follows (with comments to the right):@refill
+
address@hidden
address@hidden
+C-c C-t C-b @r{Run @code{texi2dvi} on the buffer.}
+C-c C-t C-p @r{Print the DVI file.}
+C-c C-t C-q @r{Display the printer queue.}
address@hidden group
address@hidden example
+
+The Texinfo mode @TeX{} formatting commands start a subshell in Emacs
+called the @file{*tex-shell*}. The @code{texinfo-tex-command},
address@hidden, and @code{tex-dvi-print-command}
+commands are all run in this shell.
+
+You can watch the commands operate in the @samp{*tex-shell*} buffer,
+and you can switch to and from and use the @samp{*tex-shell*} buffer
+as you would any other shell address@hidden
+
address@hidden 1500
+The formatting and print commands depend on the values of several variables.
+The default values are:@refill
+
address@hidden
address@hidden
+ @r{Variable} @r{Default value}
+
+texinfo-texi2dvi-command "texi2dvi"
+texinfo-tex-command "tex"
+texinfo-texindex-command "texindex"
+texinfo-delete-from-print-queue-command "lprm"
+texinfo-tex-trailer "@@bye"
+tex-start-of-header "%**start"
+tex-end-of-header "%**end"
+tex-dvi-print-command "lpr -d"
+tex-show-queue-command "lpq"
address@hidden group
address@hidden example
+
+You can change the values of these variables with the @kbd{M-x
+edit-options} command (@pxref{Edit Options, , Editing Variable Values,
+emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command
+(@pxref{Examining, , Examining and Setting Variables, emacs, The GNU
+Emacs Manual}), or with your @file{.emacs} initialization file
+(@pxref{Init File, , , emacs, The GNU Emacs Manual})address@hidden
+
address@hidden Customize Emacs package (@t{Development/Docs/Texinfo})
+Beginning with version 20, GNU Emacs offers a user-friendly interface,
+called @dfn{Customize}, for changing values of user-definable variables.
address@hidden Customization, , Easy Customization Interface, emacs, The GNU
+Emacs Manual}, for more details about this. The Texinfo variables can
+be found in the @samp{Development/Docs/Texinfo} group, once you invoke
+the @kbd{M-x customize} command.
+
+
address@hidden Compile-Command
address@hidden Using the Local Variables List
address@hidden Local variables
address@hidden Compile command for formatting
address@hidden Format with the compile command
+
+Yet another way to apply the @TeX{} formatting command to a Texinfo file
+is to put that command in a @dfn{local variables list} at the end of the
+Texinfo file. You can then specify the @code{tex} or @code{texi2dvi}
+commands as a @code{compile-command} and have Emacs run it by typing
address@hidden compile}. This creates a special shell called the
address@hidden buffer in which Emacs runs the compile command.
+For example, at the end of the @file{gdb.texinfo} file, after the
address@hidden@@bye}, you could put the following:@refill
+
address@hidden
address@hidden
+Local Variables:
+compile-command: "texi2dvi gdb.texinfo"
+End:
address@hidden group
address@hidden example
+
address@hidden
+This technique is most often used by programmers who also compile programs
+this way; see @ref{Compilation, , , emacs, The GNU Emacs address@hidden
+
+
address@hidden Requirements Summary
address@hidden @TeX{} Formatting Requirements Summary
address@hidden Requirements for formatting
address@hidden Minimal requirements for formatting
address@hidden Formatting requirements
+
+Every Texinfo file that is to be input to @TeX{} must begin with a
address@hidden command and must contain an @code{@@setfilename} command:
+
address@hidden
+\input texinfo
+@@setfilename @address@hidden
address@hidden example
+
address@hidden
+The first command instructs @TeX{} to load the macros it needs to
+process a Texinfo file and the second command opens auxiliary files.
+
+Every Texinfo file must end with a line that terminates @TeX{}'s
+processing and forces out unfinished pages:
+
address@hidden
+@@bye
address@hidden example
+
+Strictly speaking, these lines are all a Texinfo file needs to be
+processed successfully by @TeX{}.
+
+Usually, however, the beginning includes an @code{@@settitle} command to
+define the title of the printed manual, an @code{@@setchapternewpage}
+command, a title page, a copyright page, and permissions. Besides an
address@hidden@@bye}, the end of a file usually includes indices and a table of
+contents. (And of course most manuals contain a body of text as well.)
+
+For more information, see:
address@hidden @bullet
address@hidden @ref{settitle, , @code{@@settitle}}
address@hidden @ref{setchapternewpage, , @code{@@setchapternewpage}}
address@hidden @ref{Headings, ,Page Headings}
address@hidden @ref{Titlepage & Copyright Page}
address@hidden @ref{Printing Indices & Menus}
address@hidden @ref{Contents}
address@hidden itemize
+
+
address@hidden Preparing for TeX
address@hidden Preparing for @TeX{}
address@hidden Preparing for @TeX{}
address@hidden @TeX{} input initialization
address@hidden @code{TEXINPUTS} environment variable
address@hidden TEXINPUTS
address@hidden @b{.profile} initialization file
address@hidden @b{.cshrc} initialization file
address@hidden Initialization file for @TeX{} input
+
address@hidden needs to know where to find the @file{texinfo.tex} file that the
address@hidden texinfo} command on the first line reads. The
address@hidden file tells @TeX{} how to handle @@-commands; it is
+included in all standard GNU distributions.
+
address@hidden address@hidden, installing}
+
+Usually, the installer has put the @file{texinfo.tex} file in the
+default directory that contains @TeX{} macros when GNU Texinfo, Emacs or
+other GNU software is installed. In this case, @TeX{} will find the
+file and you do not need to do anything special. If this has not been
+done, you can put @file{texinfo.tex} in the current directory when you
+run @TeX{}, and @TeX{} will find it there.
+
address@hidden address@hidden, installing}
+Also, you should install @file{epsf.tex}, if it is not already installed
+from another distribution. More details are at the end of the description
+of the @code{@@image} command (@pxref{Images}).
+
address@hidden address@hidden, installing}
+Likewise for @file{pdfcolor.tex}, if it is not already installed and you
+use pdftex.
+
address@hidden texinfo.cnf @r{installation}
address@hidden Customizing of @TeX{} for Texinfo
address@hidden Site-wide Texinfo configuration file
+Optionally, you may create an additional @file{texinfo.cnf}, and install
+it as well. This file is read by @TeX{} when the @code{@@setfilename}
+command is executed (@pxref{setfilename,, @code{@@setfilename}}). You can put
any
+commands you like there, according to local site-wide conventions. They
+will be read by @TeX{} when processing any Texinfo document. For
+example, if @file{texinfo.cnf} contains the line @samp{@@afourpaper}
+(@pxref{A4 Paper}), then all Texinfo documents will be processed with
+that page size in effect. If you have nothing to put in
address@hidden, you do not need to create it.
+
address@hidden TEXINPUTS
+If neither of the above locations for these system files suffice for
+you, you can specify the directories explicitly. For
address@hidden, you can do this by writing the complete path for the
+file after the @code{\input} command. Another way, that works for both
address@hidden and @file{texinfo.cnf} (and any other file @TeX{}
+might read), is to set the @code{TEXINPUTS} environment variable in your
address@hidden or @file{.profile} file.
+
+Which you use of @file{.cshrc} or @file{.profile} depends on
+whether you use a Bourne shell-compatible (@code{sh}, @code{bash},
address@hidden, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh})
+command interpreter. The latter read the @file{.cshrc} file for
+initialization information, and the former read @file{.profile}.
+
+In a @file{.cshrc} file, you could use the following @code{csh} command
+sequence:
+
address@hidden
+setenv TEXINPUTS .:/home/me/mylib:/usr/lib/tex/macros
address@hidden example
+
address@hidden 1000
+In a @file{.profile} file, you could use the following @code{sh} command
+sequence:
+
address@hidden
address@hidden
+TEXINPUTS=.:/home/me/mylib:/usr/lib/tex/macros
+export TEXINPUTS
address@hidden group
address@hidden example
+
+On MS-DOS/MS-Windows, you would say it like address@hidden the use
+of the @samp{;} character, instead of @samp{:}, as directory separator
+on these systems.}:
+
address@hidden
address@hidden
+set TEXINPUTS=.;d:/home/me/mylib;c:/usr/lib/tex/macros
address@hidden group
address@hidden example
+
address@hidden
+It is customary for DOS/Windows users to put such commands in the
address@hidden file, or in the Windows address@hidden
+
address@hidden
+These settings would cause @TeX{} to look for @file{\input} file first
+in the current directory, indicated by the @samp{.}, then in a
+hypothetical user's @file{me/mylib} directory, and finally in a system
+directory @file{/usr/lib/tex/macros}.
+
address@hidden Dumping a .fmt file
address@hidden Format file, dumping
+Finally, you may wish to dump a @file{.fmt} file (@pxref{Memory dumps,,,
+web2c, Web2c}) so that @TeX{} can load Texinfo faster. (The
+disadvantage is that then updating @file{texinfo.tex} requires
+redumping.) You can do this by running this command, assuming
address@hidden is findable by @TeX{}:
+
address@hidden
+initex texinfo @@dump
address@hidden example
+
+(@code{dump} is a @TeX{} primitive.) Then, move @file{texinfo.fmt} to
+wherever your @code{.fmt} files are found; typically, this will be in the
+subdirectory @file{web2c} of your @TeX{} installation.
+
+
address@hidden Overfull hboxes
address@hidden Overfull ``hboxes''
address@hidden Overfull @samp{hboxes}
address@hidden @samp{hboxes}, overfull
address@hidden Final output
+
address@hidden is sometimes unable to typeset a line without extending it into
+the right margin. This can occur when @TeX{} comes upon what it
+interprets as a long word that it cannot hyphenate, such as an
+electronic mail network address or a very long title. When this
+happens, @TeX{} prints an error message like this:
+
address@hidden
+Overfull @@hbox (20.76302pt too wide)
address@hidden example
+
address@hidden hbox
address@hidden
+(In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''.
address@hidden@@hbox} is a @TeX{} primitive not needed in the Texinfo language.)
+
address@hidden also provides the line number in the Texinfo source file and
+the text of the offending line, which is marked at all the places that
address@hidden considered hyphenation.
address@hidden with TeX, , Catching Errors with @TeX{} Formatting},
+for more information about typesetting errors.
+
+If the Texinfo file has an overfull hbox, you can rewrite the sentence
+so the overfull hbox does not occur, or you can decide to leave it. A
+small excursion into the right margin often does not matter and may not
+even be noticeable.
+
+If you have many overfull boxes and/or an antipathy to rewriting, you
+can coerce @TeX{} into greatly increasing the allowable interword
+spacing, thus (if you're lucky) avoiding many of the bad line breaks,
+like this:
+
address@hidden \emergencystretch
address@hidden
+@@tex
+\global\emergencystretch = .9\hsize
+@@end tex
address@hidden example
+
address@hidden
+(You should adjust the fraction as needed.) This huge value for
address@hidden cannot be the default, since then the typeset
+output would generally be of noticeably lower quality; the default
+is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension
+containing the current line width.
+
address@hidden Black rectangle in hardcopy
address@hidden Rectangle, black in hardcopy
address@hidden Box, ugly black in hardcopy
address@hidden Ugly black rectangles in hardcopy
+For what overfull boxes you have, however, @TeX{} will print a large,
+ugly, black rectangle beside the line that contains the overfull hbox
+unless told otherwise. This is so you will notice the location of the
+problem if you are correcting a draft.
+
address@hidden finalout
+To prevent such a monstrosity from marring your final printout, write
+the following in the beginning of the Texinfo file on a line of its own,
+before the @code{@@titlepage} command:
+
address@hidden
+@@finalout
address@hidden example
+
+
address@hidden smallbook
address@hidden Printing ``Small'' Books
address@hidden smallbook
address@hidden Small book size
address@hidden Book, printing small
address@hidden Page sizes for books
address@hidden Size of printed book
+
+By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch
+format. However, you can direct @TeX{} to typeset a document in a 7 by
+9.25 inch format that is suitable for bound books by inserting the
+following command on a line by itself at the beginning of the Texinfo
+file, before the title page:@refill
+
address@hidden
+@@smallbook
address@hidden example
+
address@hidden
+(Since many books are about 7 by 9.25 inches, this command might better
+have been called the @code{@@regularbooksize} command, but it came to be
+called the @code{@@smallbook} command by comparison to the 8.5 by 11 inch
format.)
+
+If you write the @code{@@smallbook} command between the
+start-of-header and end-of-header lines, the Texinfo mode @TeX{}
+region formatting command, @code{texinfo-tex-region}, will format the
+region in ``small'' book size (@pxref{Start of Header})address@hidden
+
address@hidden, for information about
+commands that make it easier to produce examples for a smaller manual.
+
address@hidden with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
address@hidden, for other ways to format with @code{@@smallbook} that do not
+require changing the source file.
+
+
address@hidden A4 Paper
address@hidden Printing on A4 Paper
address@hidden A4 paper, printing on
address@hidden A5 paper, printing on
address@hidden Paper size, A4
address@hidden European A4 paper
address@hidden afourpaper
+
+You can tell @TeX{} to format a document for printing on European size
+A4 paper (or A5) with the @code{@@afourpaper} (or @code{@@afivepaper})
+command. Write the command on a line by itself near the beginning of
+the Texinfo file, before the title page. For example, this is how you
+would write the header for this manual:
+
address@hidden
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename texinfo
+@@settitle Texinfo
+@@afourpaper
+@@c %**end of header
address@hidden group
address@hidden example
+
address@hidden with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
address@hidden, for other ways to format for different paper sizes that do not
+require changing the source file.
+
address@hidden afourlatex
address@hidden afourwide
+You may or may not prefer the formatting that results from the command
address@hidden@@afourlatex}. There's also @code{@@afourwide} for A4 paper in
+wide format.
+
address@hidden pagesizes
address@hidden @code{@@pagesizes} address@hidden, @var{height}]: Custom page
sizes
address@hidden pagesizes
address@hidden Custom page sizes
address@hidden Page sizes, customized
address@hidden Text width and height
address@hidden Width of text area
address@hidden Height of text area
address@hidden Depth of text area
+
+You can explicitly specify the height and (optionally) width of the main
+text area on the page with the @code{@@pagesizes} command. Write this
+on a line by itself near the beginning of the Texinfo file, before the
+title page. The height comes first, then the width if desired,
+separated by a comma. Examples:
+
address@hidden
+@@pagesizes 200mm,150mm @c for b5 paper
address@hidden example
address@hidden and
address@hidden
+@@pagesizes 11.5in @c for legal paper
address@hidden example
+
address@hidden B5 paper, printing on
address@hidden Legal paper, printing on
+This would be reasonable for printing on B5-size paper. To emphasize,
+this command specifies the size of the @emph{text area}, not the size of
+the paper (which is address@hidden by address@hidden for B5, address@hidden by
address@hidden for legal).
+
address@hidden Margins on page, not controllable
+To make more elaborate changes, such as changing any of the page
+margins, you must define a new command in @file{texinfo.tex} (or
address@hidden, @pxref{Preparing for TeX,,Preparing for @TeX{}}).
+
address@hidden with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
address@hidden, for other ways to specify @code{@@pagesizes} that do not
+require changing the source file.
+
address@hidden@@pagesizes} is ignored by @code{makeinfo}.
+
+
address@hidden Cropmarks and Magnification
address@hidden Cropmarks and Magnification
address@hidden cropmarks
address@hidden Cropmarks for printing
address@hidden Printing cropmarks
+You can (attempt to) direct @TeX{} to print cropmarks at the corners of
+pages with the @code{@@cropmarks} command. Write the @code{@@cropmarks}
+command on a line by itself between @code{@@iftex} and @code{@@end
+iftex} lines near the beginning of the Texinfo file, before the title
+page, like this:@refill
+
address@hidden
address@hidden
+@@iftex
+@@cropmarks
+@@end iftex
address@hidden group
address@hidden example
+
+This command is mainly for printers that typeset several pages on one
+sheet of film; but you can attempt to use it to mark the corners of a
+book set to 7 by 9.25 inches with the @code{@@smallbook} command.
+(Printers will not produce cropmarks for regular sized output that is
+printed on regular sized paper.) Since different printing machines work
+in different ways, you should explore the use of this command with a
+spirit of adventure. You may have to redefine the command in
address@hidden
+
address@hidden \mag @r{(raw @TeX{} magnification)}
address@hidden Magnified printing
address@hidden Larger or smaller pages
+You can attempt to direct @TeX{} to typeset pages larger or smaller than
+usual with the @code{\mag} @TeX{} command. Everything that is typeset
+is scaled proportionally larger or smaller. (@code{\mag} stands for
+``magnification''.) This is @emph{not} a Texinfo @@-command, but is a
+plain @TeX{} command that is prefixed with a backslash. You have to
+write this command between @code{@@tex} and @code{@@end tex}
+(@pxref{Raw Formatter Commands}).
+
+Follow the @code{\mag} command with an @samp{=} and then a number that
+is 1000 times the magnification you desire. For example, to print pages
+at 1.2 normal size, write the following near the beginning of the
+Texinfo file, before the title page:
+
address@hidden
address@hidden
+@@tex
+\mag=1200
+@@end tex
address@hidden group
address@hidden example
+
+With some printing technologies, you can print normal-sized copies that
+look better than usual by giving a larger-than-normal master to your
+print shop. They do the reduction, thus effectively increasing the
+resolution.
+
+Depending on your system, DVI files prepared with a
address@hidden may not print or may print only with certain
+magnifications. Be prepared to experiment.
+
+
address@hidden PDF Output
address@hidden PDF Output
address@hidden PDF output
+
address@hidden pdftex
+You can generate a PDF output file from Texinfo source by using the
address@hidden program to process your file instead of plain
address@hidden Just run @samp{pdftex foo.texi} instead of @samp{tex
+foo.texi}, or give the @samp{--pdf} option to @command{texi2dvi}.
+
address@hidden stands for `Portable Document Format'. It was invented by
+Adobe Systems some years ago for document interchange, based on their
+PostScript language. A @uref{http://www.foolabs.com/xpdf/, PDF reader}
+for the X window system is freely available, as is the
address@hidden://partners.adobe.com/asn/developer/technotes/, definition of
+the file format}. Since PDF is a binary format, there are no
address@hidden@@ifpdf} or @samp{@@pdf} commands as with the other output
+formats.
+
+Despite the `portable' in the name, PDF files are nowhere near as
+portable in practice as the plain ASCII formats (Info, HTML) that
+Texinfo supports (DVI portability is arguable). They also tend to be
+much larger and do not support the bitmap fonts used by @TeX{} (by
+default) very well. Nevertheless, a PDF file does preserve an actual
+printed document on a screen as faithfully as possible, so it has its place.
+
+PDF support in Texinfo is fairly rudimentary.
+
+
address@hidden Creating and Installing Info Files
address@hidden Creating and Installing Info Files
+
+This chapter describes how to create and install Info files. @xref{Info
+Files}, for general information about the file format itself.
+
address@hidden
+* Creating an Info File::
+* Installing an Info File::
address@hidden menu
+
+
address@hidden Creating an Info File
address@hidden Creating an Info File
address@hidden Creating an Info file
address@hidden Info, creating an online file
address@hidden Formatting a file for Info
+
address@hidden is a program that converts a Texinfo file into an Info
+file, HTML file, or plain text. @code{texinfo-format-region} and
address@hidden are GNU Emacs functions that convert
+Texinfo to Info.
+
+For information on installing the Info file in the Info system,
address@hidden an Info File}.
+
address@hidden
+* makeinfo advantages:: @code{makeinfo} provides better error checking.
+* Invoking makeinfo:: How to run @code{makeinfo} from a shell.
+* makeinfo options:: Specify fill-column and other options.
+* Pointer Validation:: How to check that pointers point somewhere.
+* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs.
+* 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.
+* makeinfo html:: Generating HTML output.
address@hidden menu
+
+
address@hidden makeinfo advantages
address@hidden @code{makeinfo} Preferred
+
+The @code{makeinfo} utility creates an Info file from a Texinfo source
+file more quickly than either of the Emacs formatting commands and
+provides better error messages. We recommend it. @code{makeinfo} is a
+C program that is independent of Emacs. You do not need to run Emacs to
+use @code{makeinfo}, which means you can use @code{makeinfo} on machines
+that are too small to run Emacs. You can run @code{makeinfo} in any one
+of three ways: from an operating system shell, from a shell inside
+Emacs, or by typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b}
+command in Texinfo mode in Emacs.
address@hidden
+
+The @code{texinfo-format-region} and the @code{texinfo-format-buffer}
+commands are useful if you cannot run @code{makeinfo}. Also, in some
+circumstances, they format short regions or buffers more quickly than
address@hidden@refill
+
address@hidden Invoking makeinfo
address@hidden Running @code{makeinfo} from a Shell
+
+To create an Info file from a Texinfo file, type @code{makeinfo}
+followed by the name of the Texinfo file. Thus, to create the Info
+file for Bison, type the following to the shell:
+
address@hidden
+makeinfo bison.texinfo
address@hidden example
+
+(You can run a shell inside Emacs by typing @kbd{M-x shell}.)@refill
+
+Sometimes you will want to specify options. For example, if you wish
+to discover which version of @code{makeinfo} you are using,
+type:@refill
+
address@hidden
+makeinfo --version
address@hidden example
+
address@hidden options}, for more information.
+
+
address@hidden makeinfo options
address@hidden Options for @code{makeinfo}
address@hidden @code{makeinfo} options
address@hidden Options for @code{makeinfo}
+
+The @code{makeinfo} command takes a number of options. Most often,
+options are used to set the value of the fill column and specify the
+footnote style. Each command line option is a word preceded by
address@hidden or a letter preceded by @samp{-}. You can use abbreviations
+for the long option names as long as they are address@hidden
+
+For example, you could use the following shell command to create an Info
+file for @file{bison.texinfo} in which each line is filled to only 68
+columns:@refill
+
address@hidden
+makeinfo --fill-column=68 bison.texinfo
address@hidden example
+
+You can write two or more options in sequence, like this:@refill
+
address@hidden
+makeinfo --no-split --fill-column=70 @dots{}
address@hidden example
+
address@hidden
+This would keep the Info file together as one possibly very long
+file and would also set the fill column to address@hidden
+
+The options are:
+
address@hidden @code
+
address@hidden -D @var{var}
address@hidden -D @var{var}
+Cause the variable @var{var} to be defined. This is equivalent to
address@hidden@@set @var{var}} in the Texinfo file (@pxref{set clear value}).
+
address@hidden --commands-in-node-names
address@hidden --commands-in-node-names
+Allow @code{@@}-commands in node names. This is not recommended, as it
+can probably never be implemented in @TeX{}. It also makes
address@hidden much slower. Also, this option is ignored when
address@hidden is used. @xref{Pointer Validation}, for more
+details.
+
address@hidden --docbook
address@hidden --docbook
+Generate DocBook output rather than Info.
+
address@hidden address@hidden
address@hidden -e @var{limit}
address@hidden address@hidden
address@hidden -e @var{limit}
+Set the maximum number of errors that @code{makeinfo} will report
+before exiting (on the assumption that continuing would be useless);
+default 100.
+
address@hidden address@hidden
address@hidden -f @var{width}
address@hidden address@hidden
address@hidden -f @var{width}
+Specify the maximum number of columns in a line; this is the right-hand
+edge of a line. Paragraphs that are filled will be filled to this
+width. (Filling is the process of breaking up and connecting lines so
+that lines are the same length as or shorter than the number specified
+as the fill column. Lines are broken between words.) The default value
+is 72. Ignored with @samp{--html}.
+
address@hidden address@hidden
address@hidden -s @var{style}
address@hidden address@hidden
address@hidden -s @var{style}
+Set the footnote style to @var{style}, either @samp{end} for the end
+node style (the default) or @samp{separate} for the separate node style.
+The value set by this option overrides the value set in a Texinfo file
+by an @code{@@footnotestyle} command (@pxref{Footnotes}). When the
+footnote style is @samp{separate}, @code{makeinfo} makes a new node
+containing the footnotes found in the current node. When the footnote
+style is @samp{end}, @code{makeinfo} places the footnote references at
+the end of the current node. Ignored with @samp{--html}.
+
address@hidden --force
address@hidden -F
address@hidden --force
address@hidden -F
+Ordinarily, if the input file has errors, the output files are not
+created. With this option, they are preserved.
+
address@hidden --help
address@hidden -h
address@hidden --help
address@hidden -h
+Print a usage message listing all available options, then exit successfully.
+
address@hidden --html
address@hidden --html
+Generate HTML output rather than Info. @xref{makeinfo html}. By
+default, the HTML output is split into one output file per source node,
+and the split output is written into a subdirectory with the name of the
+top-level info file.
+
address@hidden -I @var{dir}
address@hidden -I @var{dir}
+Append @var{dir} to the directory search list for finding files that
+are included using the @code{@@include} command. By default,
address@hidden searches only the current directory. If @var{dir} is
+not given, the current directory @file{.} is appended. Note that
address@hidden can actually be a list of several directories separated by the
+usual path separator character (@samp{:} on Unix, @samp{;} on
+MS-DOS/MS-Windows).
+
address@hidden address@hidden
address@hidden -E @var{file}
+Output the Texinfo source with all the macros expanded to the named
+file. Normally, the results of macro expansion are used internally by
address@hidden and then discarded. This option is used by
address@hidden if you are using an old version of @file{texinfo.tex}
+that does not support @code{@@macro}.
+
address@hidden --no-headers
address@hidden --no-headers
address@hidden Plain text output
address@hidden ASCII text output
address@hidden Generating plain text files
address@hidden @file{INSTALL} file, generating
address@hidden Node separators, omitting
address@hidden Menus, omitting
+For Info output, do not include menus or node separator lines in the
+output. This results in a simple plain text file that you can (for
+example) send in email without complications, or include in a
+distribution (as in an @file{INSTALL} file).
+
address@hidden Navigation links, omitting
+For HTML output, likewise omit menus. And if @samp{--no-split} is also
+specified, do not include a navigation links at the top of each node
+(these are never included in the default case of split output).
address@hidden html}.
+
+In both cases, write to standard output by default (can still be
+overridden by @option{-o}).
+
address@hidden --no-split
address@hidden --no-split
address@hidden Splitting of output files
address@hidden Output file splitting
+Suppress the splitting stage of @code{makeinfo}. By default, large
+output files (where the size is greater than 70k bytes) are split into
+smaller subfiles. For Info output, each one is approximately 50k bytes.
+For HTML output, each file contains one node (@pxref{makeinfo html}).
+
address@hidden --no-pointer-validate
address@hidden --no-validate
address@hidden --no-pointer-validate
address@hidden --no-validate
address@hidden Pointer validation, suppressing
+Suppress the pointer-validation phase of @code{makeinfo}. This can also
+be done with the @code{@@novalidate} command (@pxref{Use TeX,,Use
address@hidden). Normally, after a Texinfo file is processed, some consistency
+checks are made to ensure that cross references can be resolved, etc.
address@hidden Validation}.
+
address@hidden --no-warn
address@hidden --no-warn
+Suppress warning messages (but @emph{not} error messages). You might
+want this if the file you are creating has examples of Texinfo cross
+references within it, and the nodes that are referenced do not actually
+exist.
+
address@hidden --number-sections
address@hidden --number-sections
+Output chapter, section, and appendix numbers as in printed manuals.
+
address@hidden --no-number-footnotes
address@hidden --no-number-footnotes
+Suppress automatic footnote numbering. By default, @code{makeinfo}
+numbers each footnote sequentially in a single node, resetting the
+current footnote number to 1 at the start of each node.
+
address@hidden address@hidden
address@hidden -o @var{file}
address@hidden address@hidden
address@hidden -o @var{file}
+Specify that the output should be directed to @var{file} and not to the
+file name specified in the @code{@@setfilename} command found in the
+Texinfo source (@pxref{setfilename}). If @var{file} is @samp{-}, output
+goes to standard output and @samp{--no-split} is implied. For split
+HTML output, @var{file} is the name for the directory into which all
+HTML nodes are written (@pxref{makeinfo html}).
+
address@hidden -P @var{dir}
address@hidden -P @var{dir}
+Prepend @var{dir} to the directory search list for @code{@@include}.
+If @var{dir} is not given, the current directory @file{.} is prepended.
+See @samp{-I} for more details.
+
address@hidden address@hidden
address@hidden -p @var{indent}
address@hidden address@hidden
address@hidden -p @var{indent}
+Set the paragraph indentation style to @var{indent}. The value set by
+this option overrides the value set in a Texinfo file by an
address@hidden@@paragraphindent} command (@pxref{paragraphindent}). The value
+of @var{indent} is interpreted as follows:
+
address@hidden @asis
address@hidden @samp{asis}
+Preserve any existing indentation at the starts of paragraphs.
+
address@hidden @samp{0} or @samp{none}
+Delete any existing indentation.
+
address@hidden @var{num}
+Indent each paragraph by @var{num} spaces.
address@hidden table
+
address@hidden address@hidden
address@hidden -r @var{limit}
address@hidden address@hidden
address@hidden -r @var{limit}
+Set the value of the number of references to a node that
address@hidden will make without reporting a warning. If a node has more
+than this number of references in it, @code{makeinfo} will make the
+references but also report a warning. The default is 1000.
+
address@hidden -U @var{var}
+Cause @var{var} to be undefined. This is equivalent to
address@hidden@@clear @var{var}} in the Texinfo file (@pxref{set clear value}).
+
address@hidden --verbose
address@hidden --verbose
+Cause @code{makeinfo} to display messages saying what it is doing.
+Normally, @code{makeinfo} only outputs messages if there are errors or
+warnings.
+
address@hidden --version
address@hidden -V
address@hidden --version
address@hidden -V
+Print the version number, then exit successfully.
+
address@hidden --xml
address@hidden --xml
+Generate XML output rather than Info.
+
address@hidden table
+
+
address@hidden Pointer Validation
address@hidden Pointer Validation
address@hidden Pointer validation with @code{makeinfo}
address@hidden Validation of pointers
+
+If you do not suppress pointer validation with the @samp{--no-validate}
+option or the @code{@@novalidate} command in the source file (@pxref{Use
+TeX,,Use @TeX{}}), @code{makeinfo} will check the validity of the final
+Info file. Mostly, this means ensuring that nodes you have referenced
+really exist. Here is a complete list of what is checked:
+
address@hidden
address@hidden
+If a `Next', `Previous', or `Up' node reference is a reference to a
+node in the current file and is not an external reference such as to
address@hidden(dir)}, then the referenced node must address@hidden
+
address@hidden
+In every node, if the `Previous' node is different from the `Up' node,
+then the node pointed to by the `Previous' field must have a `Next'
+field which points back to this address@hidden
+
address@hidden
+Every node except the `Top' node must have an `Up' address@hidden
+
address@hidden
+The node referenced by an `Up' pointer must itself reference the current
+node through a menu item, unless the node referenced by `Up'
+has the form `(@var{file})'.
+
address@hidden
+If the `Next' reference of a node is not the same as the `Next' reference
+of the `Up' reference, then the node referenced by the `Next' pointer
+must have a `Previous' pointer that points back to the current node.
+This rule allows the last node in a section to point to the first node
+of the next address@hidden
+
address@hidden
+Every node except `Top' should be referenced by at least one other node,
+either via the `Previous' or `Next' links, or via a menu or a
address@hidden
address@hidden enumerate
+
address@hidden @@-commands in @@node, limited support
+Some Texinfo documents might fail during the validation phase because
+they use commands like @code{@@value} and @code{@@definfoenclose} in
+node definitions and cross-references inconsistently. Consider the
+following example:
+
address@hidden
address@hidden
+@@set nodename Node 1
+
+@@node @@address@hidden@}, Node 2, Top, Top
+
+This is node 1.
+
+@@node Node 2, , Node 1, Top
+
+This is node 2.
address@hidden group
address@hidden example
+
address@hidden
+Here, the node ``Node 1'' was referenced both verbatim and through
address@hidden@@value}.
+
+By default, @code{makeinfo} fails such cases, because node names are not
+fully expanded until they are written to the output file. You should
+always try to reference nodes consistently; e.g., in the above example,
+the second @code{@@node} line should have also used @code{@@value}.
+However, if, for some reason, you @emph{must} reference node names
+inconsistently, and @code{makeinfo} fails to validate the file, you can
+use the @samp{--commands-in-node-names} option to force @code{makeinfo}
+to perform the expensive expansion of all node names it finds in the
+document. This might considerably slow down the program, though;
+twofold increase in conversion time was measured for large documents
+such as the Jargon file.
+
address@hidden @@value in @@node lines
+The support for @code{@@}-commands in @code{@@node} directives is not
+general enough to be freely used. For example, if the example above
+redefined @code{nodename} somewhere in the document, @code{makeinfo}
+will fail to convert it, even if invoked with the
address@hidden option.
+
address@hidden has no effect if the @samp{--no-validate}
+option is given.
+
+
address@hidden makeinfo in Emacs
address@hidden Running @code{makeinfo} inside Emacs
address@hidden Running @code{makeinfo} in Emacs
address@hidden @code{makeinfo} inside Emacs
address@hidden Shell, running @code{makeinfo} in
+
+You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the
address@hidden or the @code{makeinfo-buffer} commands. In
+Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c
+C-m C-b} by address@hidden
+
address@hidden @kbd
address@hidden C-c C-m C-r
address@hidden M-x makeinfo-region
+Format the current region for address@hidden
address@hidden makeinfo-region
+
address@hidden C-c C-m C-b
address@hidden M-x makeinfo-buffer
+Format the current buffer for address@hidden
address@hidden makeinfo-buffer
address@hidden table
+
+When you invoke either @code{makeinfo-region} or
address@hidden, Emacs prompts for a file name, offering the
+name of the visited file as the default. You can edit the default
+file name in the minibuffer if you wish, before pressing @key{RET} to
+start the @code{makeinfo} address@hidden
+
+The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands
+run the @code{makeinfo} program in a temporary shell buffer. If
address@hidden finds any errors, Emacs displays the error messages in
+the temporary address@hidden
+
address@hidden Errors, parsing
address@hidden Parsing errors
address@hidden next-error
+You can parse the error messages by typing @kbd{C-x `}
+(@code{next-error}). This causes Emacs to go to and position the
+cursor on the line in the Texinfo source that @code{makeinfo} thinks
+caused the error. @xref{Compilation, , Running @code{make} or
+Compilers Generally, emacs, The GNU Emacs Manual}, for more
+information about using the @code{next-error} address@hidden
+
+In addition, you can kill the shell in which the @code{makeinfo}
+command is running or make the shell buffer display its most recent
address@hidden
+
address@hidden @kbd
address@hidden C-c C-m C-k
address@hidden M-x makeinfo-kill-job
address@hidden makeinfo-kill-job
+Kill the current running @code{makeinfo} job
+(from @code{makeinfo-region} or @code{makeinfo-buffer})address@hidden
+
address@hidden C-c C-m C-l
address@hidden M-x makeinfo-recenter-output-buffer
address@hidden makeinfo-recenter-output-buffer
+Redisplay the @code{makeinfo} shell buffer to display its most recent
address@hidden
address@hidden table
+
address@hidden
+(Note that the parallel commands for killing and recentering a @TeX{}
+job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode
+Printing}.)@refill
+
+You can specify options for @code{makeinfo} by setting the
address@hidden variable with either the @kbd{M-x
+edit-options} or the @kbd{M-x set-variable} command, or by setting the
+variable in your @file{.emacs} initialization address@hidden
+
+For example, you could write the following in your @file{.emacs} file:@refill
+
address@hidden
address@hidden
+(setq makeinfo-options
+ "--paragraph-indent=0 --no-split
+ --fill-column=70 --verbose")
address@hidden group
address@hidden example
+
address@hidden If you write these three cross references using xref, you see
address@hidden three references to the same named manual, which looks strange.
address@hidden
+For more information, address@hidden
address@hidden Options, , Editing Variable Values, emacs, The GNU Emacs
Manual},@*
address@hidden, , Examining and Setting Variables, emacs, The GNU Emacs
Manual},@*
address@hidden File, , , emacs, The GNU Emacs Manual}, address@hidden
address@hidden options, , Options for @code{makeinfo}}.
+
address@hidden texinfo-format commands
address@hidden node-name, next, previous, up
address@hidden The @address@hidden Commands
address@hidden texinfo-format-region
address@hidden texinfo-format-buffer
+
+In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
+file with the @code{texinfo-format-region} command. This formats the
+current region and displays the formatted text in a temporary buffer
+called @samp{*Info address@hidden
+
+Similarly, you can format a buffer with the
address@hidden command. This command creates a new
+buffer and generates the Info file in it. Typing @kbd{C-x C-s} will
+save the Info file under the name specified by the
address@hidden@@setfilename} line which must be near the beginning of the
+Texinfo address@hidden
+
address@hidden @kbd
address@hidden C-c C-e C-r
address@hidden @code{texinfo-format-region}
+Format the current region for Info.
address@hidden texinfo-format-region
+
address@hidden C-c C-e C-b
address@hidden @code{texinfo-format-buffer}
+Format the current buffer for Info.
address@hidden texinfo-format-buffer
address@hidden table
+
+The @code{texinfo-format-region} and @code{texinfo-format-buffer}
+commands provide you with some error checking, and other functions can
+provide you with further help in finding formatting errors. These
+procedures are described in an appendix; see @ref{Catching Mistakes}.
+However, the @code{makeinfo} program is often faster and
+provides better error checking (@pxref{makeinfo in Emacs})address@hidden
+
address@hidden Batch Formatting
address@hidden node-name, next, previous, up
address@hidden Batch Formatting
address@hidden Batch formatting for Info
address@hidden Info batch formatting
+
+You can format Texinfo files for Info using @code{batch-texinfo-format}
+and Emacs Batch mode. You can run Emacs in Batch mode from any shell,
+including a shell inside of Emacs. (@xref{Command Switches, , Command
+Line Switches and Arguments, emacs, The GNU Emacs Manual}.)@refill
+
+Here is a shell command to format all the files that end in
address@hidden in the current directory:
+
address@hidden
+emacs -batch -funcall batch-texinfo-format *.texinfo
address@hidden example
+
address@hidden
+Emacs processes all the files listed on the command line, even if an
+error occurs while attempting to format some of address@hidden
+
+Run @code{batch-texinfo-format} only with Emacs in Batch mode as shown;
+it is not interactive. It kills the Batch mode Emacs on address@hidden
+
address@hidden is convenient if you lack @code{makeinfo}
+and want to format several Texinfo files at once. When you use Batch
+mode, you create a new Emacs process. This frees your current Emacs, so
+you can continue working in it. (When you run
address@hidden or @code{texinfo-format-buffer}, you cannot
+use that Emacs for anything else until the command finishes.)@refill
+
address@hidden Tag and Split Files
address@hidden node-name, next, previous, up
address@hidden Tag Files and Split Files
address@hidden Making a tag table automatically
address@hidden Tag table, making automatically
+
+If a Texinfo file has more than 30,000 bytes,
address@hidden automatically creates a tag table
+for its Info file; @code{makeinfo} always creates a tag table. With
+a @dfn{tag table}, Info can jump to new nodes more quickly than it can
address@hidden
+
address@hidden Indirect subfiles
+In addition, if the Texinfo file contains more than about 70,000
+bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the
+large Info file into shorter @dfn{indirect} subfiles of about 50,000
+bytes each. Big files are split into smaller files so that Emacs does
+not need to make a large buffer to hold the whole of a large Info
+file; instead, Emacs allocates just enough memory for the small, split-off
+file that is needed at the time. This way, Emacs avoids wasting
+memory when you run Info. (Before splitting was implemented, Info
+files were always kept short and @dfn{include files} were designed as
+a way to create a single, large printed manual out of the smaller Info
+files. @xref{Include Files}, for more information. Include files are
+still used for very large documents, such as @cite{The Emacs Lisp
+Reference Manual}, in which each chapter is a separate file.)@refill
+
+When a file is split, Info itself makes use of a shortened version of
+the original file that contains just the tag table and references to
+the files that were split off. The split-off files are called
address@hidden address@hidden
+
+The split-off files have names that are created by appending @address@hidden,
address@hidden@samp{-2}}, @address@hidden and so on to the file name specified
by the
address@hidden@@setfilename} command. The shortened version of the original
file
+continues to have the name specified by @code{@@address@hidden
+
+At one stage in writing this document, for example, the Info file was saved
+as the file @file{test-texinfo} and that file looked like this:@refill
+
address@hidden
address@hidden
+Info file: test-texinfo, -*-Text-*-
+produced by texinfo-format-buffer
+from file: new-texinfo-manual.texinfo
+
+^_
+Indirect:
+test-texinfo-1: 102
+test-texinfo-2: 50422
address@hidden group
address@hidden
+test-texinfo-3: 101300
+^_^L
+Tag table:
+(Indirect)
+Node: overview^?104
+Node: info file^?1271
address@hidden group
address@hidden
+Node: printed manual^?4853
+Node: conventions^?6855
address@hidden
address@hidden group
address@hidden example
+
address@hidden
+(But @file{test-texinfo} had far more nodes than are shown here.) Each of
+the split-off, indirect files, @file{test-texinfo-1},
address@hidden, and @file{test-texinfo-3}, is listed in this file
+after the line that says @samp{Indirect:}. The tag table is listed after
+the line that says @samp{Tag table:}. @refill
+
+In the list of indirect files, the number following the file name
+records the cumulative number of bytes in the preceding indirect files,
+not counting the file list itself, the tag table, or the permissions
+text in each file. In the tag table, the number following the node name
+records the location of the beginning of the node, in bytes from the
+beginning of the (unsplit) output.
+
+If you are using @code{texinfo-format-buffer} to create Info files,
+you may want to run the @code{Info-validate} command. (The
address@hidden command does such a good job on its own, you do not
+need @code{Info-validate}.) However, you cannot run the @kbd{M-x
+Info-validate} node-checking command on indirect files. For
+information on how to prevent files from being split and how to
+validate the structure of the nodes, see @ref{Using
address@hidden
+
+
address@hidden makeinfo html
address@hidden Generating HTML
address@hidden HTML
+
+Besides generating output in the Info format, you can use the
address@hidden option to generate output in HTML format, for installation
+on a web site (for example). By default, the HTML output is split at
+node level.
+
+When splitting, the HTML output files are written into a subdirectory.
+The subdirectory is named according to the name from
address@hidden@@setfilename} with any extension removed; for example, HTML
+output for @code{@@setfilename emacs.info} would be written into a
+subdirectory named @samp{emacs}. If that directory cannot be created
+for any reason, then @samp{.html} is appended to the directory name, as
+in @samp{emacs.html} (this is necessary because sometimes the info file
+is named without an extension, e.g., @samp{texinfo}). If the
address@hidden@var{name}.html} directory can't be created either,
address@hidden gives up. In any case, the top-level output file within
+the directory is always named @samp{index.html}.
+
+Monolithic output (@code{--no-split}) is named according to
address@hidden@@setfilename} or @code{--outfile}. Cross-document node
+references are not supported in monolithic HTML.
+
+Texinfo input marked up with the @code{@@ifhtml} command will produce
+output only with the @samp{--html} option supplied. Input marked up
+with the @code{@@html} is passed literally to the output (suppressing
+the normal escaping of input @samp{<}, @samp{>} and @samp{&} characters
+which have special significance in HTML).
+
+The @samp{--footnote-style} option is currently ignored for HTML output;
+footnotes are linked to the end of the output file.
+
+The HTML generated is mostly standard (i.e., HTML 2.0, RFC-1866). The
+exception is that HTML 3.2 tables are generated from the
address@hidden@@multitable} command, but tagged to degrade as well as possible
+in browsers without table support. The HTML 4 @samp{lang} attribute on
+the @samp{<html>} attribute is also used. Please report output from an
+error-free run of @code{makeinfo} which has browser portability problems
+as a bug.
+
+Navigation bars are inserted at the start of nodes, similarly to Info
+output. The @samp{--no-headers} option will suppress this if used with
address@hidden Header @code{<link>} elements in split output can
+support info-like navigation with browsers like Lynx and @w{Emacs W3}
+which implement this @w{HTML 1.0} feature. @samp{@@xref} commands to
+other documents are generated assuming the other document is available
+in split HTML form, and installed in the same HTML documentation tree,
+at @file{../<info-document>/}.
+
+
address@hidden Installing an Info File
address@hidden Installing an Info File
address@hidden Installing an Info file
address@hidden Info file installation
address@hidden @file{dir} directory for Info installation
+
+Info files are usually kept in the @file{info} directory. You can read
+Info files using the standalone Info program or the Info reader built
+into Emacs. (@inforef{Top, info, info}, for an introduction to Info.)
+
address@hidden
+* 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 install-info:: @code{install-info} options.
address@hidden menu
+
+
address@hidden Directory File
address@hidden The Directory File @file{dir}
+
+For Info to work, the @file{info} directory must contain a file that
+serves as a top level directory for the Info system. By convention,
+this file is called @file{dir}. (You can find the location of this file
+within Emacs by typing @kbd{C-h i} to enter Info and then typing
address@hidden C-f} to see the pathname to the @file{info} directory.)
+
+The @file{dir} file is itself an Info file. It contains the top level
+menu for all the Info files in the system. The menu looks like
+this:@refill
+
address@hidden
address@hidden
+* Menu:
+* Info: (info). Documentation browsing system.
+* Emacs: (emacs). The extensible, self-documenting
+ text editor.
+* Texinfo: (texinfo). With one source file, make
+ either a printed manual using
+ @@address@hidden@} or an Info file.
address@hidden
address@hidden group
address@hidden example
+
+Each of these menu entries points to the `Top' node of the Info file
+that is named in parentheses. (The menu entry does not need to
+specify the `Top' node, since Info goes to the `Top' node if no node
+name is mentioned. @xref{Other Info Files, , Nodes in Other Info
+Files}.)@refill
+
+Thus, the @samp{Info} entry points to the `Top' node of the
address@hidden file and the @samp{Emacs} entry points to the `Top' node
+of the @file{emacs} address@hidden
+
+In each of the Info files, the `Up' pointer of the `Top' node refers
+back to the @code{dir} file. For example, the line for the `Top'
+node of the Emacs manual looks like this in Info:@refill
+
address@hidden
+File: emacs Node: Top, Up: (DIR), Next: Distrib
address@hidden example
+
address@hidden
+In this case, the @file{dir} file name is written in upper case
+letters---it can be written in either upper or lower case. This is not
+true in general, it is a special case for @file{dir}.
+
+
address@hidden New Info File
address@hidden Listing a New Info File
address@hidden Adding a new Info file
address@hidden Listing a new Info file
address@hidden New Info file, listing it in @file{dir} file
address@hidden Info file, listing a new
address@hidden @file{dir} file listing
+
+To add a new Info file to your system, you must write a menu entry to
+add to the menu in the @file{dir} file in the @file{info} directory.
+For example, if you were adding documentation for GDB, you would write
+the following new entry:@refill
+
address@hidden
+* GDB: (gdb). The source-level C debugger.
address@hidden example
+
address@hidden
+The first part of the menu entry is the menu entry name, followed by a
+colon. The second part is the name of the Info file, in parentheses,
+followed by a period. The third part is the description.
+
+The name of an Info file often has a @file{.info} extension. Thus, the
+Info file for GDB might be called either @file{gdb} or @file{gdb.info}.
+The Info reader programs automatically try the file name both with and
+without @address@hidden MS-DOS/MS-Windows systems, Info will
+try the @file{.inf} extension as well.}; so it is better to avoid
+clutter and not to write @samp{.info} explicitly in the menu entry. For
+example, the GDB menu entry should use just @samp{gdb} for the file
+name, not @samp{gdb.info}.
+
+
address@hidden Other Info Directories
address@hidden Info Files in Other Directories
address@hidden Installing Info in another directory
address@hidden Info installed in another directory
address@hidden Another Info directory
address@hidden @file{dir} files and Info directories
+
+If an Info file is not in the @file{info} directory, there are three
+ways to specify its location:@refill
+
address@hidden
address@hidden
+Write the pathname in the @file{dir} file as the second part of the menu.
+
address@hidden
+If you are using Emacs, list the name of the file in a second @file{dir}
+file, in its directory; and then add the name of that directory to the
address@hidden variable in your personal or site
+initialization file.
+
+This variable tells Emacs where to look for @file{dir} files (the files
+must be named @file{dir}). Emacs merges the files named @file{dir} from
+each of the listed directories. (In Emacs version 18, you can set the
address@hidden variable to the name of only one
+directory.)@refill
+
address@hidden
+Specify the Info directory name in the @code{INFOPATH} environment
+variable in your @file{.profile} or @file{.cshrc} initialization file.
+(Only you and others who set this environment variable will be able to
+find Info files whose location is specified this way.)
address@hidden enumerate
+
+For example, to reach a test file in the @file{/home/bob/info}
+directory, you could add an entry like this to the menu in the
+standard @file{dir} file:@refill
+
address@hidden
+* Test: (/home/bob/info/info-test). Bob's own test file.
address@hidden example
+
address@hidden
+In this case, the absolute file name of the @file{info-test} file is
+written as the second part of the menu address@hidden
+
+Alternatively, you could write the following in your @file{.emacs} file:
+
address@hidden Info-directory-list
address@hidden
address@hidden
+(require 'info)
+(setq Info-directory-list
+ (cons (expand-file-name "/home/bob/info")
+ Info-directory-list))
address@hidden group
address@hidden example
+
+This tells Emacs to merge the system @file{dir} file with the @file{dir}
+file in @file{/home/bob/info}. Thus, Info will list the
address@hidden/home/bob/info/info-test} file as a menu entry in the
address@hidden/home/bob/info/dir} file. Emacs does the merging only when
address@hidden info} is first run, so if you want to set
address@hidden in an Emacs session where you've already run
address@hidden, you must @code{(setq Info-dir-contents nil)} to force Emacs
+to recompose the @file{dir} file.
+
address@hidden INFOPATH
+Finally, you can tell Info where to look by setting the @code{INFOPATH}
+environment variable in your shell startup file, such as @file{.cshrc},
address@hidden or @file{autoexec.bat}. If you use a Bourne-compatible
+shell such as @code{sh} or @code{bash} for your shell command
+interpreter, you set the @code{INFOPATH} environment variable in the
address@hidden initialization file; but if you use @code{csh} or
address@hidden, you set the variable in the @file{.cshrc} initialization
+file. On MS-DOS/MS-Windows systems, you must set @code{INFOPATH} in
+your @file{autoexec.bat} file or in the Registry. Each type of shell
+uses a different syntax.
+
address@hidden @bullet
address@hidden
+In a @file{.cshrc} file, you could set the @code{INFOPATH}
+variable as follows:@refill
+
address@hidden
+setenv INFOPATH .:~/info:/usr/local/emacs/info
address@hidden smallexample
+
address@hidden
+In a @file{.profile} file, you would achieve the same effect by
+writing:@refill
+
address@hidden
+INFOPATH=.:$HOME/info:/usr/local/emacs/info
+export INFOPATH
address@hidden smallexample
+
address@hidden
address@hidden autoexec.bat
+In a @file{autoexec.bat} file, you write this address@hidden the
+use of @samp{;} as the directory separator, and a different syntax for
+using values of other environment variables.}:
+
address@hidden
+set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info
address@hidden smallexample
address@hidden itemize
+
address@hidden
+The @samp{.} indicates the current directory as usual. Emacs uses the
address@hidden environment variable to initialize the value of Emacs's
+own @code{Info-directory-list} variable. The stand-alone Info reader
+merges any files named @file{dir} in any directory listed in the
address@hidden variable into a single menu presented to you in the node
+called @samp{(dir)Top}.
+
address@hidden colon, last in @env{INFOPATH}
+However you set @env{INFOPATH}, if its last character is a
address@hidden MS-DOS/MS-Windows systems, use semi-colon instead.}, this
+is replaced by the default (compiled-in) path. This gives you a way to
+augment the default path with new directories without having to list all
+the standard places. For example (using @code{sh} syntax):
+
address@hidden
+INFOPATH=/local/info:
+export INFOPATH
address@hidden example
+
address@hidden
+will search @file{/local/info} first, then the standard directories.
+Leading or doubled colons are not treated specially.
+
address@hidden @file{dir} file, creating your own
+When you create your own @file{dir} file for use with
address@hidden or @env{INFOPATH}, it's easiest to start by
+copying an existing @file{dir} file and replace all the text after the
address@hidden Menu:} with your desired entries. That way, the punctuation and
+special CTRL-_ characters that Info needs will be present.
+
+
address@hidden Installing Dir Entries
address@hidden Installing Info Directory Files
+
+When you install an Info file onto your system, you can use the program
address@hidden to update the Info directory file @file{dir}.
+Normally the makefile for the package runs @code{install-info}, just
+after copying the Info file into its proper installed location.
+
address@hidden dircategory
address@hidden direntry
+In order for the Info file to work with @code{install-info}, you include
+the commands @code{@@dircategory} and
address@hidden@@address@hidden@code{@@end direntry} in the Texinfo source
+file. Use @code{@@direntry} to specify the menu entries to add to the
+Info directory file, and use @code{@@dircategory} to specify which part
+of the Info directory to put it in. Here is how these commands are used
+in this manual:
+
address@hidden
+@@dircategory Texinfo documentation system
+@@direntry
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. @dots{}
address@hidden
+@@end direntry
address@hidden smallexample
+
+Here's what this produces in the Info file:
+
address@hidden
+INFO-DIR-SECTION Texinfo documentation system
+START-INFO-DIR-ENTRY
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. @dots{}
address@hidden
+END-INFO-DIR-ENTRY
address@hidden smallexample
+
address@hidden
+The @code{install-info} program sees these lines in the Info file, and
+that is how it knows what to do.
+
+Always use the @code{@@direntry} and @code{@@dircategory} commands near
+the beginning of the Texinfo input, before the first @code{@@node}
+command. If you use them later on in the input, @code{install-info}
+will not notice them.
+
+If you use @code{@@dircategory} more than once in the Texinfo source,
+each usage specifies the `current' category; any subsequent
address@hidden@@direntry} commands will add to that category.
+
+Here are some recommended @code{@@dircategory} categories:
+
address@hidden
+GNU packages
+GNU programming tools
+GNU programming documentation
+GNU Emacs Lisp
+GNU libraries
+TeX
+Individual utilities
address@hidden display
+
+The idea is to include the `Invoking' node for every program installed
+by a package under `Individual utilities', and an entry for the manual
+as a whole in the appropriate other category.
+
+
address@hidden Invoking install-info
address@hidden Invoking install-info
+
address@hidden install-info
+
address@hidden inserts menu entries from an Info file into the
+top-level @file{dir} file in the Info system (see the previous sections
+for an explanation of how the @file{dir} file works). It's most often
+run as part of software installation, or when constructing a @file{dir} file
+for all manuals on a system. Synopsis:
+
address@hidden
+install-info address@hidden@dots{} address@hidden address@hidden
address@hidden example
+
+If @var{info-file} or @var{dir-file} are not specified, the options
+(described below) that define them must be. There are no compile-time
+defaults, and standard input is never used. @code{install-info} can
+read only one Info file and write only one @file{dir} file per invocation.
+
address@hidden @file{dir}, created by @code{install-info}
+If @var{dir-file} (however specified) does not exist,
address@hidden creates it if possible (with no entries).
+
address@hidden Compressed files, reading
address@hidden Dir files, compressed
+If any input file is compressed with @code{gzip} (@pxref{Invoking
+gzip,,,gzip, Gzip}), @code{install-info} automatically uncompresses it
+for reading. And if @var{dir-file} is compressed, @code{install-info}
+also automatically leaves it compressed after writing any changes.
+If @var{dir-file} itself does not exist, @code{install-info} tries to
+open @address@hidden
+
+Options:
+
address@hidden @code
address@hidden --delete
address@hidden --delete
+Delete the entries in @var{info-file} from @var{dir-file}. The file
+name in the entry in @var{dir-file} must be @var{info-file} (except for
+an optional @samp{.info} in either one). Don't insert any new entries.
+
address@hidden address@hidden
address@hidden -d @var{name}
address@hidden address@hidden
address@hidden -d @var{name}
+Specify file name of the Info directory file. This is equivalent to
+using the @var{dir-file} argument.
+
address@hidden address@hidden
address@hidden -e @var{text}
address@hidden address@hidden
address@hidden -e @var{text}
+Insert @var{text} as an Info directory entry; @var{text} should have the
+form of an Info menu item line plus zero or more extra lines starting
+with whitespace. If you specify more than one entry, they are all
+added. If you don't specify any entries, they are determined from
+information in the Info file itself.
+
address@hidden --help
address@hidden -h
address@hidden --help
address@hidden -h
+Display a usage message listing basic usage and all available options,
+then exit successfully.
+
address@hidden address@hidden
address@hidden -i @var{file}
address@hidden address@hidden
address@hidden -i @var{file}
+Specify Info file to install in the directory.
+Equivalent to using the @var{info-file} argument.
+
address@hidden address@hidden
address@hidden -D @var{dir}
address@hidden address@hidden
address@hidden -D @var{dir}
+Specify the directory where @file{dir} resides.
+Equivalent to @address@hidden/dir}.
+
address@hidden address@hidden
address@hidden address@hidden
+Same as @address@hidden An Info directory entry is actually
+a menu item.
+
address@hidden --quiet
address@hidden --quiet
+Suppress warnings.
+
address@hidden --remove
address@hidden -r
address@hidden --remove
address@hidden -r
+Same as @samp{--delete}.
+
address@hidden address@hidden
address@hidden -s @var{sec}
address@hidden address@hidden
address@hidden -s @var{sec}
+Put this file's entries in section @var{sec} of the directory. If you
+specify more than one section, all the entries are added in each of the
+sections. If you don't specify any sections, they are determined from
+information in the Info file itself.
+
address@hidden --version
address@hidden -V
address@hidden --version
address@hidden -V
address@hidden version number, finding
+Display version information and exit successfully.
+
address@hidden table
+
+
address@hidden Command List
address@hidden @@-Command List
address@hidden Alphabetical @@-command list
address@hidden List of @@-commands
address@hidden @@-command list
address@hidden Reference to @@-commands
+
+Here is an alphabetical list of the @@-commands in Texinfo. Square
+brackets, @address@hidden address@hidden, indicate optional arguments; an
ellipsis,
address@hidden@dots{}}, indicates repeated text.
+
address@hidden 1
address@hidden @code
address@hidden @@@var{whitespace}
+An @code{@@} followed by a space, tab, or newline produces a normal,
+stretchable, interword space. @xref{Multiple Spaces}.
+
address@hidden @@!
+Generate an exclamation point that really does end a sentence (usually
+after an end-of-sentence capital letter). @xref{Ending a Sentence}.
+
address@hidden @@"
address@hidden @@'
+Generate an umlaut or acute accent, respectively, over the next
+character, as in @"o and @'o. @xref{Inserting Accents}.
+
address@hidden @@*
+Force a line break. Do not end a paragraph that uses @code{@@*} with
+an @code{@@refill} command. @xref{Line Breaks}.
+
address@hidden @@,@address@hidden@}
+Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting
+Accents}.
+
address@hidden @@-
+Insert a discretionary hyphenation point. @xref{- and hyphenation}.
+
address@hidden @@.
+Produce a period that really does end a sentence (usually after an
+end-of-sentence capital letter). @xref{Ending a Sentence}.
+
address@hidden @@:
+Indicate to @TeX{} that an immediately preceding period, question
+mark, exclamation mark, or colon does not end a sentence. Prevent
address@hidden from inserting extra whitespace as it does at the end of a
+sentence. The command has no effect on the Info file output.
address@hidden Ending a Sentence}.
+
address@hidden @@=
+Generate a macron (bar) accent over the next character, as in @=o.
address@hidden Accents}.
+
address@hidden @@?
+Generate a question mark that really does end a sentence (usually after
+an end-of-sentence capital letter). @xref{Ending a Sentence}.
+
address@hidden @@@@
+Stands for an at sign, @samp{@@}.
address@hidden Atsigns, , Inserting @@ and braces}.
+
address@hidden @@\
+Stands for a backslash (@samp{\}) inside @code{@@math}.
address@hidden,,@code{math}}.
+
address@hidden @@^
address@hidden @@`
+Generate a circumflex (hat) or grave accent, respectively, over the next
+character, as in @^o and @`e.
address@hidden Accents}.
+
address@hidden @@@{
+Stands for a left brace, @address@hidden
address@hidden Atsigns, , Inserting @@ and braces}.
+
address@hidden @@@}
+Stands for a right-hand brace, @address@hidden@*
address@hidden Atsigns, , Inserting @@ and braces}.
+
address@hidden @@~
+Generate a tilde accent over the next character, as in @~N.
address@hidden Accents}.
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Generate the uppercase and lowercase Scandinavian A-ring letters,
+respectively: @AA{}, @aa{}. @xref{Inserting Accents}.
+
address@hidden @@address@hidden@address@hidden
+Tag @var{abbrev} as an acronym, that is, an abbreviation written in all
+capital letters, such as `NASA'. @xref{acronym,, @code{acronym}}.
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Generate the uppercase and lowercase AE ligatures, respectively:
address@hidden, @ae{}. @xref{Inserting Accents}.
+
address@hidden @@afivepaper
+Change page dimensions for the A5 paper size. @xref{A4 Paper}.
+
address@hidden @@afourlatex
address@hidden @@afourpaper
address@hidden @@afourwide
+Change page dimensions for the A4 paper size. @xref{A4 Paper}.
+
address@hidden @@alias @address@hidden
+Make the command @samp{@@@var{new}} an alias for the existing command
address@hidden@@@var{existing}}. @xref{alias}.
+
address@hidden @@address@hidden@address@hidden
+Define @var{name} as the current location for use as a cross-reference
+target. @xref{anchor,, @code{@@anchor}}.
+
address@hidden @@appendix @var{title}
+Begin an appendix. The title appears in the table
+of contents of a printed manual. In Info, the title is
+underlined with asterisks. @xref{unnumbered & appendix, , The
address@hidden@@unnumbered} and @code{@@appendix} address@hidden
+
address@hidden @@appendixsec @var{title}
address@hidden @@appendixsection @var{title}
+Begin an appendix section within an appendix. The section title appears
+in the table of contents of a printed manual. In Info, the title is
+underlined with equal signs. @code{@@appendixsection} is a longer
+spelling of the @code{@@appendixsec} command. @xref{unnumberedsec
+appendixsec heading, , Section address@hidden
+
address@hidden @@appendixsubsec @var{title}
+Begin an appendix subsection within an appendix. The title appears
+in the table of contents of a printed manual. In Info, the title is
+underlined with hyphens. @xref{unnumberedsubsec appendixsubsec
+subheading, , Subsection address@hidden
+
address@hidden @@appendixsubsubsec @var{title}
+Begin an appendix subsubsection within an appendix subsection. The
+title appears in the table of contents of a printed manual. In Info,
+the title is underlined with periods. @xref{subsubsection,, The
+`subsub' address@hidden
+
address@hidden @@asis
+Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to
+print the table's first column without highlighting (``as is'').
address@hidden Tables, , Making a Two-column address@hidden
+
address@hidden @@author @var{author}
+Typeset @var{author} flushleft and underline it. @xref{title
+subtitle author, , The @code{@@title} and @code{@@author}
address@hidden
+
address@hidden @@address@hidden@address@hidden
+Print @var{text} in @b{bold} font. No effect in Info. @address@hidden
+
+
address@hidden @@address@hidden@}
+Generate a large round dot, or the closest possible
+thing to one. @xref{bullet, , @code{@@address@hidden
+
address@hidden @@bye
+Stop formatting a file. The formatters do not see the contents of a
+file following an @code{@@bye} command. @xref{Ending a address@hidden
+
address@hidden @@c @var{comment}
+Begin a comment in Texinfo. The rest of the line does not appear in
+either the Info file or the printed manual. A synonym for
address@hidden@@comment}. @xref{Comments, , address@hidden
+
address@hidden @@cartouche
+Highlight an example or quotation by drawing a box with rounded
+corners around it. Pair with @code{@@end cartouche}. No effect in
+Info. @xref{cartouche, , Drawing Cartouches Around Examples}.)@refill
+
address@hidden @@center @var{line-of-text}
+Center the line of text following the command.
address@hidden center sp, , @code{@@address@hidden
+
address@hidden @@centerchap @var{line-of-text}
+Like @code{@@chapter}, but centers the chapter title. @xref{chapter,,
address@hidden@@chapter}}.
+
address@hidden @@chapheading @var{title}
+Print a chapter-like heading in the text, but not in the table of
+contents of a printed manual. In Info, the title is underlined with
+asterisks. @xref{majorheading & chapheading, , @code{@@majorheading}
+and @code{@@address@hidden
+
address@hidden @@chapter @var{title}
+Begin a chapter. The chapter title appears in the table of
+contents of a printed manual. In Info, the title is underlined with
+asterisks. @xref{chapter, , @code{@@address@hidden
+
address@hidden @@cindex @var{entry}
+Add @var{entry} to the index of concepts. @xref{Index Entries, ,
+Defining the Entries of an address@hidden
+
address@hidden @@address@hidden@address@hidden
+Highlight the name of a book or other reference that lacks a
+companion Info file. @xref{cite, , @code{@@address@hidden
+
address@hidden @@clear @var{flag}
+Unset @var{flag}, preventing the Texinfo formatting commands from
+formatting text between subsequent pairs of @code{@@ifset @var{flag}}
+and @code{@@end ifset} commands, and preventing
address@hidden@@address@hidden@address@hidden from expanding to the value to
which
address@hidden is set.
address@hidden clear value, , @code{@@set} @code{@@clear} @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Highlight text that is an expression, a syntactically complete token
+of a program, or a program name. @xref{code, , @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate a command name, such as @command{ls}.
address@hidden,, @code{@@command}}.
+
address@hidden @@comment @var{comment}
+Begin a comment in Texinfo. The rest of the line does not appear in
+either the Info file or the printed manual. A synonym for @code{@@c}.
address@hidden
+
address@hidden @@contents
+Print a complete table of contents. Has no effect in Info, which uses
+menus instead. @xref{Contents, , Generating a Table of
address@hidden
+
address@hidden @@address@hidden@}
+Generate a copyright symbol. @xref{copyright symbol, ,
address@hidden@@address@hidden
+
+
address@hidden @@defcodeindex @var{index-name}
+Define a new index and its indexing command. Print entries in an
address@hidden@@code} font. @xref{New Indices, , Defining New
address@hidden
+
address@hidden @@defcv @var{category} @var{class} @var{name}
address@hidden @@defcvx @var{category} @var{class} @var{name}
+Format a description for a variable associated with a class in
+object-oriented programming. Takes three arguments: the category of
+thing being defined, the class to which it belongs, and its name.
address@hidden Commands}, and @ref{deffnx,, Def Cmds in Detail}.
+
address@hidden @@deffn @var{category} @var{name} @address@hidden
address@hidden @@deffnx @var{category} @var{name} @address@hidden
+Format a description for a function, interactive command, or similar
+entity that may take arguments. @code{@@deffn} takes as arguments the
+category of entity being described, the name of this particular
+entity, and its arguments, if any. @xref{Definition address@hidden
+
address@hidden @@defindex @var{index-name}
+Define a new index and its indexing command. Print entries in a roman
+font. @xref{New Indices, , Defining New address@hidden
+
address@hidden @@definfoenclose @var{newcmd}, @var{before}, @var{after},
+Create new @@-command @var{newcmd} for Info that marks text by enclosing
+it in strings that precede and follow the text. @xref{definfoenclose}.
+
address@hidden @@defivar @var{class} @var{instance-variable-name}
address@hidden @@defivarx @var{class} @var{instance-variable-name}
+This command formats a description for an instance variable in
+object-oriented programming. The command is equivalent to @samp{@@defcv
address@hidden address@hidden @dots{}}. @xref{Definition Commands}, and
address@hidden,, Def Cmds in Detail}.
+
address@hidden @@defmac @var{macroname} @address@hidden
address@hidden @@defmacx @var{macroname} @address@hidden
+Format a description for a macro. The command is equivalent to
address@hidden@@deffn Macro @dots{}}. @xref{Definition Commands}, and
address@hidden,, Def Cmds in Detail}.
+
address@hidden @@defmethod @var{class} @var{method-name} @address@hidden
address@hidden @@defmethodx @var{class} @var{method-name} @address@hidden
+Format a description for a method in object-oriented programming. The
+command is equivalent to @samp{@@defop Method @dots{}}. Takes as
+arguments the name of the class of the method, the name of the
+method, and its arguments, if any. @xref{Definition Commands}, and
address@hidden,, Def Cmds in Detail}.
+
address@hidden @@defop @var{category} @var{class} @var{name} @address@hidden
address@hidden @@defopx @var{category} @var{class} @var{name} @address@hidden
+Format a description for an operation in object-oriented programming.
address@hidden@@defop} takes as arguments the overall name of the category of
+operation, the name of the class of the operation, the name of the
+operation, and its arguments, if any. @xref{Definition
+Commands}, and @ref{Abstract Objects}.
+
address@hidden @@defopt @var{option-name}
address@hidden @@defoptx @var{option-name}
+Format a description for a user option. The command is equivalent to
address@hidden@@defvr @{User address@hidden @dots{}}. @xref{Definition
Commands}, and
address@hidden,, Def Cmds in Detail}.
+
address@hidden @@defspec @var{special-form-name} @address@hidden
address@hidden @@defspecx @var{special-form-name} @address@hidden
+Format a description for a special form. The command is equivalent to
address@hidden@@deffn @{Special address@hidden @dots{}}. @xref{Definition
Commands},
+and @ref{deffnx,, Def Cmds in Detail}.
+
address@hidden @@deftp @var{category} @var{name-of-type} @address@hidden
address@hidden @@deftpx @var{category} @var{name-of-type} @address@hidden
+Format a description for a data type. @code{@@deftp} takes as arguments
+the category, the name of the type (which is a word like @samp{int} or
address@hidden), and then the names of attributes of objects of that type.
address@hidden Commands}, and @ref{Data Types}.
+
address@hidden @@deftypefn @var{classification} @var{data-type} @var{name}
@address@hidden
address@hidden @@deftypefnx @var{classification} @var{data-type} @var{name}
@address@hidden
+Format a description for a function or similar entity that may take
+arguments and that is typed. @code{@@deftypefn} takes as arguments the
+classification of entity being described, the type, the name of the
+entity, and its arguments, if any. @xref{Definition Commands}, and
address@hidden,, Def Cmds in Detail}.
+
address@hidden @@deftypefun @var{data-type} @var{function-name} @address@hidden
address@hidden @@deftypefunx @var{data-type} @var{function-name} @address@hidden
+Format a description for a function in a typed language.
+The command is equivalent to @samp{@@deftypefn Function @dots{}}.
address@hidden Commands}, and @ref{deffnx,, Def Cmds in Detail}.
+
address@hidden @@deftypeivar @var{class} @var{data-type} @var{variable-name}
address@hidden @@deftypeivarx @var{class} @var{data-type} @var{variable-name}
+Format a description for a typed instance variable in object-oriented
+programming. @xref{Definition Commands}, and @ref{Abstract Objects}.
+
address@hidden @@deftypemethod @var{class} @var{data-type} @var{method-name}
@address@hidden
address@hidden @@deftypemethodx @var{class} @var{data-type} @var{method-name}
@address@hidden
+Format a description for a typed method in object-oriented programming.
address@hidden Commands}, and @ref{deffnx,, Def Cmds in Detail}.
+
address@hidden @@deftypeop @var{category} @var{class} @var{data-type}
@var{name} @address@hidden
address@hidden @@deftypeopx @var{category} @var{class} @var{data-type}
@var{name} @address@hidden
+Format a description for a typed operation in object-oriented programming.
address@hidden Commands}, and @ref{Abstract Objects}.
+
address@hidden @@deftypevar @var{data-type} @var{variable-name}
address@hidden @@deftypevarx @var{data-type} @var{variable-name}
+Format a description for a variable in a typed language. The command is
+equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition
+Commands}, and @ref{deffnx,, Def Cmds in Detail}.
+
address@hidden @@deftypevr @var{classification} @var{data-type} @var{name}
address@hidden @@deftypevrx @var{classification} @var{data-type} @var{name}
+Format a description for something like a variable in a typed
+language---an entity that records a value. Takes as arguments the
+classification of entity being described, the type, and the name of the
+entity. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in
+Detail}.
+
address@hidden @@defun @var{function-name} @address@hidden
address@hidden @@defunx @var{function-name} @address@hidden
+Format a description for functions. The command is equivalent to
address@hidden@@deffn Function @dots{}}. @xref{Definition Commands}, and
address@hidden,, Def Cmds in Detail}.
+
address@hidden @@defvar @var{variable-name}
address@hidden @@defvarx @var{variable-name}
+Format a description for variables. The command is equivalent to
address@hidden@@defvr Variable @dots{}}. @xref{Definition Commands}, and
address@hidden,, Def Cmds in Detail}.
+
address@hidden @@defvr @var{category} @var{name}
address@hidden @@defvrx @var{category} @var{name}
+Format a description for any kind of variable. @code{@@defvr} takes
+as arguments the category of the entity and the name of the entity.
address@hidden Commands},
+and @ref{deffnx,, Def Cmds in Detail}.
+
address@hidden @@detailmenu
+Avoid @code{makeinfo} confusion stemming from the detailed node listing
+in a master menu. @xref{Master Menu Parts}.
+
address@hidden @@address@hidden@address@hidden
+Highlight the introductory or defining use of a term.
address@hidden, , @code{@@address@hidden
+
address@hidden @@dircategory @var{dirpart}
+Specify a part of the Info directory menu where this file's entry should
+go. @xref{Installing Dir Entries}.
+
address@hidden @@direntry
+Begin the Info directory menu entry for this file. Pair with
address@hidden@@end direntry}. @xref{Installing Dir Entries}.
+
address@hidden @@display
+Begin a kind of example. Like @code{@@example} (indent text, do not
+fill), but do not select a new font. Pair with @code{@@end display}.
address@hidden, , @code{@@display}}.
+
address@hidden @@address@hidden@address@hidden
+Format a unit of measure, as in address@hidden Causes @TeX{} to insert a
+thin space before @var{dimension}. No effect in Info.
address@hidden, , @code{@@dmn}}.
+
address@hidden @@documentdescription
+Set the document description text, included in the HTML output. Pair
+with @code{@@end documentdescription}. @xref{documentdescription,,
address@hidden@@documentdescription}}.
+
address@hidden @@documentencoding @var{enc}
+Declare the input encoding to be @var{enc}.
address@hidden,, @code{@@documentencoding}}.
+
address@hidden @@documentlanguage @var{CC}
+Declare the document language as the two-character ISO-639 abbreviation
address@hidden @xref{documentlanguage,, @code{@@documentlanguage}}.
+
address@hidden @@address@hidden@address@hidden
+Generate a dot accent over the character @var{c}, as in @dotaccent{o}.
address@hidden Accents}.
+
address@hidden @@address@hidden@}
+Insert an ellipsis: @address@hidden
address@hidden, , @code{@@address@hidden
+
address@hidden @@address@hidden@var{address}[, @address@hidden
+Indicate an electronic mail address.
address@hidden, , @code{@@email}}.
+
address@hidden @@address@hidden@address@hidden
+Highlight @var{text}; text is displayed in @emph{italics} in printed
+output, and surrounded by asterisks in Info. @xref{Emphasis, ,
+Emphasizing Text}.
+
address@hidden @@end @var{environment}
+Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting
+Commands,,@@-commands}.
+
address@hidden @@address@hidden@address@hidden
+Indicate an environment variable name, such as @env{PATH}.
address@hidden,, @code{@@env}}.
+
address@hidden @@address@hidden@}
+Generate an end-of-sentence of ellipsis, like this @enddots{}
address@hidden,,@code{@@address@hidden@}}}.
+
address@hidden @@enumerate address@hidden
+Begin a numbered list, using @code{@@item} for each entry.
+Optionally, start list with @var{number-or-letter}. Pair with
address@hidden@@end enumerate}. @xref{enumerate, ,
address@hidden@@address@hidden
+
address@hidden @@address@hidden@}
+Indicate to the reader the exact equivalence of two forms with a
+glyph: @address@hidden @address@hidden
+
address@hidden @@address@hidden@}
+Indicate to the reader with a glyph that the following text is
+an error message: @address@hidden @xref{Error address@hidden
+
address@hidden @@evenfooting address@hidden @@| address@hidden @@|
address@hidden
address@hidden @@evenheading address@hidden @@| address@hidden @@|
address@hidden
+Specify page footings resp.@: headings for even-numbered (left-hand)
+pages. @xref{Custom Headings, ,
+How to Make Your Own address@hidden
+
address@hidden @@everyfooting address@hidden @@| address@hidden @@|
address@hidden
address@hidden @@everyheading address@hidden @@| address@hidden @@|
address@hidden
+Specify page footings resp.@: headings for every page. Not relevant to
+Info. @xref{Custom Headings, , How to Make Your Own address@hidden
+
address@hidden @@example
+Begin an example. Indent text, do not fill, and select fixed-width font.
+Pair with @code{@@end example}. @xref{example, ,
address@hidden@@address@hidden
+
address@hidden @@exampleindent @var{indent}
+Indent example-like environments by @var{indent} number of spaces
+(perhaps 0). @xref{exampleindent,, Paragraph Indenting}.
+
address@hidden @@address@hidden@}
+Produce an upside-down exclamation point. @xref{Inserting Accents}.
+
address@hidden @@exdent @var{line-of-text}
+Remove any indentation a line might have. @xref{exdent, ,
+Undoing the Indentation of a address@hidden
+
address@hidden @@address@hidden@}
+Indicate the result of a macro expansion to the reader with a special
+glyph: @address@hidden
address@hidden, , @expansion{} Indicating an address@hidden
+
address@hidden @@address@hidden@address@hidden
+Highlight the name of a file, buffer, node, or directory. @xref{file, ,
address@hidden@@address@hidden
+
address@hidden @@finalout
+Prevent @TeX{} from printing large black warning rectangles beside
+over-wide lines. @xref{Overfull address@hidden
+
address@hidden @@findex @var{entry}
+Add @var{entry} to the index of functions. @xref{Index Entries, ,
+Defining the Entries of an address@hidden
+
address@hidden @@flushleft
address@hidden @@flushright
+Left justify every line but leave the right end ragged.
+Leave font as is. Pair with @code{@@end flushleft}.
address@hidden@@flushright} analogous.
address@hidden & flushright, , @code{@@flushleft} and
address@hidden@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Enter a footnote. Footnote text is printed at the bottom of the page
+by @TeX{}; Info may format in either `End' node or `Separate' node style.
address@hidden@refill
+
address@hidden @@footnotestyle @var{style}
+Specify an Info file's footnote style, either @samp{end} for the end
+node style or @samp{separate} for the separate node style.
address@hidden@refill
+
address@hidden @@format
+Begin a kind of example. Like @code{@@display}, but do not narrow the
+margins. Pair with @code{@@end format}. @xref{example,,
address@hidden@@example}}.
+
address@hidden @@ftable @var{formatting-command}
+Begin a two-column table, using @code{@@item} for each entry.
+Automatically enter each of the items in the first column into the
+index of functions. Pair with @code{@@end ftable}. The same as
address@hidden@@table}, except for indexing. @xref{ftable vtable, ,
address@hidden@@ftable} and @code{@@address@hidden
+
address@hidden @@group
+Hold text together that must appear on one printed page. Pair with
address@hidden@@end group}. Not relevant to Info. @xref{group, ,
address@hidden@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}.
+
address@hidden @@heading @var{title}
+Print an unnumbered section-like heading in the text, but not in the
+table of contents of a printed manual. In Info, the title is
+underlined with equal signs. @xref{unnumberedsec appendixsec heading,
+, Section address@hidden
+
address@hidden @@headings @var{on-off-single-double}
+Turn page headings on or off, and/or specify single-sided or double-sided
+page headings for printing. @xref{headings on off, , The
address@hidden@@headings} Command}.
+
address@hidden @@html
+Enter HTML completely. Pair with @code{@@end html}. @xref{Raw
+Formatter Commands}.
+
address@hidden @@address@hidden@var{hy-phen-a-ted address@hidden
+Explicitly define hyphenation points. @xref{- and hyphenation,,
address@hidden@@-} and @code{@@hyphenation}}.
+
address@hidden @@address@hidden@address@hidden
+Print @var{text} in @i{italic} font. No effect in Info. @xref{Fonts}.
+
address@hidden @@ifclear @var{flag}
+If @var{flag} is cleared, the Texinfo formatting commands format text
+between @code{@@ifclear @var{flag}} and the following @code{@@end
+ifclear} command.
address@hidden clear value, , @code{@@set} @code{@@clear} @code{@@address@hidden
+
address@hidden @@ifhtml
address@hidden @@ifinfo
+Begin a stretch of text that will be ignored by @TeX{} when it typesets
+the printed manual. @code{@@ifhtml} text appears only in the HTML
+output. @code{@@ifinfo} output appears in both Info and (for historical
+compatibility) plain text output . Pair with @code{@@end ifhtml}
+resp.@: @code{@@end ifinfo}. @xref{Conditionals}.
+
address@hidden @@ifnothtml
address@hidden @@ifnotinfo
address@hidden @@ifnotplaintext
address@hidden @@ifnottex
+Begin a stretch of text that will be ignored in one output format but
+not the others. The text appears in the formats not specified:
address@hidden@@ifnothtml} text is omitted from html output, etc. The exception
+is @code{@@ifnotinfo} text, which is omitted from plain text output as
+well as Info output. Pair with @code{@@end ifnothtml} resp.@:
address@hidden@@end ifnotinfo} resp.@: @code{@@end ifnotplaintext} resp.@:
address@hidden@@end ifnottex}. @xref{Conditionals}.
+
address@hidden @@ifplaintext
+Begin a stretch of text that appears only in the plain text output.
+Pair with @code{@@end ifplaintext}. @xref{Conditionals}.
+
address@hidden @@ifset @var{flag}
+If @var{flag} is set, the Texinfo formatting commands format text
+between @code{@@ifset @var{flag}} and the following @code{@@end ifset}
+command.
address@hidden clear value, , @code{@@set} @code{@@clear} @code{@@address@hidden
+
address@hidden @@iftex
+Begin a stretch of text that will not appear in the Info file, but
+will be processed only by @TeX{}. Pair with @code{@@end iftex}.
address@hidden, , Conditionally Visible address@hidden
+
address@hidden @@ignore
+Begin a stretch of text that will not appear in either the Info file
+or the printed output. Pair with @code{@@end ignore}.
address@hidden, , Comments and Ignored address@hidden
+
address@hidden @@address@hidden@var{filename}, address@hidden, address@hidden,
address@hidden, address@hidden@}
+Include graphics image in external @var{filename} scaled to the given
address@hidden and/or @var{height}, using @var{alt} text and looking for
address@hidden@address@hidden in HTML. @xref{Images}.
+
address@hidden @@include @var{filename}
+Incorporate the contents of the file @var{filename} into the Info file
+or printed document. @xref{Include address@hidden
+
address@hidden @@address@hidden@var{node-name}, address@hidden, @address@hidden
+Make a cross reference to an Info file for which there is no printed
+manual. @xref{inforef, , Cross references using
address@hidden@@address@hidden
+
address@hidden \input @var{macro-definitions-file}
+Use the specified macro definitions file. This command is used only
+in the first line of a Texinfo file to cause @TeX{} to make use of the
address@hidden macro definitions file. The backslash in @code{\input}
+is used instead of an @code{@@} because @TeX{} does not
+recognize @code{@@} until after it has read the definitions file.
address@hidden File Header}.
+
address@hidden @@item
+Indicate the beginning of a marked paragraph for @code{@@itemize} and
address@hidden@@enumerate}; indicate the beginning of the text of a first column
+entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}.
address@hidden and address@hidden
+
address@hidden @@itemize @var{mark-generating-character-or-command}
+Produce a sequence of indented paragraphs, with a mark inside the left
+margin at the beginning of each paragraph. Pair with @code{@@end
+itemize}. @xref{itemize, , @code{@@address@hidden
+
address@hidden @@itemx
+Like @code{@@item} but do not generate extra vertical space above the
+item text. @xref{itemx, , @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate text that is characters of input to be typed by
+users. @xref{kbd, , @code{@@address@hidden
+
address@hidden @@kbdinputstyle @var{style}
+Specify when @code{@@kbd} should use a font distinct from @code{@@code}.
address@hidden, , @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate a name for a key on a keyboard.
address@hidden, , @code{@@address@hidden
+
address@hidden @@kindex @var{entry}
+Add @var{entry} to the index of keys.
address@hidden Entries, , Defining the Entries of an address@hidden
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Generate the uppercase and lowercase Polish suppressed-L letters,
+respectively: @L{}, @l{}.
+
address@hidden Possibly this can be tossed now that we have macros. --karl,
16sep96.
address@hidden Yes, let's toss it, it's pretty weird. --karl, 15jun97.
address@hidden @item @@global@@address@hidden@var{existing-command}
address@hidden Equate a new highlighting command with an existing one. Only for
address@hidden @TeX{}. Write definition inside of @code{@@iftex} @dots{}
@code{@@end
address@hidden iftex}. @xref{Customized address@hidden
+
address@hidden @@lisp
+Begin an example of Lisp code. Indent text, do not fill, and select
+fixed-width font. Pair with @code{@@end lisp}. @xref{lisp, , @code{@@lisp}}.
+
address@hidden @@lowersections
+Change subsequent chapters to sections, sections to subsections, and so
+on. @xref{Raise/lower sections, , @code{@@raisesections} and
address@hidden@@address@hidden
+
address@hidden @@macro @var{macroname} @address@hidden@}
+Define a new Texinfo command @code{@@@address@hidden@address@hidden
+Only supported by @code{makeinfo} and @code{texi2dvi}. @xref{Defining
+Macros}.
+
address@hidden @@majorheading @var{title}
+Print a chapter-like heading in the text, but not in the table of
+contents of a printed manual. Generate more vertical whitespace before
+the heading than the @code{@@chapheading} command. In Info, the chapter
+heading line is underlined with asterisks. @xref{majorheading &
+chapheading, , @code{@@majorheading} and @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Format a mathematical expression.
address@hidden, , @code{@@math}: Inserting Mathematical Expressions}.
+
address@hidden @@menu
+Mark the beginning of a menu of nodes in Info. No effect in a printed
+manual. Pair with @code{@@end menu}. @address@hidden
+
address@hidden @@address@hidden@}
+Generate a minus sign, address@hidden'. @xref{minus, , @code{@@address@hidden
+
address@hidden @@multitable @var{column-width-spec}
+Begin a multi-column table. Pair with @code{@@end multitable}.
address@hidden Column Widths}.
+
address@hidden @@need @var{n}
+Start a new page in a printed manual if fewer than @var{n} mils
+(thousandths of an inch) remain on the current page. @xref{need, ,
address@hidden@@address@hidden
+
address@hidden @@node @var{name}, @var{next}, @var{previous}, @var{up}
+Define the beginning of a new node in Info, and serve as a locator for
+references for @TeX{}. @xref{node, , @code{@@address@hidden
+
address@hidden @@noindent
+Prevent text from being indented as if it were a new paragraph.
address@hidden, , @code{@@address@hidden
+
address@hidden @@novalidate
+Suppress validation of node references, omit creation of auxiliary files
+with @TeX{}. Use before @code{@@setfilename}. @xref{Pointer Validation}.
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Generate the uppercase and lowercase O-with-slash letters, respectively:
address@hidden, @o{}.
+
address@hidden @@oddfooting address@hidden @@| address@hidden @@|
address@hidden
address@hidden @@oddheading address@hidden @@| address@hidden @@| address@hidden
+Specify page footings resp.@: headings for odd-numbered (right-hand)
+pages. @xref{Custom Headings, ,
+How to Make Your Own address@hidden
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Generate the uppercase and lowercase OE ligatures, respectively:
address@hidden, @oe{}. @xref{Inserting Accents}.
+
address@hidden @@address@hidden@address@hidden
+Indicate a command-line option, such as @option{-l} or @option{--help}.
address@hidden,, @code{@@option}}.
+
address@hidden @@page
+Start a new page in a printed manual. No effect in Info.
address@hidden, , @code{@@address@hidden
+
address@hidden @@pagesizes address@hidden, @var{height}]
+Change page dimensions. @xref{pagesizes}.
+
address@hidden @@paragraphindent @var{indent}
+Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve
+source file indentation if @var{indent} is @code{asis}.
address@hidden,, Paragraph Indenting}.
+
address@hidden @@pindex @var{entry}
+Add @var{entry} to the index of programs. @xref{Index Entries, , Defining
+the Entries of an address@hidden
+
address@hidden @@address@hidden@}
+Indicate the position of point in a buffer to the reader with a
+glyph: @address@hidden @xref{Point Glyph, , Indicating
+Point in a address@hidden
+
address@hidden @@address@hidden@}
+Generate the pounds sterling currency sign.
address@hidden,,@code{@@address@hidden@}}}.
+
address@hidden @@address@hidden@}
+Indicate printed output to the reader with a glyph:
address@hidden@print{}}. @xref{Print address@hidden
+
address@hidden @@printindex @var{index-name}
+Print an alphabetized two-column index in a printed manual or generate
+an alphabetized menu of index entries for Info. @xref{Printing
+Indices & address@hidden
+
address@hidden @@address@hidden@var{node-name}, address@hidden, address@hidden,
address@hidden, address@hidden@}
+Make a reference that starts with a lower case `see' in a printed
+manual. Use within parentheses only. Do not follow command with a
+punctuation mark---the Info formatting commands automatically insert
+terminating punctuation as needed. Only the first argument is mandatory.
address@hidden, , @code{@@address@hidden
+
address@hidden @@address@hidden@}
+Generate an upside-down question mark. @xref{Inserting Accents}.
+
address@hidden @@quotation
+Narrow the margins to indicate text that is quoted from another real
+or imaginary work. Write command on a line of its own. Pair with
address@hidden@@end quotation}. @xref{quotation, ,
address@hidden@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Print @var{text} in @r{roman} font. No effect in Info.
address@hidden@refill
+
address@hidden @@raisesections
+Change subsequent sections to chapters, subsections to sections, and so
+on. @xref{Raise/lower sections, , @code{@@raisesections} and
address@hidden@@address@hidden
+
address@hidden @@address@hidden@var{node-name}, address@hidden, address@hidden,
address@hidden, address@hidden@}
+Make a reference. In a printed manual, the reference does not start
+with a `See'. Follow command with a punctuation mark. Only the first
+argument is mandatory. @xref{ref, , @code{@@address@hidden
+
address@hidden @@refill
+In Info, refill and indent the paragraph after all the other processing
+has been done. No effect on @TeX{}, which always refills. This command
+is no longer needed, since all formatters now automatically refill.
address@hidden address@hidden
+
address@hidden @@address@hidden@}
+Indicate the result of an expression to the reader with a special
+glyph: @address@hidden @xref{result, , @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Generate a ring accent over the next character, as in @ringaccent{o}.
address@hidden Accents}.
+
address@hidden @@address@hidden@address@hidden
+Highlight @var{text} that is a literal example of a sequence of
+characters. Used for single characters, for statements, and often for
+entire shell commands. @xref{samp, , @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Set @var{text} in a printed output in @sc{the small caps font} and
+set text in the Info file in uppercase letters.
address@hidden@refill
+
address@hidden @@section @var{title}
+Begin a section within a chapter. In a printed manual, the section
+title is numbered and appears in the table of contents. In Info, the
+title is underlined with equal signs. @xref{section, ,
address@hidden@@address@hidden
+
address@hidden @@set @var{flag} address@hidden
+Make @var{flag} active, causing the Texinfo formatting commands to
+format text between subsequent pairs of @code{@@ifset @var{flag}} and
address@hidden@@end ifset} commands. Optionally, set value of @var{flag} to
address@hidden
address@hidden clear value, , @code{@@set} @code{@@clear} @code{@@value}}.
+
address@hidden @@setchapternewpage @var{on-off-odd}
+Specify whether chapters start on new pages, and if so, whether on
+odd-numbered (right-hand) new pages. @xref{setchapternewpage, ,
address@hidden@@setchapternewpage}}.
+
address@hidden @@setcontentsaftertitlepage
+Put the table of contents after the @samp{@@end titlepage} even if the
address@hidden@@contents} command is not there. @xref{Contents}.
+
address@hidden @@setfilename @var{info-file-name}
+Provide a name to be used by the Info file. This command is essential
+for @TeX{} formatting as well, even though it produces no output.
address@hidden, , @code{@@setfilename}}.
+
address@hidden @@setshortcontentsaftertitlepage
+Place the short table of contents after the @samp{@@end titlepage}
+command even if the @code{@@shortcontents} command is not there.
address@hidden
+
address@hidden @@settitle @var{title}
+Provide a title for page headers in a printed manual, and the default
+document description for HTML @samp{<head>}.
address@hidden, , @code{@@address@hidden
+
address@hidden @@shortcontents
+Print a short table of contents. Not relevant to Info, which uses
+menus rather than tables of contents. A synonym for
address@hidden@@summarycontents}. @xref{Contents, , Generating a Table of
address@hidden
+
address@hidden @@shorttitlepage @var{title}
+Generate a minimal title page. @xref{titlepage,,@code{@@titlepage}}.
+
address@hidden @@smallbook
+Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format
+rather than the regular 8.5 by 11 inch format. @xref{smallbook, ,
+Printing Small Books}. Also, see @ref{small}.
+
address@hidden @@smalldisplay
+Begin a kind of example. Like @code{@@smallexample} (narrow margins, no
+filling), but do not select the fixed-width font. Pair with @code{@@end
+smalldisplay}. @xref{small}.
+
address@hidden @@smallexample
+Indent text to indicate an example. Do not fill, select fixed-width
+font, narrow the margins. In printed manuals, print text in a smaller
+font than with @code{@@example}. Pair with @code{@@end smallexample}.
address@hidden
+
address@hidden @@smallformat
+Begin a kind of example. Like @code{@@smalldisplay}, but do not narrow
+the margins. Pair with @code{@@end smallformat}. @xref{small}.
+
address@hidden @@smalllisp
+Begin an example of Lisp code. Same as @code{@@smallexample}. Pair
+with @code{@@end smalllisp}. @xref{small}.
+
address@hidden @@sp @var{n}
+Skip @var{n} blank lines. @xref{sp, , @code{@@address@hidden
+
address@hidden @@address@hidden@}
+Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}.
+
address@hidden @@strong @address@hidden@}
+Emphasize @var{text} by typesetting it in a @strong{bold} font for the
+printed manual and by surrounding it with asterisks for Info.
address@hidden & strong, , Emphasizing address@hidden
+
address@hidden @@subheading @var{title}
+Print an unnumbered subsection-like heading in the text, but not in
+the table of contents of a printed manual. In Info, the title is
+underlined with hyphens. @xref{unnumberedsubsec appendixsubsec
+subheading, , @code{@@unnumberedsubsec} @code{@@appendixsubsec}
address@hidden@@address@hidden
+
address@hidden @@subsection @var{title}
+Begin a subsection within a section. In a printed manual, the
+subsection title is numbered and appears in the table of contents. In
+Info, the title is underlined with hyphens. @xref{subsection, ,
address@hidden@@address@hidden
+
address@hidden @@subsubheading @var{title}
+Print an unnumbered subsubsection-like heading in the text, but not in
+the table of contents of a printed manual. In Info, the title is
+underlined with periods. @xref{subsubsection, , The `subsub'
address@hidden
+
address@hidden @@subsubsection @var{title}
+Begin a subsubsection within a subsection. In a printed manual,
+the subsubsection title is numbered and appears in the table of
+contents. In Info, the title is underlined with periods.
address@hidden, , The `subsub' address@hidden
+
address@hidden @@subtitle @var{title}
+In a printed manual, set a subtitle in a normal sized font flush to
+the right-hand side of the page. Not relevant to Info, which does not
+have title pages. @xref{title subtitle author, , @code{@@title}
address@hidden@@subtitle} and @code{@@author} address@hidden
+
address@hidden @@summarycontents
+Print a short table of contents. Not relevant to Info, which uses
+menus rather than tables of contents. A synonym for
address@hidden@@shortcontents}. @xref{Contents, , Generating a Table of
address@hidden
+
address@hidden @@syncodeindex @var{from-index} @var{into-index}
+Merge the index named in the first argument into the index named in
+the second argument, printing the entries from the first index in
address@hidden@@code} font. @xref{Combining address@hidden
+
address@hidden @@synindex @var{from-index} @var{into-index}
+Merge the index named in the first argument into the index named in
+the second argument. Do not change the font of @var{from-index}
+entries. @xref{Combining address@hidden
+
address@hidden @@address@hidden@address@hidden
+Print @var{text} in a @t{fixed-width}, typewriter-like font.
+No effect in Info. @address@hidden
+
address@hidden @@tab
+Separate columns in a multitable. @xref{Multitable Rows}.
+
address@hidden @@table @var{formatting-command}
+Begin a two-column table, using @code{@@item} for each entry. Write
+each first column entry on the same line as @code{@@item}. First
+column entries are printed in the font resulting from
address@hidden Pair with @code{@@end table}.
address@hidden Tables, , Making a Two-column Table}.
+Also see @ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}},
+and @ref{itemx, , @code{@@address@hidden
+
address@hidden @@address@hidden@}
+Insert the logo @TeX{}. @xref{TeX and copyright, , Inserting @TeX{}
+and @address@hidden
+
address@hidden @@tex
+Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Raw
+Formatter Commands}.
+
address@hidden @@thischapter
address@hidden @@thischaptername
address@hidden @@thisfile
address@hidden @@thispage
address@hidden @@thistitle
+Only allowed in a heading or footing. Stands for the number and name of
+the current chapter (in the format `Chapter 1: Title'), the chapter name
+only, the filename, the current page number, and the title of the
+document, respectively. @xref{Custom Headings, , How to Make Your Own
address@hidden
+
address@hidden @@address@hidden@address@hidden
+Generate a tie-after accent over the next two characters @var{cc}, as in
address@hidden'. @xref{Inserting Accents}.
+
address@hidden @@tindex @var{entry}
+Add @var{entry} to the index of data types. @xref{Index Entries, ,
+Defining the Entries of an address@hidden
+
address@hidden @@title @var{title}
+In a printed manual, set a title flush to the left-hand side of the
+page in a larger than normal font and underline it with a black rule.
+Not relevant to Info, which does not have title pages. @xref{title
+subtitle author, , The @code{@@title} @code{@@subtitle} and
address@hidden@@author} address@hidden
+
address@hidden @@address@hidden@address@hidden
+In a printed manual, print @var{text} in a larger than normal font.
+Not relevant to Info, which does not have title pages.
address@hidden center sp, , The @code{@@titlefont} @code{@@center}
+and @code{@@sp} address@hidden
+
address@hidden @@titlepage
+Indicate to Texinfo the beginning of the title page. Write command on
+a line of its own. Pair with @code{@@end titlepage}. Nothing between
address@hidden@@titlepage} and @code{@@end titlepage} appears in Info.
address@hidden, , @code{@@address@hidden
+
address@hidden @@address@hidden@}
+Insert the current date, in `1 Jan 1900' style. @xref{Custom
+Headings, , How to Make Your Own address@hidden
+
address@hidden @@top @var{title}
+In a Texinfo file to be formatted with @code{makeinfo}, identify the
+topmost @code{@@node} in the file, which must be written on the line
+immediately preceding the @code{@@top} command. Used for
address@hidden's node pointer insertion feature. The title is
+underlined with asterisks. Both the @code{@@node} line and the @code{@@top}
+line normally should be enclosed by @code{@@ifnottex} and @code{@@end
+ifnottex}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
+command is merely a synonym for @code{@@unnumbered}. @xref{makeinfo
+Pointer Creation, , Creating Pointers with @code{makeinfo}}.
+
address@hidden @@address@hidden@address@hidden
address@hidden @@address@hidden@address@hidden
address@hidden @@address@hidden@address@hidden
+Generate a breve, underbar, or underdot accent, respectively, over or
+under the character @var{c}, as in @u{o}, @ubaraccent{o},
address@hidden @xref{Inserting Accents}.
+
address@hidden @@unnumbered @var{title}
+In a printed manual, begin a chapter that appears without chapter
+numbers of any kind. The title appears in the table of contents of a
+printed manual. In Info, the title is underlined with asterisks.
address@hidden & appendix, , @code{@@unnumbered} and
address@hidden@@address@hidden
+
address@hidden @@unnumberedsec @var{title}
+In a printed manual, begin a section that appears without section
+numbers of any kind. The title appears in the table of contents of a
+printed manual. In Info, the title is underlined with equal signs.
address@hidden appendixsec heading, , Section address@hidden
+
address@hidden @@unnumberedsubsec @var{title}
+In a printed manual, begin an unnumbered subsection within a
+chapter. The title appears in the table of contents of a printed
+manual. In Info, the title is underlined with hyphens.
address@hidden appendixsubsec subheading, ,
address@hidden@@unnumberedsubsec} @code{@@appendixsubsec}
address@hidden@@address@hidden
+
address@hidden @@unnumberedsubsubsec @var{title}
+In a printed manual, begin an unnumbered subsubsection within a
+chapter. The title appears in the table of contents of a printed
+manual. In Info, the title is underlined with periods.
address@hidden, , The `subsub' address@hidden
+
address@hidden @@address@hidden@var{url}[, @var{displayed-text}][,
@address@hidden
+Define a cross reference to an external uniform resource locator for the
+World Wide Web. @xref{uref, , @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate text that is a uniform resource locator for the World Wide
+Web. @xref{url, , @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Generate check accent over the character @var{c}, as in @v{o}.
address@hidden Accents}.
+
address@hidden @@address@hidden@address@hidden
+Replace @var{flag} with the value to which it is set by @code{@@set
address@hidden
address@hidden clear value, , @code{@@set} @code{@@clear} @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Highlight a metasyntactic variable, which is something that stands for
+another piece of text. @xref{var, , Indicating Metasyntactic
address@hidden
+
address@hidden @@address@hidden@var{delim} @var{literal} @address@hidden
+Output @var{literal}, delimited by the single character @var{delim},
+exactly as is (in the fixed-width font), including any whitespace or
+Texinfo special characters. @xref{verb,,@code{verb}}.
+
address@hidden @@verbatim
+Output the text of the environment exactly as is (in the fixed-width
+font). Pair with @code{@@end verbatim}. @xref{verbatim,,@code{verbatim}}.
+
address@hidden @@verbatiminclude @var{filename}
+Output the contents of @var{filename} exactly as is (in the fixed-width font).
address@hidden,,@code{verbatiminclude}}.
+
address@hidden @@vindex @var{entry}
+Add @var{entry} to the index of variables. @xref{Index Entries, ,
+Defining the Entries of an address@hidden
+
address@hidden @@vskip @var{amount}
+In a printed manual, insert whitespace so as to push text on the
+remainder of the page towards the bottom of the page. Used in
+formatting the copyright page with the argument @samp{0pt plus
+1filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used
+only in contexts ignored for Info. @xref{Copyright}.
+
address@hidden @@vtable @var{formatting-command}
+Begin a two-column table, using @code{@@item} for each entry.
+Automatically enter each of the items in the first column into the
+index of variables. Pair with @code{@@end vtable}. The same as
address@hidden@@table}, except for indexing. @xref{ftable vtable, ,
address@hidden@@ftable} and @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Prevent @var{text} from being split across two lines. Do not end a
+paragraph that uses @code{@@w} with an @code{@@refill} command.
address@hidden, , @code{@@address@hidden
+
address@hidden @@address@hidden@var{node-name}, address@hidden, address@hidden,
address@hidden, address@hidden@}
+Make a reference that starts with `See' in a printed manual. Follow
+command with a punctuation mark. Only the first argument is
+mandatory. @xref{xref, , @code{@@address@hidden
address@hidden table
+
+
address@hidden Tips
address@hidden Tips and Hints
+
+Here are some tips for writing Texinfo documentation:@refill
+
address@hidden Tips
address@hidden Usage tips
address@hidden Hints
address@hidden @bullet
address@hidden
+Write in the present tense, not in the past or the future.
+
address@hidden
+Write actively! For example, write ``We recommend that @dots{}'' rather
+than ``It is recommended that @dots{}''.
+
address@hidden
+Use 70 or 72 as your fill column. Longer lines are hard to read.
+
address@hidden
+Include a copyright notice and copying permissions.
address@hidden itemize
+
address@hidden Index, Index, Index!
+
+Write many index entries, in different ways.
+Readers like indices; they are helpful and convenient.
+
+Although it is easiest to write index entries as you write the body of
+the text, some people prefer to write entries afterwards. In either
+case, write an entry before the paragraph to which it applies. This
+way, an index entry points to the first page of a paragraph that is
+split across pages.
+
+Here are more hints we have found valuable:
+
address@hidden @bullet
address@hidden
+Write each index entry differently, so each entry refers to a different
+place in the document.
+
address@hidden
+Write index entries only where a topic is discussed significantly. For
+example, it is not useful to index ``debugging information'' in a
+chapter on reporting bugs. Someone who wants to know about debugging
+information will certainly not find it in that chapter.
+
address@hidden
+Consistently capitalize the first word of every concept index entry,
+or else consistently use lower case. Terse entries often call for
+lower case; longer entries for capitalization. Whichever case
+convention you use, please use one or the other consistently! Mixing
+the two styles looks bad.
+
address@hidden
+Always capitalize or use upper case for those words in an index for
+which this is proper, such as names of countries or acronyms. Always
+use the appropriate case for case-sensitive names, such as those in C or
+Lisp.
+
address@hidden
+Write the indexing commands that refer to a whole section immediately
+after the section command, and write the indexing commands that refer to
+a paragraph before that paragraph.
+
+In the example that follows, a blank line comes after the index
+entry for ``Leaping'':
+
address@hidden
address@hidden
+@@section The Dog and the Fox
+@@cindex Jumping, in general
+@@cindex Leaping
+
+@@cindex Dog, lazy, jumped over
+@@cindex Lazy dog jumped over
+@@cindex Fox, jumps over dog
+@@cindex Quick fox jumps over dog
+The quick brown fox jumps over the lazy dog.
address@hidden group
address@hidden example
+
address@hidden
+(Note that the example shows entries for the same concept that are
+written in different address@hidden dog}, and @samp{Dog, lazy}---so
+readers can look up the concept in different ways.)
address@hidden itemize
+
address@hidden Blank Lines
+
address@hidden @bullet
address@hidden
+Insert a blank line between a sectioning command and the first following
+sentence or paragraph, or between the indexing commands associated with
+the sectioning command and the first following sentence or paragraph, as
+shown in the tip on indexing. Otherwise, a formatter may fold title and
+paragraph together.
+
address@hidden
+Always insert a blank line before an @code{@@table} command and after an
address@hidden@@end table} command; but never insert a blank line after an
address@hidden@@table} command or before an @code{@@end table} command.
+
address@hidden 1000
+For example,
+
address@hidden
address@hidden
+Types of fox:
+
+@@table @@samp
+@@item Quick
+Jump over lazy dogs.
address@hidden group
+
address@hidden
+@@item Brown
+Also jump over lazy dogs.
+@@end table
+
address@hidden group
address@hidden
+@@noindent
+On the other hand, @dots{}
address@hidden group
address@hidden example
+
+Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end
+itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the
+same way.
address@hidden itemize
+
address@hidden Complete Phrases
+
+Complete phrases are easier to read than @dots{}
+
address@hidden @bullet
address@hidden
+Write entries in an itemized list as complete sentences; or at least, as
+complete phrases. Incomplete expressions @dots{} awkward @dots{} like
+this.
+
address@hidden
+Write the prefatory sentence or phrase for a multi-item list or table as
+a complete expression. Do not write ``You can set:''; instead, write
+``You can set these variables:''. The former expression sounds cut off.
address@hidden itemize
+
address@hidden Editions, Dates and Versions
+
+Include edition numbers, version numbers, and dates in the
address@hidden@@copying} text (for people reading the Texinfo file, and for the
+legal copyright in the output files). Then use @code{@@insertcopying}
+in the @code{@@titlepage} section (for people reading the printed
+output) and the Top node (for people reading the online output).
+
+It is easiest to do this using @code{@@set} and @code{@@value}.
address@hidden Example, , @code{@@value} Example}, and @ref{GNU Sample Texts}.
+
+
address@hidden Definition Commands
+
+Definition commands are @code{@@deffn}, @code{@@defun},
address@hidden@@defmac}, and the like, and enable you to write descriptions in
+a uniform address@hidden
+
address@hidden @bullet
address@hidden
+Write just one definition command for each entity you define with a
+definition command. The automatic indexing feature creates an index
+entry that leads the reader to the definition.
+
address@hidden
+Use @code{@@table} @dots{} @code{@@end table} in an appendix that
+contains a summary of functions, not @code{@@deffn} or other definition
+commands.
address@hidden itemize
+
address@hidden Capitalization
+
address@hidden @bullet
address@hidden
+Capitalize ``Texinfo''; it is a name. Do not write the @samp{x} or
address@hidden in upper case.
+
address@hidden
+Capitalize ``Info''; it is a name.
+
address@hidden
+Write @TeX{} using the @code{@@address@hidden@}} command. Note the uppercase
address@hidden and @samp{X}. This command causes the formatters to
+typeset the name according to the wishes of Donald Knuth, who wrote
address@hidden
address@hidden itemize
+
address@hidden Spaces
+
+Do not use spaces to format a Texinfo file, except inside of
address@hidden@@example} @dots{} @code{@@end example} and similar commands.
+
address@hidden 700
+For example, @TeX{} fills the following:
+
address@hidden
address@hidden
+ @@address@hidden address@hidden
+ @@address@hidden address@hidden
+ Perform the next logical operation
+ on the version-controlled file
+ corresponding to the current buffer.
address@hidden group
address@hidden example
+
address@hidden 950
address@hidden
+so it looks like this:
+
address@hidden
+`C-x v' `M-x vc-next-action' Perform the next logical operation on the
+version-controlled file corresponding to the current buffer.
address@hidden quotation
+
address@hidden
+In this case, the text should be formatted with
address@hidden@@table}, @code{@@item}, and @code{@@itemx}, to create a table.
+
address@hidden @@code, @@samp, @@var, and @samp{---}
+
address@hidden @bullet
address@hidden
+Use @code{@@code} around Lisp symbols, including command names.
+For example,
+
address@hidden
+The main function is @@address@hidden@}, @dots{}
address@hidden example
+
address@hidden
+Avoid putting letters such as @samp{s} immediately after an
address@hidden@@code}. Such letters look bad.
+
address@hidden
+Use @code{@@var} around meta-variables. Do not write angle brackets
+around them.
+
address@hidden
+Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{}
+typesets these as a long dash and the Info formatters reduce three
+hyphens to two.
address@hidden itemize
+
address@hidden Periods Outside of Quotes
+
+Place periods and other punctuation marks @emph{outside} of quotations,
+unless the punctuation is part of the quotation. This practice goes
+against publishing conventions in the United States, but enables the
+reader to distinguish between the contents of the quotation and the
+whole passage.
+
+For example, you should write the following sentence with the period
+outside the end quotation marks:
+
address@hidden
+Evidently, @samp{au} is an abbreviation for ``author''.
address@hidden example
+
address@hidden
+since @samp{au} does @emph{not} serve as an abbreviation for
address@hidden (with a period following the word).
+
address@hidden Introducing New Terms
+
address@hidden @bullet
address@hidden
+Introduce new terms so that a reader who does not know them can
+understand them from context; or write a definition for the term.
+
+For example, in the following, the terms ``check in'', ``register'' and
+``delta'' are all appearing for the first time; the example sentence should be
+rewritten so they are understandable.
+
address@hidden
+The major function assists you in checking in a file to your
+version control system and registering successive sets of changes to
+it as deltas.
address@hidden quotation
+
address@hidden
+Use the @code{@@dfn} command around a word being introduced, to indicate
+that the reader should not expect to know the meaning already, and
+should expect to learn the meaning from this passage.
address@hidden itemize
+
address@hidden @@pxref
+
address@hidden !!! maybe include this in the tips on pxref
+Absolutely never use @code{@@pxref} except in the special context for
+which it is designed: inside parentheses, with the closing parenthesis
+following immediately after the closing brace. One formatter
+automatically inserts closing punctuation and the other does not. This
+means that the output looks right both in printed output and in an Info
+file, but only when the command is used inside parentheses.
+
address@hidden Invoking from a Shell
+
+You can invoke programs such as Emacs, GCC, and @code{gawk} from a
+shell. The documentation for each program should contain a section that
+describes this. Unfortunately, if the node names and titles for these
+sections are all different, they are difficult for users to find.
+
+So, there is a convention to name such sections with a phrase beginning
+with the word `Invoking', as in `Invoking Emacs'; this way, users can
+find the section easily.
+
+
address@hidden ANSI C Syntax
+
+When you use @code{@@example} to describe a C function's calling
+conventions, use the ANSI C syntax, like this:@refill
+
address@hidden
+void dld_init (char *@@address@hidden@});
address@hidden example
+
address@hidden
+And in the subsequent discussion, refer to the argument values by
+writing the same argument names, again highlighted with
address@hidden@@address@hidden
+
address@hidden 800
+Avoid the obsolete style that looks like this:@refill
+
address@hidden
+#include <dld.h>
+
+dld_init (path)
+char *path;
address@hidden example
+
+Also, it is best to avoid writing @code{#include} above the
+declaration just to indicate that the function is declared in a
+header file. The practice may give the misimpression that the
address@hidden belongs near the declaration of the function. Either
+state explicitly which header file holds the declaration or, better
+yet, name the header file used for a group of functions at the
+beginning of the section that describes the address@hidden
+
address@hidden Bad Examples
+
+Here are several examples of bad writing to avoid:
+
+In this example, say, `` @dots{} you must @code{@@address@hidden
address@hidden the new version.'' That flows better.
+
address@hidden
+When you are done editing the file, you must perform a
address@hidden@@address@hidden address@hidden
address@hidden quotation
+
+In the following example, say, address@hidden makes a unified interface such
as VC
+mode possible.''
+
address@hidden
+SCCS, RCS and other version-control systems all perform similar
+functions in broadly similar ways (it is this resemblance which makes
+a unified control mode like this possible).
address@hidden quotation
+
+And in this example, you should specify what `it' refers to:
+
address@hidden
+If you are working with other people, it assists in coordinating
+everyone's changes so they do not step on each other.
address@hidden quotation
+
address@hidden And Finally @dots{}
+
address@hidden @bullet
address@hidden
+Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last
+sound in the name `Bach'. But pronounce Texinfo as in `speck':
+``teckinfo''.
+
address@hidden
+Write notes for yourself at the very end of a Texinfo file after the
address@hidden@@bye}. None of the formatters process text after the
address@hidden@@bye}; it is as if the text were within @code{@@ignore} @dots{}
address@hidden@@end ignore}.
address@hidden itemize
+
+
address@hidden Sample Texinfo Files
address@hidden Sample Texinfo Files
address@hidden Sample Texinfo files
+
+The first example is from the first chapter (@pxref{Short Sample}),
+given here in its entirety, without commentary. The second sample
+includes the full texts to be used in GNU manuals.
+
address@hidden
+* Short Sample Texinfo File::
+* GNU Sample Texts::
address@hidden menu
+
+
address@hidden Short Sample Texinfo File
address@hidden Short Sample
address@hidden Sample Texinfo file, no comments
+
+Here is a complete, short sample Texinfo file, without any commentary.
+You can see this file, with comments, in the first chapter. @xref{Short
+Sample}.
+
+In a nutshell: The @command{makeinfo} program transforms a Texinfo
+source file such as this into an Info file or HTML; and @TeX{} typesets
+it for a printed manual.
+
+
address@hidden 1
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename sample.info
+@@settitle Sample Manual 1.0
+@@c %**end of header
+
+@@copying
+This is a short example of a complete Texinfo file.
+
+Copyright (C) 2002 Free Software Foundation, Inc.
+@@end copying
+
+@@titlepage
+@@title Sample Title
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
+@@end titlepage
+
+@@c Output the table of the contents at the beginning.
+@@contents
+
+@@ifnottex
+@@node Top
+
+@@insertcopying
+@@end ifnottex
+
+@@menu
+* First Chapter:: The first chapter is the
+ only chapter in this sample.
+* Index:: Complete index.
+@@end menu
+
+
+@@node First Chapter
+@@chapter First Chapter
+
+@@cindex chapter, first
+
+This is the first chapter.
+@@cindex index entry, another
+
+Here is a numbered list.
+
+@@enumerate
+@@item
+This is the first item.
+
+@@item
+This is the second item.
+@@end enumerate
+
+
+@@node Index
+@@unnumbered Index
+
+@@printindex cp
+
+@@bye
address@hidden example
+
+
address@hidden GNU Sample Texts
address@hidden GNU Sample Texts
+
address@hidden GNU sample texts
address@hidden Sample texts, GNU
address@hidden Full texts, GNU
+
+Here 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.
+
address@hidden Sample}, for a minimal example of a Texinfo file.
address@hidden a File}, for a full explanation of that minimal
+example.
+
+Here are some notes on the example:
+
address@hidden @bullet
address@hidden
address@hidden $ @c Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $
comment
address@hidden CVS Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $, in
Texinfo
address@hidden RCS Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $, in
Texinfo
+The @samp{Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $} comment is
for CVS (@pxref{Top,, Overview, cvs,
+Concurrent Versions System}) or RCS (see rcsintro(1)) version control
+systems, which expand it into a string such as:
address@hidden
+Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $
address@hidden example
+(This is useful in all sources that use version control, not just manuals.)
+
address@hidden
address@hidden address@hidden, and version info}
+The @file{version.texi} in the @code{@@include} command is maintained
+automatically by Automake (@pxref{Top,, Introduction, automake, GNU
+Automake}). It sets the @samp{VERSION} and @samp{UPDATED} values used
+elsewhere. If your distribution doesn't use Automake, you can mimic
+these or equivalent settings.
+
address@hidden
+The @code{@@syncodeindex} command reflects the recommendation to use only
+one index if at all possible, to make it easier for readers.
+
address@hidden
+The @code{@@dircategory} is for constructing the Info directory.
address@hidden Dir Entries}, which includes a variety of recommended
+category names.
+
address@hidden
+The `Invoking' node is a GNU standard to help users find the basic
+information about command-line usage of a given program. @xref{Manual
+Structure Details,,,standards, GNU Coding Standards}.
+
address@hidden
+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 of doing so. The @file{fdl.texi}
+file is available on the GNU machines (and in the Texinfo and other GNU
+distributions).
+
+The FDL provides for omitting itself under certain conditions, but in
+that case the sample texts given here have to be modified. @xref{GNU
+Free Documentation License}.
+
address@hidden
+If your manual has invariant sections (again, see the license itself for
+details), then don't forget to include them.
address@hidden itemize
+
+Here is the sample document:
+
address@hidden We do the first part of this with @example instead of @verbatim
address@hidden because the literal @setfilename and @include confuse Automake.
Argh.
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@comment Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $
+@@comment %**start of header
+@@setfilename sample.info
+@@include version.texi
+@@settitle GNU Sample @@address@hidden@}
+@@syncodeindex pg cp
+@@comment %**end of header
+@@copying
+This manual is for GNU Sample
+(version @@address@hidden@}, @@address@hidden@}),
+which is an example in the Texinfo documentation.
+
+Copyright @@address@hidden@} 2002 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 @@address@hidden@}, @@address@hidden@}
+@@author A.U. Thor (@@address@hidden@@@@address@hidden)
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
+@@end titlepage
+
+@@contents
+
+@@ifnottex
+@@node Top
+@@top GNU Sample
+
+@@insertcopying
+@@end ifnottex
+
+@@menu
+* Invoking sample::
+* Copying This Manual::
+* Index::
+@@end menu
+
+
+@@node Invoking sample
+@@chapter Invoking sample
+
+@@pindex sample
+@@cindex invoking @@address@hidden@}
+
+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
address@hidden example
+
+
address@hidden Include Files
address@hidden Include Files
address@hidden Include files
+
+When @TeX{} or an Info formatting command sees an @code{@@include}
+command in a Texinfo file, it processes the contents of the file named
+by the command and incorporates them into the DVI or Info file being
+created. Index entries from the included file are incorporated into
+the indices of the output file.
+
+Include files let you keep a single large document as a collection of
+conveniently small parts.
+
address@hidden
+* Using Include Files:: How to use the @code{@@include} command.
+* texinfo-multiple-files-update:: How to create and update nodes and
+ menus when using included files.
+* Include File Requirements:: What @code{texinfo-multiple-files-update}
expects.
+* 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.
address@hidden menu
+
address@hidden Using Include Files, texinfo-multiple-files-update, Include
Files, Include Files
address@hidden How to Use Include Files
address@hidden include
+
+To include another file within a Texinfo file, write the
address@hidden@@include} command at the beginning of a line and follow it on
+the same line by the name of a file to be included. For
+example:@refill
+
address@hidden
+@@include buffers.texi
address@hidden example
+
+An included file should simply be a segment of text that you expect to
+be included as is into the overall or @dfn{outer} Texinfo file; it
+should not contain the standard beginning and end parts of a Texinfo
+file. In particular, you should not start an included file with a
+line saying @samp{\input texinfo}; if you do, that phrase is inserted
+into the output file as is. Likewise, you should not end an included
+file with an @code{@@bye} command; nothing after @code{@@bye} is
address@hidden
+
+In the past, you were required to write an @code{@@setfilename} line at the
+beginning of an included file, but no longer. Now, it does not matter
+whether you write such a line. If an @code{@@setfilename} line exists
+in an included file, it is address@hidden
+
+Conventionally, an included file begins with an @code{@@node} line that
+is followed by an @code{@@chapter} line. Each included file is one
+chapter. This makes it easy to use the regular node and menu creating
+and updating commands to create the node pointers and menus within the
+included file. However, the simple Emacs node and menu creating and
+updating commands do not work with multiple Texinfo files. Thus you
+cannot use these commands to fill in the `Next', `Previous', and `Up'
+pointers of the @code{@@node} line that begins the included file. Also,
+you cannot use the regular commands to create a master menu for the
+whole file. Either you must insert the menus and the `Next',
+`Previous', and `Up' pointers by hand, or you must use the GNU Emacs
+Texinfo mode command, @code{texinfo-multiple-files-update}, that is
+designed for @code{@@include} address@hidden
+
address@hidden texinfo-multiple-files-update, Include File Requirements, Using
Include Files, Include Files
address@hidden @code{texinfo-multiple-files-update}
address@hidden texinfo-multiple-files-update
+
+GNU Emacs Texinfo mode provides the @code{texinfo-multiple-files-update}
+command. This command creates or updates `Next', `Previous', and `Up'
+pointers of included files as well as those in the outer or overall
+Texinfo file, and it creates or updates a main menu in the outer file.
+Depending whether you call it with optional arguments, the command
+updates only the pointers in the first @code{@@node} line of the
+included files or all of them:@refill
+
address@hidden @kbd
address@hidden M-x texinfo-multiple-files-update
+Called without any arguments:@refill
+
address@hidden @minus
address@hidden
+Create or update the `Next', `Previous', and `Up' pointers of the
+first @code{@@node} line in each file included in an outer or overall
+Texinfo address@hidden
+
address@hidden
+Create or update the `Top' level node pointers of the outer or
+overall address@hidden
+
address@hidden
+Create or update a main menu in the outer address@hidden
address@hidden itemize
+
address@hidden C-u M-x texinfo-multiple-files-update
+Called with @kbd{C-u} as a prefix argument:
+
address@hidden @minus{}
address@hidden
+Create or update pointers in the first @code{@@node} line in each
+included file.
+
address@hidden
+Create or update the `Top' level node pointers of the outer file.
+
address@hidden
+Create and insert a master menu in the outer file. The master menu
+is made from all the menus in all the included address@hidden
address@hidden itemize
+
address@hidden C-u 8 M-x texinfo-multiple-files-update
+Called with a numeric prefix argument, such as @kbd{C-u 8}:
+
address@hidden @minus
address@hidden
+Create or update @strong{all} the `Next', `Previous', and `Up' pointers
+of all the included address@hidden
+
address@hidden
+Create or update @strong{all} the menus of all the included
address@hidden
+
address@hidden
+Create or update the `Top' level node pointers of the outer or
+overall address@hidden
+
address@hidden
+And then create a master menu in the outer file. This is similar to
+invoking @code{texinfo-master-menu} with an argument when you are
+working with just one address@hidden
address@hidden itemize
address@hidden table
+
+Note the use of the prefix argument in interactive use: with a regular
+prefix argument, just @address@hidden, the
address@hidden command inserts a master menu;
+with a numeric prefix argument, such as @kbd{C-u 8}, the command
+updates @strong{every} pointer and menu in @strong{all} the files and then
inserts a
+master address@hidden
+
+
address@hidden Include File Requirements
address@hidden Include File Requirements
address@hidden Include file requirements
address@hidden Requirements for include files
+
+If you plan to use the @code{texinfo-multiple-files-update} command,
+the outer Texinfo file that lists included files within it should
+contain nothing but the beginning and end parts of a Texinfo file, and
+a number of @code{@@include} commands listing the included files. It
+should not even include indices, which should be listed in an included
+file of their address@hidden
+
+Moreover, each of the included files must contain exactly one highest
+level node (conventionally, @code{@@chapter} or equivalent),
+and this node must be the first node in the included file.
+Furthermore, each of these highest level nodes in each included file
+must be at the same hierarchical level in the file structure.
+Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an
address@hidden@@unnumbered} node. Thus, normally, each included file contains
+one, and only one, chapter or equivalent-level address@hidden
+
+The outer file should contain only @emph{one} node, the `Top' node. It
+should @emph{not} contain any nodes besides the single `Top' node. The
address@hidden command will not process
address@hidden
+
address@hidden Sample Include File, Include Files Evolution, Include File
Requirements, Include Files
address@hidden Sample File with @code{@@include}
address@hidden Sample @code{@@include} file
address@hidden Include file sample
address@hidden @code{@@include} file sample
+
+Here is an example of a complete outer Texinfo file with @code{@@include} files
+within it before running @code{texinfo-multiple-files-update}, which
+would insert a main or master menu:@refill
+
address@hidden
address@hidden
+\input texinfo @@c -*-texinfo-*-
address@hidden %**start of header
+@@setfilename include-example.info
+@@settitle Include Example
address@hidden %**end of header
address@hidden group
+
address@hidden
+@@setchapternewpage odd
+@@titlepage
+@@sp 12
+@@center @@address@hidden address@hidden
+@@sp 2
+@@center by Whom Ever
address@hidden group
+
address@hidden
+@@page
+@@vskip 0pt plus 1filll
+Copyright @@address@hidden@} 2002 Free Software Foundation, Inc.
+@@end titlepage
address@hidden group
+
address@hidden
+@@ifinfo
+@@node Top, First, , (dir)
+@@top Master Menu
+@@end ifinfo
address@hidden group
+
address@hidden
+@@include foo.texinfo
+@@include bar.texinfo
+@@include concept-index.texinfo
address@hidden group
+
address@hidden
+@@summarycontents
+@@contents
+
+@@bye
address@hidden group
address@hidden example
+
+An included file, such as @file{foo.texinfo}, might look like this:
+
address@hidden
address@hidden
+@@node First, Second, , Top
+@@chapter First Chapter
+
+Contents of first chapter @dots{}
address@hidden group
address@hidden example
+
+The full contents of @file{concept-index.texinfo} might be as simple as this:
+
address@hidden
address@hidden
+@@node Concept Index
+@@unnumbered Concept Index
+
+@@printindex cp
address@hidden group
address@hidden example
+
+The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference
+Manual} is named @file{elisp.texi}. This outer file contains a master
+menu with 417 entries and a list of 41 @code{@@include}
address@hidden
+
+
address@hidden Include Files Evolution
address@hidden Evolution of Include Files
+
+When Info was first created, it was customary to create many small
+Info files on one subject. Each Info file was formatted from its own
+Texinfo source file. This custom meant that Emacs did not need to
+make a large buffer to hold the whole of a large Info file when
+someone wanted information; instead, Emacs allocated just enough
+memory for the small Info file that contained the particular
+information sought. This way, Emacs could avoid wasting address@hidden
+
+References from one file to another were made by referring to the file
+name as well as the node name. (@xref{Other Info Files, , Referring to
+Other Info Files}. Also, see @ref{Four and Five Arguments, ,
address@hidden@@xref} with Four and Five Arguments}.)@refill
+
+Include files were designed primarily as a way to create a single,
+large printed manual out of several smaller Info files. In a printed
+manual, all the references were within the same document, so @TeX{}
+could automatically determine the references' page numbers. The Info
+formatting commands used include files only for creating joint
+indices; each of the individual Texinfo files had to be formatted for
+Info individually. (Each, therefore, required its own
address@hidden@@setfilename} line.)@refill
+
+However, because large Info files are now split automatically, it is
+no longer necessary to keep them address@hidden
+
+Nowadays, multiple Texinfo files are used mostly for large documents,
+such as @cite{The GNU Emacs Lisp Reference Manual}, and for projects
+in which several different people write different sections of a
+document address@hidden
+
+In addition, the Info formatting commands have been extended to work
+with the @code{@@include} command so as to create a single large Info
+file that is split into smaller files if necessary. This means that
+you can write menus and cross references without naming the different
+Texinfo address@hidden
+
+
address@hidden Headings
address@hidden Page Headings
address@hidden Headings
address@hidden Footings
address@hidden Page numbering
address@hidden Page headings
address@hidden Formatting headings and footings
+
+Most printed manuals contain headings along the top of every page
+except the title and copyright pages. Some manuals also contain
+footings. (Headings and footings have no meaning to Info, which is
+not paginated.)@refill
+
address@hidden
+* 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.
address@hidden menu
+
address@hidden Headings Introduced, Heading Format, Headings, Headings
address@hidden Headings Introduced
+
+Texinfo provides standard page heading formats for manuals that are
+printed on one side of each sheet of paper and for manuals that are
+printed on both sides of the paper. Typically, you will use these
+formats, but you can specify your own format if you address@hidden
+
+In addition, you can specify whether chapters should begin on a new
+page, or merely continue the same page as the previous chapter; and if
+chapters begin on new pages, you can specify whether they must be
+odd-numbered address@hidden
+
+By convention, a book is printed on both sides of each sheet of paper.
+When you open a book, the right-hand page is odd-numbered, and
+chapters begin on right-hand pages---a preceding left-hand page is
+left blank if necessary. Reports, however, are often printed on just
+one side of paper, and chapters begin on a fresh page immediately
+following the end of the preceding chapter. In short or informal
+reports, chapters often do not begin on a new page at all, but are
+separated from the preceding text by a small amount of address@hidden
+
+The @code{@@setchapternewpage} command controls whether chapters begin
+on new pages, and whether one of the standard heading formats is used.
+In addition, Texinfo has several heading and footing commands that you
+can use to generate your own heading and footing address@hidden
+
+In Texinfo, headings and footings are single lines at the tops and
+bottoms of pages; you cannot create multiline headings or footings.
+Each header or footer line is divided into three parts: a left part, a
+middle part, and a right part. Any part, or a whole line, may be left
+blank. Text for the left part of a header or footer line is set
+flushleft; text for the middle part is centered; and, text for the
+right part is set address@hidden
+
address@hidden Heading Format, Heading Choice, Headings Introduced, Headings
address@hidden node-name, next, previous, up
address@hidden Standard Heading Formats
+
+Texinfo provides two standard heading formats, one for manuals printed
+on one side of each sheet of paper, and the other for manuals printed
+on both sides of the paper.
+
+By default, nothing is specified for the footing of a Texinfo file,
+so the footing remains address@hidden
+
+The standard format for single-sided printing consists of a header
+line in which the left-hand part contains the name of the chapter, the
+central part is blank, and the right-hand part contains the page
address@hidden
+
address@hidden 950
+A single-sided page looks like this:
+
address@hidden
address@hidden
+ _______________________
+ | |
+ | chapter page number |
+ | |
+ | Start of text ... |
+ | ... |
+ | |
+
address@hidden group
address@hidden example
+
+The standard format for two-sided printing depends on whether the page
+number is even or odd. By convention, even-numbered pages are on the
+left- and odd-numbered pages are on the right. (@TeX{} will adjust the
+widths of the left- and right-hand margins. Usually, widths are
+correct, but during double-sided printing, it is wise to check that
+pages will bind properly---sometimes a printer will produce output in
+which the even-numbered pages have a larger right-hand margin than the
+odd-numbered pages.)@refill
+
+In the standard double-sided format, the left part of the left-hand
+(even-numbered) page contains the page number, the central part is
+blank, and the right part contains the title (specified by the
address@hidden@@settitle} command). The left part of the right-hand
+(odd-numbered) page contains the name of the chapter, the central part
+is blank, and the right part contains the page address@hidden
+
address@hidden 750
+Two pages, side by side as in an open book, look like this:@refill
+
address@hidden
address@hidden
+ _______________________ _______________________
+ | | | |
+ | page number title | | chapter page number |
+ | | | |
+ | Start of text ... | | More text ... |
+ | ... | | ... |
+ | | | |
+
address@hidden group
address@hidden example
+
address@hidden
+The chapter name is preceded by the word ``Chapter'', the chapter number
+and a colon. This makes it easier to keep track of where you are in the
address@hidden
+
address@hidden Heading Choice, Custom Headings, Heading Format, Headings
address@hidden node-name, next, previous, up
address@hidden Specifying the Type of Heading
+
address@hidden does not begin to generate page headings for a standard Texinfo
+file until it reaches the @code{@@end titlepage} command. Thus, the
+title and copyright pages are not numbered. The @code{@@end
+titlepage} command causes @TeX{} to begin to generate page headings
+according to a standard format specified by the
address@hidden@@setchapternewpage} command that precedes the
address@hidden@@titlepage} address@hidden
+
address@hidden 1000
+There are four possibilities:@refill
+
address@hidden @asis
address@hidden No @code{@@setchapternewpage} command
+Cause @TeX{} to specify the single-sided heading format, with chapters
+on new pages. This is the same as @code{@@setchapternewpage address@hidden
+
address@hidden @code{@@setchapternewpage on}
+Specify the single-sided heading format, with chapters on new address@hidden
+
address@hidden @code{@@setchapternewpage off}
+Cause @TeX{} to start a new chapter on the same page as the last page of
+the preceding chapter, after skipping some vertical whitespace. Also
+cause @TeX{} to typeset for single-sided printing. (You can override
+the headers format with the @code{@@headings double} command; see
address@hidden on off, , The @code{@@headings} Command}.)@refill
+
address@hidden @code{@@setchapternewpage odd}
+Specify the double-sided heading format, with chapters on new address@hidden
address@hidden table
+
address@hidden
+Texinfo lacks an @code{@@setchapternewpage even} address@hidden
+
address@hidden Custom Headings, , Heading Choice, Headings
address@hidden node-name, next, previous, up
address@hidden How to Make Your Own Headings
+
+You can use the standard headings provided with Texinfo or specify
+your own. By default, Texinfo has no footers, so if you specify them,
+the available page size for the main text will be slightly reduced.
+
+Texinfo provides six commands for specifying headings and
+footings:
address@hidden @bullet
address@hidden
address@hidden@@everyheading} @code{@@everyfooting} generate page headers and
+footers that are the same for both even- and odd-numbered pages.
address@hidden
address@hidden@@evenheading} and @code{@@evenfooting} command generate headers
+and footers for even-numbered (left-hand) pages.
address@hidden
address@hidden@@oddheading} and @code{@@oddfooting} generate headers and footers
+for odd-numbered (right-hand) pages.
address@hidden itemize
+
+Write custom heading specifications in the Texinfo file immediately
+after the @code{@@end titlepage} command.
+You must cancel the predefined heading commands with the
address@hidden@@headings off} command before defining your own
address@hidden
+
address@hidden 1000
+Here is how to tell @TeX{} to place the chapter name at the left, the
+page number in the center, and the date at the right of every header
+for both even- and odd-numbered pages:@refill
+
address@hidden
address@hidden
+@@headings off
+@@everyheading @@thischapter @@| @@thispage @@| @@address@hidden@}
address@hidden group
address@hidden example
+
address@hidden
+You need to divide the left part from the central part and the central
+part from the right part by inserting @samp{@@|} between parts.
+Otherwise, the specification command will not be able to tell where
+the text for one part ends and the next part address@hidden
+
+Each part can contain text or @@-commands. The text
+is printed as if the part were within an ordinary paragraph in the
+body of the page. The @@-commands replace
+themselves with the page number, date, chapter name, or
address@hidden
+
address@hidden 950
+Here are the six heading and footing commands:@refill
+
address@hidden everyheading
address@hidden everyfooting
address@hidden @code
address@hidden @@everyheading @var{left} @@| @var{center} @@| @var{right}
address@hidden @@everyfooting @var{left} @@| @var{center} @@| @var{right}
+
+The `every' commands specify the format for both even- and odd-numbered
+pages. These commands are for documents that are printed on one side
+of each sheet of paper, or for documents in which you want symmetrical
+headers or address@hidden
+
address@hidden evenheading
address@hidden evenfooting
address@hidden oddheading
address@hidden oddfooting
address@hidden @@evenheading @var{left} @@| @var{center} @@| @var{right}
address@hidden @@oddheading @var{left} @@| @var{center} @@| @var{right}
+
address@hidden @@evenfooting @var{left} @@| @var{center} @@| @var{right}
address@hidden @@oddfooting @var{left} @@| @var{center} @@| @var{right}
+
+The `even' and `odd' commands specify the format for even-numbered
+pages and odd-numbered pages. These commands are for books and
+manuals that are printed on both sides of each sheet of paper.
address@hidden table
+
+Use the @samp{@@address@hidden series of @@-commands to
+provide the names of chapters
+and sections and the page number. You can use the
address@hidden@@address@hidden commands in the left, center, or right portions
+of headers and footers, or anywhere else in a Texinfo file so long as
+they are between @code{@@iftex} and @code{@@end iftex} address@hidden
+
address@hidden 1000
+Here are the @samp{@@address@hidden commands:@refill
+
address@hidden @code
address@hidden thispage
address@hidden @@thispage
+Expands to the current page address@hidden
address@hidden !!! Karl Berry says that `thissection' can fail on page breaks.
+
address@hidden thischaptername
address@hidden @@thischaptername
+Expands to the name of the current address@hidden
+
address@hidden thischapter
address@hidden @@thischapter
+Expands to the number and name of the current
+chapter, in the format `Chapter 1: Title'address@hidden
+
address@hidden thistitle
address@hidden @@thistitle
+Expands to the name of the document, as specified by the
address@hidden@@settitle} address@hidden
+
address@hidden thisfile
address@hidden @@thisfile
+For @code{@@include} files only: expands to the name of the current
address@hidden@@include} file. If the current Texinfo source file is not an
address@hidden@@include} file, this command has no effect. This command does
address@hidden provide the name of the current Texinfo source file unless
+it is an @code{@@include} file. (@xref{Include Files}, for more
+information about @code{@@include} files.)@refill
address@hidden table
+
address@hidden
+You can also use the @code{@@address@hidden@}} command, which expands to the
+current date, in `1 Jan 1900' address@hidden
address@hidden today
+
+Other @@-commands and text are printed in a header or footer just as
+if they were in the body of a page. It is useful to incorporate text,
+particularly when you are writing drafts:@refill
+
address@hidden
address@hidden
+@@headings off
+@@everyheading @@address@hidden@} @@| @@thispage @@| @@thischapter
+@@everyfooting @@| @@| Version: 0.27: @@address@hidden@}
address@hidden group
address@hidden example
+
+Beware of overlong titles: they may overlap another part of the
+header or footer and blot it address@hidden
+
+
address@hidden Catching Mistakes
address@hidden Formatting Mistakes
address@hidden Structure, catching mistakes in
address@hidden Nodes, catching mistakes
address@hidden Catching mistakes
address@hidden Correcting mistakes
address@hidden Mistakes, catching
address@hidden Problems, catching
address@hidden Debugging the Texinfo structure
+
+Besides mistakes in the content of your documentation, there are two
+kinds of mistake you can make with Texinfo: you can make mistakes with
+@@-commands, and you can make mistakes with the structure of the nodes
+and chapters.
+
+Emacs has two tools for catching the @@-command mistakes and two for
+catching structuring address@hidden
+
+For finding problems with @@-commands, you can run @TeX{} or a region
+formatting command on the region that has a problem; indeed, you can
+run these commands on each region as you write address@hidden
+
+For finding problems with the structure of nodes and chapters, you can use
address@hidden C-s} (@code{texinfo-show-structure}) and the related @code{occur}
+command and you can use the @kbd{M-x Info-validate} address@hidden
+
address@hidden
+* 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 texinfo-show-structure:: How to use @code{texinfo-show-structure}.
+* Using occur:: How to list all lines containing a pattern.
+* Running Info-Validate:: How to find badly referenced nodes.
address@hidden menu
+
address@hidden makeinfo Preferred, Debugging with Info, Catching Mistakes,
Catching Mistakes
address@hidden @code{makeinfo} Find Errors
+
+The @code{makeinfo} program does an excellent job of catching errors
+and reporting them---far better than @code{texinfo-format-region} or
address@hidden In addition, the various functions for
+automatically creating and updating node pointers and menus remove
+many opportunities for human address@hidden
+
+If you can, use the updating commands to create and insert pointers
+and menus. These prevent many errors. Then use @code{makeinfo} (or
+its Texinfo mode manifestations, @code{makeinfo-region} and
address@hidden) to format your file and check for other
+errors. This is the best way to work with Texinfo. But if you
+cannot use @code{makeinfo}, or your problem is very puzzling, then you
+may want to use the tools described in this address@hidden
+
address@hidden Debugging with Info, Debugging with TeX, makeinfo Preferred,
Catching Mistakes
address@hidden node-name, next, previous, up
address@hidden Catching Errors with Info Formatting
address@hidden Catching errors with Info formatting
address@hidden Debugging with Info formatting
+
+After you have written part of a Texinfo file, you can use the
address@hidden or the @code{makeinfo-region} command to
+see whether the region formats address@hidden
+
+Most likely, however, you are reading this section because for some
+reason you cannot use the @code{makeinfo-region} command; therefore, the
+rest of this section presumes that you are using
address@hidden@refill
+
+If you have made a mistake with an @@-command,
address@hidden will stop processing at or after the
+error and display an error message. To see where in the buffer the
+error occurred, switch to the @samp{*Info Region*} buffer; the cursor
+will be in a position that is after the location of the error. Also,
+the text will not be formatted after the place where the error
+occurred (or more precisely, where it was detected)address@hidden
+
+For example, if you accidentally end a menu with the command @code{@@end
+menus} with an `s' on the end, instead of with @code{@@end menu}, you
+will see an error message that says:@refill
+
address@hidden
+@@end menus is not handled by texinfo
address@hidden example
+
address@hidden
+The cursor will stop at the point in the buffer where the error
+occurs, or not long after it. The buffer will look like this:@refill
+
address@hidden
address@hidden
+---------- Buffer: *Info Region* ----------
+* Menu:
+
+* Using texinfo-show-structure:: How to use
+ `texinfo-show-structure'
+ to catch mistakes.
+* Running Info-Validate:: How to check for
+ unreferenced nodes.
+@@end menus
address@hidden
+---------- Buffer: *Info Region* ----------
address@hidden group
address@hidden example
+
+The @code{texinfo-format-region} command sometimes provides slightly
+odd error messages. For example, the following cross reference fails to
format:@refill
+
address@hidden
+(@@address@hidden Mistakes, for more info.)
address@hidden example
+
address@hidden
+In this case, @code{texinfo-format-region} detects the missing closing
+brace but displays a message that says @samp{Unbalanced parentheses}
+rather than @samp{Unbalanced braces}. This is because the formatting
+command looks for mismatches between braces as if they were
address@hidden
+
+Sometimes @code{texinfo-format-region} fails to detect mistakes. For
+example, in the following, the closing brace is swapped with the
+closing parenthesis:@refill
+
address@hidden
+(@@address@hidden Mistakes), for more address@hidden
address@hidden example
+
address@hidden
+Formatting produces:
address@hidden
+(*Note for more info.: Catching Mistakes)
address@hidden example
+
+The only way for you to detect this error is to realize that the
+reference should have looked like this:@refill
+
address@hidden
+(*Note Catching Mistakes::, for more info.)
address@hidden example
+
+Incidentally, if you are reading this node in Info and type @kbd{f
address@hidden (@code{Info-follow-reference}), you will generate an error
+message that says:
+
address@hidden
+No such node: "Catching Mistakes) The only way @dots{}
address@hidden example
+
address@hidden
+This is because Info perceives the example of the error as the first
+cross reference in this node and if you type a @key{RET} immediately
+after typing the Info @kbd{f} command, Info will attempt to go to the
+referenced node. If you type @kbd{f catch @key{TAB} @key{RET}}, Info
+will complete the node name of the correctly written example and take
+you to the `Catching Mistakes' node. (If you try this, you can return
+from the `Catching Mistakes' node by typing @kbd{l}
+(@code{Info-last}).)
+
address@hidden !!! section on using Elisp debugger ignored.
+
address@hidden Debugging with TeX, Using texinfo-show-structure, Debugging with
Info, Catching Mistakes
address@hidden node-name, next, previous, up
address@hidden Catching Errors with @TeX{} Formatting
address@hidden Catching errors with @TeX{} formatting
address@hidden Debugging with @TeX{} formatting
+
+You can also catch mistakes when you format a file with @address@hidden
+
+Usually, you will want to do this after you have run
address@hidden (or, better, @code{makeinfo-buffer}) on
+the same file, because @code{texinfo-format-buffer} sometimes displays
+error messages that make more sense than @TeX{}. (@xref{Debugging
+with Info}, for more information.)@refill
+
+For example, @TeX{} was run on a Texinfo file, part of which is shown
+here:@refill
+
address@hidden
+---------- Buffer: texinfo.texi ----------
+name of the Texinfo file as an extension. The
+@@address@hidden@} are `wildcards' that cause the shell to
+substitute all the raw index files. (@@address@hidden
+indices, for more information about sorting
+indices.)@@refill
+---------- Buffer: texinfo.texi ----------
address@hidden example
+
address@hidden
+(The cross reference lacks a closing brace.)
address@hidden produced the following output, after which it stopped:@refill
+
address@hidden
+---------- Buffer: *tex-shell* ----------
+Runaway argument?
address@hidden indices, for more information about sorting
+indices.) @@refill @@ETC.
+! Paragraph ended before @@xref was complete.
+<to be read again>
+ @@par
+l.27
+
+?
+---------- Buffer: *tex-shell* ----------
address@hidden example
+
+In this case, @TeX{} produced an accurate and
+understandable error message:
+
address@hidden
+Paragraph ended before @@xref was complete.
address@hidden example
+
address@hidden
address@hidden@@par} is an internal @TeX{} command of no relevance to Texinfo.
address@hidden means that @TeX{} detected the problem on line 27 of the
+Texinfo file. The @samp{?} is the prompt @TeX{} uses in this
address@hidden
+
+Unfortunately, @TeX{} is not always so helpful, and sometimes you must
+truly be a Sherlock Holmes to discover what went address@hidden
+
+In any case, if you run into a problem like this, you can do one of three
address@hidden
+
address@hidden
address@hidden
+You can tell @TeX{} to continue running and ignore just this error by
+typing @key{RET} at the @samp{?} address@hidden
+
address@hidden
+You can tell @TeX{} to continue running and to ignore all errors as best
+it can by typing @kbd{r @key{RET}} at the @samp{?} address@hidden
+
+This is often the best thing to do. However, beware: the one error
+may produce a cascade of additional error messages as its consequences
+are felt through the rest of the file. To stop @TeX{} when it is
+producing such an avalanche of error messages, type @kbd{C-c} (or
address@hidden C-c}, if you are running a shell inside Emacs).
+
address@hidden
+You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}}
+at the @samp{?} address@hidden
address@hidden enumerate
+
+If you are running @TeX{} inside Emacs, you need to switch to the shell
+buffer and line at which @TeX{} offers the @samp{?} prompt.
+
+Sometimes @TeX{} will format a file without producing error messages even
+though there is a problem. This usually occurs if a command is not ended
+but @TeX{} is able to continue processing anyhow. For example, if you fail
+to end an itemized list with the @code{@@end itemize} command, @TeX{} will
+write a DVI file that you can print out. The only error message that
address@hidden will give you is the somewhat mysterious comment address@hidden
+
address@hidden
+(@@end occurred inside a group at level 1)
address@hidden example
+
address@hidden
+However, if you print the DVI file, you will find that the text
+of the file that follows the itemized list is entirely indented as if
+it were part of the last item in the itemized list. The error message
+is the way @TeX{} says that it expected to find an @code{@@end}
+command somewhere in the file; but that it could not determine where
+it was address@hidden
+
+Another source of notoriously hard-to-find errors is a missing
address@hidden@@end group} command. If you ever are stumped by
+incomprehensible errors, look for a missing @code{@@end group} command
address@hidden
+
+If the Texinfo file lacks header lines,
address@hidden may stop in the
+beginning of its run and display output that looks like the following.
+The @samp{*} indicates that @TeX{} is waiting for address@hidden
+
address@hidden
+This is TeX, Version 3.14159 (Web2c 7.0)
+(test.texinfo [1])
+*
address@hidden example
+
address@hidden
+In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then
+write the header lines in the Texinfo file and run the @TeX{} command
+again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\}
+instead of @samp{@@}; and in this circumstance, you are working
+directly with @TeX{}, not with Texinfo.)@refill
+
address@hidden Using texinfo-show-structure, Using occur, Debugging with TeX,
Catching Mistakes
address@hidden node-name, next, previous, up
address@hidden Using @code{texinfo-show-structure}
address@hidden Showing the structure of a file
address@hidden texinfo-show-structure
+
+It is not always easy to keep track of the nodes, chapters, sections, and
+subsections of a Texinfo file. This is especially true if you are revising
+or adding to a Texinfo file that someone else has address@hidden
+
+In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure}
+command lists all the lines that begin with the @@-commands that
+specify the structure: @code{@@chapter}, @code{@@section},
address@hidden@@appendix}, and so on. With an argument (@address@hidden
+as prefix argument, if interactive),
+the command also shows the @code{@@node} lines. The
address@hidden command is bound to @kbd{C-c C-s} in
+Texinfo mode, by address@hidden
+
+The lines are displayed in a buffer called the @samp{*Occur*} buffer,
+indented by hierarchical level. For example, here is a part of what was
+produced by running @code{texinfo-show-structure} on this manual:@refill
+
address@hidden
address@hidden
+ Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\|
+ unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
+ in buffer texinfo.texi.
+ @dots{}
+ 4177:@@chapter Nodes
+ 4198: @@heading Two Paths
+ 4231: @@section Node and Menu Illustration
+ 4337: @@section The @@address@hidden@@@@address@hidden Command
+ 4393: @@subheading Choosing Node and Pointer Names
+ 4417: @@subsection How to Write an @@address@hidden@@@@address@hidden
Line
+ 4469: @@subsection @@address@hidden@@@@address@hidden Line Tips
+ @dots{}
address@hidden group
address@hidden example
+
+This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin
+with the @code{@@section}, @code{@@subheading}, and @code{@@subsection}
+commands respectively. If you move your cursor into the @samp{*Occur*}
+window, you can position the cursor over one of the lines and use the
address@hidden C-c} command (@code{occur-mode-goto-occurrence}), to jump to
+the corresponding spot in the Texinfo file. @xref{Other Repeating
+Search, , Using Occur, emacs, The GNU Emacs Manual}, for more
+information about @address@hidden
+
+The first line in the @samp{*Occur*} window describes the @dfn{regular
+expression} specified by @var{texinfo-heading-pattern}. This regular
+expression is the pattern that @code{texinfo-show-structure} looks for.
address@hidden, , Using Regular Expressions, emacs, The GNU Emacs Manual},
+for more address@hidden
+
+When you invoke the @code{texinfo-show-structure} command, Emacs will
+display the structure of the whole buffer. If you want to see the
+structure of just a part of the buffer, of one chapter, for example,
+use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the
+region. (@xref{Narrowing, , , emacs, The GNU Emacs Manual}.) This is
+how the example used above was generated. (To see the whole buffer
+again, use @kbd{C-x n w} (@code{widen}).)@refill
+
+If you call @code{texinfo-show-structure} with a prefix argument by
+typing @address@hidden C-c C-s}}, it will list lines beginning with
address@hidden@@node} as well as the lines beginning with the @@-sign commands
+for @code{@@chapter}, @code{@@section}, and the address@hidden
+
+You can remind yourself of the structure of a Texinfo file by looking at
+the list in the @samp{*Occur*} window; and if you have mis-named a node
+or left out a section, you can correct the address@hidden
+
address@hidden Using occur, Running Info-Validate, Using
texinfo-show-structure, Catching Mistakes
address@hidden node-name, next, previous, up
address@hidden Using @code{occur}
address@hidden Occurrences, listing with @code{@@occur}
address@hidden occur
+
+Sometimes the @code{texinfo-show-structure} command produces too much
+information. Perhaps you want to remind yourself of the overall structure
+of a Texinfo file, and are overwhelmed by the detailed list produced by
address@hidden In this case, you can use the @code{occur}
+command directly. To do this, address@hidden
+
address@hidden
address@hidden occur}
address@hidden example
+
address@hidden
+and then, when prompted, type a @dfn{regexp}, a regular expression for
+the pattern you want to match. (@xref{Regexps, , Regular Expressions,
+emacs, The GNU Emacs Manual}.) The @code{occur} command works from
+the current location of the cursor in the buffer to the end of the
+buffer. If you want to run @code{occur} on the whole buffer, place
+the cursor at the beginning of the address@hidden
+
+For example, to see all the lines that contain the word
address@hidden@@chapter} in them, just type @samp{@@chapter}. This will
+produce a list of the chapters. It will also list all the sentences
+with @samp{@@chapter} in the middle of the address@hidden
+
+If you want to see only those lines that start with the word
address@hidden@@chapter}, type @samp{^@@chapter} when prompted by
address@hidden If you want to see all the lines that end with a word
+or phrase, end the last word with a @samp{$}; for example,
address@hidden mistakes$}. This can be helpful when you want to see
+all the nodes that are part of the same chapter or section and
+therefore have the same `Up' address@hidden
+
address@hidden Repeating Search, , Using Occur, emacs , The GNU Emacs Manual},
+for more address@hidden
+
address@hidden Running Info-Validate, , Using occur, Catching Mistakes
address@hidden node-name, next, previous, up
address@hidden Finding Badly Referenced Nodes
address@hidden Info-validate
address@hidden Nodes, checking for badly referenced
address@hidden Checking for badly referenced nodes
address@hidden Looking for badly referenced nodes
address@hidden Finding badly referenced nodes
address@hidden Badly referenced nodes
+
+You can use the @code{Info-validate} command to check whether any of
+the `Next', `Previous', `Up' or other node pointers fail to point to a
+node. This command checks that every node pointer points to an
+existing node. The @code{Info-validate} command works only on Info
+files, not on Texinfo address@hidden
+
+The @code{makeinfo} program validates pointers automatically, so you
+do not need to use the @code{Info-validate} command if you are using
address@hidden You only may need to use @code{Info-validate} if you
+are unable to run @code{makeinfo} and instead must create an Info file
+using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or
+if you write an Info file from address@hidden
+
address@hidden
+* Using 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.
address@hidden menu
+
address@hidden Using Info-validate, Unsplit, Running Info-Validate, Running
Info-Validate
address@hidden Running @code{Info-validate}
address@hidden Running @code{Info-validate}
address@hidden Info validating a large file
address@hidden Validating a large file
+
+To use @code{Info-validate}, visit the Info file you wish to check and
+type:@refill
+
address@hidden
+M-x Info-validate
address@hidden example
+
address@hidden
+Note that the @code{Info-validate} command requires an upper case
+`I'. You may also need to create a tag table before running
address@hidden @xref{Tagifying}.
+
+If your file is valid, you will receive a message that says ``File appears
+valid''. However, if you have a pointer that does not point to a node,
+error messages will be displayed in a buffer called @samp{*problems in
+info address@hidden
+
+For example, @code{Info-validate} was run on a test file that contained
+only the first node of this manual. One of the messages said:@refill
+
address@hidden
+In node "Overview", invalid Next: Texinfo Mode
address@hidden example
+
address@hidden
+This meant that the node called @samp{Overview} had a `Next' pointer that
+did not point to anything (which was true in this case, since the test file
+had only one node in it)address@hidden
+
+Now suppose we add a node named @samp{Texinfo Mode} to our test case
+but we do not specify a `Previous' for this node. Then we will get
+the following error message:@refill
+
address@hidden
+In node "Texinfo Mode", should have Previous: Overview
address@hidden example
+
address@hidden
+This is because every `Next' pointer should be matched by a
+`Previous' (in the node where the `Next' points) which points address@hidden
+
address@hidden also checks that all menu entries and cross references
+point to actual address@hidden
+
address@hidden requires a tag table and does not work with files
+that have been split. (The @code{texinfo-format-buffer} command
+automatically splits large files.) In order to use @code{Info-validate}
+on a large file, you must run @code{texinfo-format-buffer} with an
+argument so that it does not split the Info file; and you must create a
+tag table for the unsplit file.
+
address@hidden Unsplit, Tagifying, Using Info-validate, Running Info-Validate
address@hidden node-name, next, previous, up
address@hidden Creating an Unsplit File
address@hidden Creating an unsplit file
address@hidden Unsplit file creation
+
+You can run @code{Info-validate} only on a single Info file that has a
+tag table. The command will not work on the indirect subfiles that
+are generated when a master file is split. If you have a large file
+(longer than 70,000 bytes or so), you need to run the
address@hidden or @code{makeinfo-buffer} command in such
+a way that it does not create indirect subfiles. You will also need
+to create a tag table for the Info file. After you have done this,
+you can run @code{Info-validate} and look for badly referenced
address@hidden
+
+The first step is to create an unsplit Info file. To prevent
address@hidden from splitting a Texinfo file into
+smaller Info files, give a prefix to the @kbd{M-x
+texinfo-format-buffer} command:@refill
+
address@hidden
+C-u M-x texinfo-format-buffer
address@hidden example
+
address@hidden
+or else
+
address@hidden
+C-u C-c C-e C-b
address@hidden example
+
address@hidden
+When you do this, Texinfo will not split the file and will not create
+a tag table for it. @refill
address@hidden Making a tag table manually
address@hidden Tag table, making manually
+
address@hidden Tagifying, Splitting, Unsplit, Running Info-Validate
address@hidden Tagifying a File
+
+After creating an unsplit Info file, you must create a tag table for
+it. Visit the Info file you wish to tagify and type:@refill
+
address@hidden
+M-x Info-tagify
address@hidden example
+
address@hidden
+(Note the upper case @samp{I} in @code{Info-tagify}.) This creates an
+Info file with a tag table that you can address@hidden
+
+The third step is to validate the Info file:@refill
+
address@hidden
+M-x Info-validate
address@hidden example
+
address@hidden
+(Note the upper case @samp{I} in @code{Info-validate}.)
+In brief, the steps are:@refill
+
address@hidden
address@hidden
+C-u M-x texinfo-format-buffer
+M-x Info-tagify
+M-x Info-validate
address@hidden group
address@hidden example
+
+After you have validated the node structure, you can rerun
address@hidden in the normal way so it will construct a
+tag table and split the file automatically, or you can make the tag
+table and split the file address@hidden
+
address@hidden Splitting, , Tagifying, Running Info-Validate
address@hidden node-name, next, previous, up
address@hidden Splitting a File Manually
address@hidden Splitting an Info file manually
address@hidden Info file, splitting manually
+
+You should split a large file or else let the
address@hidden or @code{makeinfo-buffer} command do it
+for you automatically. (Generally you will let one of the formatting
+commands do this job for you. @xref{Creating an Info File}.)@refill
+
+The split-off files are called the indirect address@hidden
+
+Info files are split to save memory. With smaller files, Emacs does not
+have make such a large buffer to hold the address@hidden
+
+If an Info file has more than 30 nodes, you should also make a tag
+table for it. @xref{Using Info-validate}, for information
+about creating a tag table. (Again, tag tables are usually created
+automatically by the formatting command; you only need to create a tag
+table yourself if you are doing the job manually. Most likely, you
+will do this for a large, unsplit file on which you have run
address@hidden)@refill
+
address@hidden Info-split is autoloaded in `loaddefs.el' in Emacs 18.51
+
+Visit the Info file you wish to tagify and split and type the two
+commands:@refill
+
address@hidden
+M-x Info-tagify
+M-x Info-split
address@hidden example
+
address@hidden
+(Note that the @samp{I} in @samp{Info} is upper case.)@refill
+
+When you use the @code{Info-split} command, the buffer is modified into a
+(small) Info file which lists the indirect subfiles. This file should be
+saved in place of the original visited file. The indirect subfiles are
+written in the same directory the original file is in, with names generated
+by appending @samp{-} and a number to the original file address@hidden
+
+The primary file still functions as an Info file, but it contains just
+the tag table and a directory of address@hidden
+
+
address@hidden Refilling Paragraphs
address@hidden Refilling Paragraphs
address@hidden Refilling paragraphs
address@hidden Filling paragraphs
address@hidden Paragraphs, filling
address@hidden refill
+
+The @code{@@refill} command refills and, optionally, indents the first
+line of a address@hidden the command should have been
+called the @code{@@refillandindent} command, but @code{@@refill} is
+shorter and the name was chosen before indenting was possible.} The
address@hidden@@refill} command is no longer important, but we describe it here
+because you once needed it. You will see it in many old Texinfo
address@hidden
+
+Without refilling, paragraphs containing long @@-constructs may look
+bad after formatting because the formatter removes @@-commands and
+shortens some lines more than others. In the past, neither the
address@hidden command nor the
address@hidden command refilled paragraphs
+automatically. The @code{@@refill} command had to be written at the
+end of every paragraph to cause these formatters to fill them. (Both
address@hidden and @code{makeinfo} have always refilled paragraphs
+automatically.) Now, all the Info formatters automatically fill and
+indent those paragraphs that need to be filled and address@hidden
+
+The @code{@@refill} command causes @code{texinfo-format-region} and
address@hidden to refill a paragraph in the Info file
address@hidden all the other processing has been done. For this reason,
+you can not use @code{@@refill} with a paragraph containing either
address@hidden@@*} or @code{@@address@hidden @dots{} @}} since the refilling
action will
+override those two address@hidden
+
+The @code{texinfo-format-region} and @code{texinfo-format-buffer}
+commands now automatically append @code{@@refill} to the end of each
+paragraph that should be filled. They do not append @code{@@refill} to
+the ends of paragraphs that contain @code{@@*} or
@address@hidden@@address@hidden @address@hidden
+and therefore do not refill or indent address@hidden
+
+
address@hidden Command Syntax
address@hidden @@-Command Syntax
address@hidden @@-command syntax
address@hidden Syntax, of @@-commands
address@hidden Command syntax
+
+The character @samp{@@} is used to start special Texinfo commands.
+(It has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo
+has four types of @@-command:@refill
+
address@hidden @asis
address@hidden 1. Non-alphabetic commands.
+These commands consist of an @@ followed by a punctuation mark or other
+character that is not part of the alphabet. Non-alphabetic commands are
+almost always part of the text within a paragraph, and never take any
+argument. The two characters (@@ and the other one) are complete in
+themselves; none is followed by braces. The non-alphabetic commands
+are: @code{@@.}, @code{@@:}, @code{@@*}, @code{@@@kbd{SPACE}},
address@hidden@@@kbd{TAB}}, @code{@@@kbd{NL}}, @code{@@@@}, @code{@@@{}, and
address@hidden@@@address@hidden
+
address@hidden 2. Alphabetic commands that do not require arguments.
+These commands start with @@ followed by a word followed by left- and
+right-hand braces. These commands insert special symbols in the
+document; they do not require arguments. For example,
address@hidden@@address@hidden@}} @result{} @address@hidden,
@code{@@address@hidden@}}
address@hidden @address@hidden, @code{@@address@hidden@}} @result{}
address@hidden',
+and @code{@@address@hidden@}} @result{} @address@hidden@refill
+
address@hidden 3. Alphabetic commands that require arguments within braces.
+These commands start with @@ followed by a letter or a word, followed by an
+argument within braces. For example, the command @code{@@dfn} indicates
+the introductory or defining use of a term; it is used as follows: @samp{In
+Texinfo, @@@@-commands are @@address@hidden@} address@hidden
+
address@hidden 4. Alphabetic commands that occupy an entire line.
+These commands occupy an entire line. The line starts with @@,
+followed by the name of the command (a word); for example, @code{@@center}
+or @code{@@cindex}. If no argument is needed, the word is followed by
+the end of the line. If there is an argument, it is separated from
+the command name by a space. Braces are not address@hidden
address@hidden table
+
address@hidden Braces and argument syntax
+Thus, the alphabetic commands fall into classes that have
+different argument syntaxes. You cannot tell to which class a command
+belongs by the appearance of its name, but you can tell by the
+command's meaning: if the command stands for a glyph, it is in
+class 2 and does not require an argument; if it makes sense to use the
+command together with other text as part of a paragraph, the command
+is in class 3 and must be followed by an argument in braces;
+otherwise, it is in class 4 and uses the rest of the line as its
address@hidden
+
+The purpose of having a different syntax for commands of classes 3 and
+4 is to make Texinfo files easier to read, and also to help the GNU
+Emacs paragraph and filling commands work properly. There is only one
+exception to this rule: the command @code{@@refill}, which is always
+used at the end of a paragraph immediately following the final period
+or other punctuation character. @code{@@refill} takes no argument and
+does @emph{not} require braces. @code{@@refill} never confuses the
+Emacs paragraph commands because it cannot appear at the beginning of
+a address@hidden
+
+
address@hidden Obtaining TeX
address@hidden How to Obtain @TeX{}
address@hidden Obtaining @TeX{}
address@hidden @TeX{}, how to obtain
+
address@hidden !!! Here is information about obtaining TeX. Update it whenever.
address@hidden !!! Also consider updating TeX.README on ftp.gnu.org.
address@hidden Updated by RJC on 1 March 1995, conversation with MacKay.
address@hidden Updated by address@hidden on 29 July 1996.
address@hidden Updated by address@hidden on 25 April 1997.
address@hidden Updated by address@hidden on 27 February 1998.
address@hidden is freely redistributable. You can obtain @TeX{} for Unix
+systems via anonymous ftp or on physical media. The core material
+consists of the Web2c @TeX{} distribution (@uref{http://tug.org/web2c}).
+
+Instructions for retrieval by anonymous ftp and information on other
+available distributions:
address@hidden
address@hidden://tug.org/tex/unixtex.ftp}
address@hidden://tug.org/unixtex.ftp}
address@hidden example
+
+The Free Software Foundation provides a core distribution on its Source
+Code CD-ROM suitable for printing Texinfo manuals. To order it, contact:
+
address@hidden
address@hidden
+Free Software Foundation, Inc.
+59 Temple Place Suite 330
+Boston, MA @ @ 02111-1307
+USA
+Telephone: @w{+1-617-542-5942}
+Fax: (including Japan) @w{+1-617-542-2652}
+Free Dial Fax (in Japan):
address@hidden } @w{ } @w{ } 0031-13-2473 (KDD)
address@hidden } @w{ } @w{ } 0066-3382-0158 (IDC)
+Electronic mail: @code{gnu@@gnu.org}
address@hidden group
address@hidden display
+
+Many other @TeX{} distributions are available; see
address@hidden://tug.org/}.
+
+
address@hidden These are no longer ``new'', and the explanations
address@hidden are all given elsewhere anyway, I think. --karl, 25apr97.
address@hidden So ignore the entire appendix.
+
+
address@hidden Copying This Manual
address@hidden Copying This Manual
+
address@hidden
+* GNU Free Documentation License:: License for copying this manual.
address@hidden menu
+
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
+
address@hidden FDL, GNU Free Documentation License
address@hidden Version 1.1, March 2000
+
address@hidden
+Copyright @copyright{} 2000 Free Software Foundation, Inc.
+59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
address@hidden display
+
address@hidden 0
address@hidden
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+written document @dfn{free} in the sense of freedom: to assure everyone
+the effective freedom to copy and redistribute it, with or without
+modifying it, either commercially or noncommercially. Secondarily,
+this License preserves for the author and publisher a way to get
+credit for their work, while not being considered responsible for
+modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
address@hidden
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work that contains a
+notice placed by the copyright holder saying it can be distributed
+under the terms of this License. The ``Document'', below, refers to any
+such manual or work. Any member of the public is a licensee, and is
+addressed as ``you''.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (For example, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, whose contents can be viewed and edited directly and
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is
+not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
address@hidden without markup, Texinfo input format, address@hidden input
format,
address@hidden or @acronym{XML} using a publicly available
address@hidden, and standard-conforming simple @acronym{HTML} designed
+for human modification. Opaque formats include PostScript,
address@hidden, proprietary formats that can be read and edited only by
+proprietary word processors, @acronym{SGML} or @acronym{XML} for which
+the @acronym{DTD} and/or processing tools are not generally available,
+and the machine-generated @acronym{HTML} produced by some word
+processors for output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
address@hidden
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
address@hidden
+COPYING IN QUANTITY
+
+If you publish printed copies of the Document numbering more than 100,
+and the Document's license notice requires Cover Texts, you must enclose
+the copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols. If you use the latter
+option, you must take reasonably prudent steps, when you begin
+distribution of Opaque copies in quantity, to ensure that this
+Transparent copy will remain thus accessible at the stated location
+until at least one year after the last time you distribute an Opaque
+copy (directly or through your agents or retailers) of that edition to
+the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
address@hidden
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
address@hidden A
address@hidden
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
address@hidden
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has less than five).
+
address@hidden
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
address@hidden
+Preserve all the copyright notices of the Document.
+
address@hidden
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
address@hidden
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
address@hidden
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
address@hidden
+Include an unaltered copy of this License.
+
address@hidden
+Preserve the section entitled ``History'', and its title, and add to
+it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
address@hidden
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
address@hidden
+In any section entitled ``Acknowledgments'' or ``Dedications'',
+preserve the section's title, and preserve in the section all the
+substance and tone of each of the contributor acknowledgments
+and/or dedications given therein.
+
address@hidden
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
address@hidden
+Delete any section entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
address@hidden
+Do not retitle any existing section as ``Endorsements''
+or to conflict in title with any Invariant Section.
address@hidden enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
address@hidden
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections entitled ``History''
+in the various original documents, forming one section entitled
+``History''; likewise combine any sections entitled ``Acknowledgments'',
+and any sections entitled ``Dedications''. You must delete all sections
+entitled ``Endorsements.''
+
address@hidden
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
address@hidden
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, does not as a whole count as a Modified Version
+of the Document, provided no compilation copyright is claimed for the
+compilation. Such a compilation is called an ``aggregate'', and this
+License does not apply to the other self-contained works thus compiled
+with the Document, on account of their being thus compiled, if they
+are not themselves derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one quarter
+of the entire aggregate, the Document's Cover Texts may be placed on
+covers that surround only the Document within the aggregate.
+Otherwise they must appear on covers around the whole aggregate.
+
address@hidden
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License provided that you also include the
+original English version of this License. In case of a disagreement
+between the translation and the original English version of this
+License, the original English version will prevail.
+
address@hidden
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
address@hidden
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
address@hidden://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
address@hidden enumerate
+
address@hidden
address@hidden ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
address@hidden
address@hidden
+ Copyright (C) @var{year} @var{your name}.
+ 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 the Invariant Sections being @var{list their titles}, with the
+ Front-Cover Texts being @var{list}, and with the Back-Cover Texts being
@var{list}.
+ A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
address@hidden group
address@hidden smallexample
+
+If you have no Invariant Sections, write ``with no Invariant Sections''
+instead of saying which ones are invariant. If you have no
+Front-Cover Texts, write ``no Front-Cover Texts'' instead of
+``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
address@hidden Local Variables:
address@hidden ispell-local-pdict: "ispell-dict"
address@hidden End:
+
+
+
address@hidden Command and Variable Index
address@hidden Command and Variable Index
+
+This is an alphabetical list of all the @@-commands, assorted Emacs Lisp
+functions, and several variables. To make the list easier to use, the
+commands are listed without their preceding @samp{@@address@hidden
+
address@hidden fn
+
+
address@hidden Concept Index
address@hidden Concept Index
+
address@hidden cp
+
+
address@hidden
Index: res_info/texi_cvs/cvs.texi.first
===================================================================
RCS file: res_info/texi_cvs/cvs.texi.first
diff -N res_info/texi_cvs/cvs.texi.first
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ res_info/texi_cvs/cvs.texi.first 2 Aug 2009 13:11:04 -0000 1.1
@@ -0,0 +1,14405 @@
+\input texinfo @c -*-texinfo-*-
address@hidden Documentation for CVS.
address@hidden cvs.info
address@hidden copyleftnotice
address@hidden
+Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
+ 2001, 2002, 2003 Free Software Foundation, Inc.
+
address@hidden @columnfractions .12 .88
address@hidden Portions
address@hidden @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003 Derek
R. Price,
address@hidden @tab Copyright @copyright{} 2002, 2003 Ximbiot
<http://ximbiot.com>,
address@hidden @tab Copyright @copyright{} 1992, 1993, 1999 Signum Support AB,
address@hidden @tab and Copyright @copyright{} others.
address@hidden multitable
+
address@hidden
+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).
+
address@hidden ignore
+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 also 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 Free Software Foundation.
address@hidden macro
+
address@hidden This file is part of the CVS distribution.
+
address@hidden CVS is free software; you can redistribute it and/or modify
address@hidden it under the terms of the GNU General Public License as
published by
address@hidden the Free Software Foundation; either version 2, or (at your
option)
address@hidden any later version.
+
address@hidden CVS is distributed in the hope that it will be useful,
address@hidden but WITHOUT ANY WARRANTY; without even the implied warranty of
address@hidden MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
address@hidden GNU General Public License for more details.
+
address@hidden See ../README for A4 vs. US letter size.
address@hidden When we provided A4 postscript, and people tried to
address@hidden print it on US letter, the usual complaint was that the
address@hidden page numbers would get cut off.
address@hidden If one prints US letter on A4, reportedly there is
address@hidden some extra space at the top and/or bottom, and the side
address@hidden margins are a bit narrow, but no text is lost.
address@hidden
address@hidden See
address@hidden http://www.ft.uni-erlangen.de/~mskuhn/iso-paper.html
address@hidden for more on paper sizes. Insuring that margins are
address@hidden big enough to print on either A4 or US letter does
address@hidden indeed seem to be the usual approach (RFC2346).
+
address@hidden This document seems to get overfull hboxes with some
address@hidden frequency (probably because the tendency is to
address@hidden sanity-check it with "make info" and run TeX less
address@hidden often). The big ugly boxes just seem to add insult
address@hidden to injury, and I'm not aware of them helping to fix
address@hidden the overfull hboxes at all.
address@hidden
+
address@hidden UPDATED 28 March 2002
address@hidden UPDATED-MONTH March 2002
address@hidden EDITION 4.2
address@hidden VERSION 4.2
address@hidden CVS---Concurrent Versions System v4.2
address@hidden odd
+
address@hidden -- TODO list:
address@hidden -- Fix all lines that match "address@hidden -- "
address@hidden -- Also places marked with FIXME should be manual
address@hidden problems (as opposed to FIXCVS for CVS problems).
+
address@hidden @splitrcskeyword{} is used to avoid keyword expansion. It is
replaced by
address@hidden @asis when generating info and dvi, and by <i></i> in the
generated html,
address@hidden such that keywords are not expanded in the generated html.
+
address@hidden splitrcskeyword {arg}
+ \arg\
address@hidden macro
+
+
+
address@hidden splitrcskeyword {arg}
+ \arg\
address@hidden macro
+
address@hidden GNU Packages
address@hidden
+* CVS: (cvs). Concurrent Versions System
address@hidden direntry
address@hidden Individual utilities
address@hidden
+* cvs: (cvs)CVS commands. Concurrent Versions System
address@hidden direntry
+
address@hidden The titlepage section does not appear in the Info file.
+
address@hidden ================================================================
address@hidden The real text starts here
address@hidden ================================================================
+
address@hidden
---------------------------------------------------------------------
address@hidden Top
address@hidden
+
+This info manual describes how to use and administer
address@hidden version 4.2.
+
address@hidden
+Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
+ 2001, 2002, 2003 Free Software Foundation, Inc.
+
address@hidden @columnfractions .12 .88
address@hidden Portions
address@hidden @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003 Derek
R. Price,
address@hidden @tab Copyright @copyright{} 2002, 2003 Ximbiot
<http://ximbiot.com>,
address@hidden @tab Copyright @copyright{} 1992, 1993, 1999 Signum Support AB,
address@hidden @tab and Copyright @copyright{} others.
address@hidden multitable
+
+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 also 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 Free Software Foundation.
+
address@hidden This menu is pretty long. Not sure how easily that
address@hidden can be fixed (no brilliant ideas right away)...
address@hidden
+* Overview:: An introduction to CVS
+* Repository:: Where all your sources are stored
+* Starting a new project:: Starting a project with CVS
+* Revisions:: Numeric and symbolic names for revisions
+* Branching and merging:: Diverging/rejoining branches of development
+* Recursive behavior:: CVS descends directories
+* Adding and removing:: Adding/removing/renaming files/directories
+* History browsing:: Viewing the history of files in various ways
+
+CVS and the Real World.
+-----------------------
+* Binary files:: CVS can handle binary files
+* Multiple developers:: How CVS helps a group of developers
+* Revision management:: Policy questions for revision management
+* Keyword substitution:: CVS can include the revision inside the file
+* Tracking sources:: Tracking third-party sources
+* Builds:: Issues related to CVS and builds
+* Special Files:: Devices, links and other non-regular files
+
+References.
+-----------
+* CVS commands:: CVS commands share some things
+* Invoking CVS:: Quick reference to CVS commands
+* Administrative files:: Reference manual for the Administrative files
+* Environment variables:: All environment variables which affect CVS
+* Compatibility:: Upgrading CVS versions
+* Troubleshooting:: Some tips when nothing works
+* Credits:: Some of the contributors to this manual
+* BUGS:: Dealing with bugs in CVS or this manual
+* Index:: Index
address@hidden menu
+
address@hidden
---------------------------------------------------------------------
address@hidden Overview
address@hidden Overview
address@hidden Overview
+
+This chapter is for people who have never used
address@hidden, and perhaps have never used version control
+software before.
+
+If you are already familiar with @sc{cvs} and are just
+trying to learn a particular feature or remember a
+certain command, you can probably skip everything here.
+
address@hidden
+* What is CVS?:: What you can do with @sc{cvs}
+* What is CVS not?:: Problems @sc{cvs} doesn't try to solve
+* A sample session:: A tour of basic @sc{cvs} usage
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden What is CVS?
address@hidden What is CVS?
address@hidden What is CVS?
address@hidden Introduction to CVS
address@hidden CVS, introduction to
+
address@hidden is a version control system. Using it, you can
+record the history of your source files.
+
address@hidden -- ///
address@hidden -- ///Those who cannot remember the past are condemned to repeat
it.
address@hidden -- /// -- George Santayana
address@hidden -- //////
+
address@hidden -- Insert history quote here!
+For example, bugs sometimes creep in when
+software is modified, and you might not detect the bug
+until a long time after you make the modification.
+With @sc{cvs}, you can easily retrieve old versions to see
+exactly which change caused the bug. This can
+sometimes be a big help.
+
+You could of course save every version of every file
+you have ever created. This would
+however waste an enormous amount of disk space. @sc{cvs}
+stores all the versions of a file in a single file in a
+clever way that only stores the differences between
+versions.
+
address@hidden also helps you if you are part of a group of people working
+on the same project. It is all too easy to overwrite
+each others' changes unless you are extremely careful.
+Some editors, like @sc{gnu} Emacs, try to make sure that
+the same file is never modified by two people at the
+same time. Unfortunately, if someone is using another
+editor, that safeguard will not work. @sc{cvs} solves this problem
+by insulating the different developers from each other. Every
+developer works in his own directory, and @sc{cvs} merges
+the work when each developer is done.
+
address@hidden History of CVS
address@hidden CVS, history of
address@hidden Credits (CVS program)
address@hidden Contributors (CVS program)
address@hidden started out as a bunch of shell scripts written by
+Dick Grune, posted to the newsgroup
address@hidden in the volume 6
+release of July, 1986. While no actual code from
+these shell scripts is present in the current version
+of @sc{cvs} much of the @sc{cvs} conflict resolution algorithms
+come from them.
+
+In April, 1989, Brian Berliner designed and coded @sc{cvs}.
+Jeff Polk later helped Brian with the design of the @sc{cvs}
+module and vendor branch support.
+
address@hidden Source, getting CVS source
+You can get @sc{cvs} in a variety of ways, including
+free download from the internet. For more information
+on downloading @sc{cvs} and other @sc{cvs} topics, see:
+
address@hidden
+http://www.cvshome.org/
+http://www.loria.fr/~molli/cvs-index.html
address@hidden example
+
address@hidden Mailing list
address@hidden List, mailing list
address@hidden Newsgroups
+There is a mailing list, known as @address@hidden,
+devoted to @sc{cvs}. To subscribe or
+unsubscribe
+write to
address@hidden@code{info-cvs-request@@gnu.org}}.
+If you prefer a usenet group, the right
+group is @code{comp.software.config-mgmt} which is for
address@hidden discussions (along with other configuration
+management systems). In the future, it might be
+possible to create a
address@hidden, but probably only
+if there is sufficient @sc{cvs} traffic on
address@hidden
address@hidden Other random data is that past attempts to create a
address@hidden gnu.* group have failed (the relevant authorities
address@hidden say they'll do it, but don't), and that tale was very
address@hidden skeptical of comp.software.config-mgmt.cvs when the
address@hidden subject came up around 1995 or so (for one
address@hidden thing, because creating it would be a "reorg" which
address@hidden would need to take a more comprehensive look at the
address@hidden whole comp.software.config-mgmt.* hierarchy).
+
+You can also subscribe to the @code{bug-cvs} mailing list,
+described in more detail in @ref{BUGS}. To subscribe
+send mail to @code{bug-cvs-request@@gnu.org}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden What is CVS not?
address@hidden What is CVS not?
address@hidden What is CVS not?
+
address@hidden can do a lot of things for you, but it does
+not try to be everything for everyone.
+
address@hidden @asis
address@hidden @sc{cvs} is not a build system.
+
+Though the structure of your repository and modules
+file interact with your build system
+(e.g. @file{Makefile}s), they are essentially
+independent.
+
address@hidden does not dictate how you build anything. It
+merely stores files for retrieval in a tree structure
+you devise.
+
address@hidden does not dictate how to use disk space in the
+checked out working directories. If you write your
address@hidden or scripts in every directory so they
+have to know the relative positions of everything else,
+you wind up requiring the entire repository to be
+checked out.
+
+If you modularize your work, and construct a build
+system that will share files (via links, mounts,
address@hidden in @file{Makefile}s, etc.), you can
+arrange your disk usage however you like.
+
+But you have to remember that @emph{any} such system is
+a lot of work to construct and maintain. @sc{cvs} does
+not address the issues involved.
+
+Of course, you should place the tools created to
+support such a build system (scripts, @file{Makefile}s,
+etc) under @sc{cvs}.
+
+Figuring out what files need to be rebuilt when
+something changes is, again, something to be handled
+outside the scope of @sc{cvs}. One traditional
+approach is to use @code{make} for building, and use
+some automated tool for generating the dependencies which
address@hidden uses.
+
+See @ref{Builds}, for more information on doing builds
+in conjunction with @sc{cvs}.
+
address@hidden @sc{cvs} is not a substitute for management.
+
+Your managers and project leaders are expected to talk
+to you frequently enough to make certain you are aware
+of schedules, merge points, branch names and release
+dates. If they don't, @sc{cvs} can't help.
+
address@hidden is an instrument for making sources dance to
+your tune. But you are the piper and the composer. No
+instrument plays itself or writes its own music.
+
address@hidden @sc{cvs} is not a substitute for developer communication.
+
+When faced with conflicts within a single file, most
+developers manage to resolve them without too much
+effort. But a more general definition of ``conflict''
+includes problems too difficult to solve without
+communication between developers.
+
address@hidden cannot determine when simultaneous changes
+within a single file, or across a whole collection of
+files, will logically conflict with one another. Its
+concept of a @dfn{conflict} is purely textual, arising
+when two changes to the same base file are near enough
+to spook the merge (i.e. @code{diff3}) command.
+
address@hidden does not claim to help at all in figuring out
+non-textual or distributed conflicts in program logic.
+
+For example: Say you change the arguments to function
address@hidden defined in file @file{A}. At the same time,
+someone edits file @file{B}, adding new calls to
+function @code{X} using the old arguments. You are
+outside the realm of @sc{cvs}'s competence.
+
+Acquire the habit of reading specs and talking to your
+peers.
+
+
address@hidden @sc{cvs} does not have change control
+
+Change control refers to a number of things. First of
+all it can mean @dfn{bug-tracking}, that is being able
+to keep a database of reported bugs and the status of
+each one (is it fixed? in what release? has the bug
+submitter agreed that it is fixed?). For interfacing
address@hidden to an external bug-tracking system, see the
address@hidden and @file{verifymsg} files
+(@pxref{Administrative files}).
+
+Another aspect of change control is keeping track of
+the fact that changes to several files were in fact
+changed together as one logical change. If you check
+in several files in a single @code{cvs commit}
+operation, @sc{cvs} then forgets that those files were
+checked in together, and the fact that they have the
+same log message is the only thing tying them
+together. Keeping a @sc{gnu} style @file{ChangeLog}
+can help somewhat.
address@hidden FIXME: should have an xref to a section which talks
address@hidden more about keeping ChangeLog's with CVS, but that
address@hidden section hasn't been written yet.
+
+Another aspect of change control, in some systems, is
+the ability to keep track of the status of each
+change. Some changes have been written by a developer,
+others have been reviewed by a second developer, and so
+on. Generally, the way to do this with @sc{cvs} is to
+generate a diff (using @code{cvs diff} or @code{diff})
+and email it to someone who can then apply it using the
address@hidden utility. This is very flexible, but
+depends on mechanisms outside @sc{cvs} to make sure
+nothing falls through the cracks.
+
address@hidden @sc{cvs} is not an automated testing program
+
+It should be possible to enforce mandatory use of a
+testsuite using the @code{commitinfo} file. I haven't
+heard a lot about projects trying to do that or whether
+there are subtle gotchas, however.
+
address@hidden @sc{cvs} does not have a builtin process model
+
+Some systems provide ways to ensure that changes or
+releases go through various steps, with various
+approvals as needed. Generally, one can accomplish
+this with @sc{cvs} but it might be a little more work.
+In some cases you'll want to use the @file{commitinfo},
address@hidden, @file{rcsinfo}, or @file{verifymsg}
+files, to require that certain steps be performed
+before cvs will allow a checkin. Also consider whether
+features such as branches and tags can be used to
+perform tasks such as doing work in a development tree
+and then merging certain changes over to a stable tree
+only once they have been proven.
address@hidden table
+
address@hidden
---------------------------------------------------------------------
address@hidden A sample session
address@hidden A sample session
address@hidden Example of a work-session
address@hidden Getting started
address@hidden Work-session, example of
address@hidden tc, Trivial Compiler (example)
address@hidden Trivial Compiler (example)
+
address@hidden I think an example is a pretty good way to start. But
address@hidden somewhere in here, maybe after the sample session,
address@hidden we need something which is kind of
address@hidden a "roadmap" which is more directed at sketching out
address@hidden the functionality of CVS and pointing people to
address@hidden various other parts of the manual. As it stands now
address@hidden people who read in order get dumped right into all
address@hidden manner of hair regarding remote repositories,
address@hidden creating a repository, etc.
address@hidden
address@hidden The following was in the old Basic concepts node. I don't
address@hidden know how good a job it does at introducing modules,
address@hidden or whether they need to be introduced so soon, but
address@hidden something of this sort might go into some
address@hidden introductory material somewhere.
+
+As a way of introducing @sc{cvs}, we'll go through a
+typical work-session using @sc{cvs}. The first thing
+to understand is that @sc{cvs} stores all files in a
+centralized @dfn{repository} (@pxref{Repository}); this
+section assumes that a repository is set up.
address@hidden I'm not sure that the sentence concerning the
address@hidden repository quite tells the user what they need to
address@hidden know at this point. Might need to expand on "centralized"
address@hidden slightly (maybe not here, maybe further down in the example?)
+
+Suppose you are working on a simple compiler. The source
+consists of a handful of C files and a @file{Makefile}.
+The compiler is called @samp{tc} (Trivial Compiler),
+and the repository is set up so that there is a module
+called @samp{tc}.
+
address@hidden
+* Getting the source:: Creating a workspace
+* Committing your changes:: Making your work available to others
+* Cleaning up:: Cleaning up
+* Viewing differences:: Viewing differences
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Getting the source
address@hidden Getting the source
address@hidden Getting the source
address@hidden Checking out source
address@hidden Fetching source
address@hidden Source, getting from CVS
address@hidden Checkout, example
+
+The first thing you must do is to get your own working copy of the
+source for @samp{tc}. For this, you use the @code{checkout} command:
+
address@hidden
+$ cvs checkout tc
address@hidden example
+
address@hidden
+This will create a new directory called @file{tc} and populate it with
+the source files.
+
address@hidden
+$ cd tc
+$ ls
+CVS Makefile backend.c driver.c frontend.c parser.c
address@hidden example
+
+The @file{CVS} directory is used internally by
address@hidden Normally, you should not modify or remove
+any of the files in it.
+
+You start your favorite editor, hack away at @file{backend.c}, and a couple
+of hours later you have added an optimization pass to the compiler.
+A note to @sc{rcs} and @sc{sccs} users: There is no need to lock the files that
+you want to edit. @xref{Multiple developers}, for an explanation.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Committing your changes
address@hidden Committing your changes
address@hidden Committing changes to files
address@hidden Log message entry
+
+When you have checked that the compiler is still compilable you decide
+to make a new version of @file{backend.c}. This will
+store your new @file{backend.c} in the repository and
+make it available to anyone else who is using that same
+repository.
+
address@hidden
+$ cvs commit backend.c
address@hidden example
+
address@hidden
address@hidden starts an editor, to allow you to enter a log
+message. You type in ``Added an optimization pass.'',
+save the temporary file, and exit the editor.
+
address@hidden CVSEDITOR, environment variable
address@hidden EDITOR, environment variable
+The environment variable @code{$CVSEDITOR} determines
+which editor is started. If @code{$CVSEDITOR} is not
+set, then if the environment variable @code{$EDITOR} is
+set, it will be used. If both @code{$CVSEDITOR} and
address@hidden are not set then there is a default
+which will vary with your operating system, for example
address@hidden for unix or @code{notepad} for Windows
+NT/95.
+
address@hidden VISUAL, environment variable
+In addition, @sc{cvs} checks the @code{$VISUAL} environment
+variable. Opinions vary on whether this behavior is desirable and
+whether future releases of @sc{cvs} should check @code{$VISUAL} or
+ignore it. You will be OK either way if you make sure that
address@hidden is either unset or set to the same thing as
address@hidden
+
address@hidden This probably should go into some new node
address@hidden containing detailed info on the editor, rather than
address@hidden the intro. In fact, perhaps some of the stuff with
address@hidden CVSEDITOR and -m and so on should too.
+When @sc{cvs} starts the editor, it includes a list of
+files which are modified. For the @sc{cvs} client,
+this list is based on comparing the modification time
+of the file against the modification time that the file
+had when it was last gotten or updated. Therefore, if
+a file's modification time has changed but its contents
+have not, it will show up as modified. The simplest
+way to handle this is simply not to worry about it---if
+you proceed with the commit @sc{cvs} will detect that
+the contents are not modified and treat it as an
+unmodified file. The next @code{update} will clue
address@hidden in to the fact that the file is unmodified,
+and it will reset its stored timestamp so that the file
+will not show up in future editor sessions.
address@hidden FIXCVS: Might be nice if "commit" and other commands
address@hidden would reset that timestamp too, but currently commit
address@hidden doesn't.
address@hidden FIXME: Need to talk more about the process of
address@hidden prompting for the log message. Like show an example
address@hidden of what it pops up in the editor, for example. Also
address@hidden a discussion of how to get the "a)bort, c)ontinue,
address@hidden e)dit" prompt and what to do with it. Might also
address@hidden work in the suggestion that if you want a diff, you
address@hidden should make it before running commit (someone
address@hidden suggested that the diff pop up in the editor. I'm
address@hidden not sure that is better than telling people to run
address@hidden "cvs diff" first if that is what they want, but if
address@hidden we want to tell people that, the manual possibly
address@hidden should say it).
+
+If you want to avoid
+starting an editor you can specify the log message on
+the command line using the @samp{-m} flag instead, like
+this:
+
address@hidden
+$ cvs commit -m "Added an optimization pass" backend.c
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Cleaning up
address@hidden Cleaning up
address@hidden Cleaning up
address@hidden Working copy, removing
address@hidden Removing your working copy
address@hidden Releasing your working copy
+
+Before you turn to other tasks you decide to remove your working copy of
+tc. One acceptable way to do that is of course
+
address@hidden
+$ cd ..
+$ rm -r tc
address@hidden example
+
address@hidden
+but a better way is to use the @code{release} command (@pxref{release}):
+
address@hidden
+$ cd ..
+$ cvs release -d tc
+M driver.c
+? tc
+You have [1] altered files in this repository.
+Are you sure you want to release (and delete) directory `tc': n
+** `release' aborted by user choice.
address@hidden example
+
+The @code{release} command checks that all your modifications have been
+committed. If history logging is enabled it also makes a note in the
+history file. @xref{history file}.
+
+When you use the @samp{-d} flag with @code{release}, it
+also removes your working copy.
+
+In the example above, the @code{release} command wrote a couple of lines
+of output. @samp{? tc} means that the file @file{tc} is unknown to @sc{cvs}.
+That is nothing to worry about: @file{tc} is the executable compiler,
+and it should not be stored in the repository. @xref{cvsignore},
+for information about how to make that warning go away.
address@hidden output}, for a complete explanation of
+all possible output from @code{release}.
+
address@hidden driver.c} is more serious. It means that the
+file @file{driver.c} has been modified since it was
+checked out.
+
+The @code{release} command always finishes by telling
+you how many modified files you have in your working
+copy of the sources, and then asks you for confirmation
+before deleting any files or making any note in the
+history file.
+
+You decide to play it safe and answer @kbd{n @key{RET}}
+when @code{release} asks for confirmation.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Viewing differences
address@hidden Viewing differences
address@hidden Viewing differences
address@hidden Diff
+
+You do not remember modifying @file{driver.c}, so you want to see what
+has happened to that file.
+
address@hidden
+$ cd tc
+$ cvs diff driver.c
address@hidden example
+
+This command runs @code{diff} to compare the version of @file{driver.c}
+that you checked out with your working copy. When you see the output
+you remember that you added a command line option that enabled the
+optimization pass. You check it in, and release the module.
address@hidden FIXME: we haven't yet defined the term "check in".
+
address@hidden
+$ cvs commit -m "Added an optimization pass" driver.c
+Checking in driver.c;
+/usr/local/cvsroot/tc/driver.c,v <-- driver.c
+new revision: 1.2; previous revision: 1.1
+done
+$ cd ..
+$ cvs release -d tc
+? tc
+You have [0] altered files in this repository.
+Are you sure you want to release (and delete) directory `tc': y
address@hidden example
+
address@hidden
---------------------------------------------------------------------
address@hidden Repository
address@hidden The Repository
address@hidden Repository (intro)
address@hidden Repository, example
address@hidden Layout of repository
address@hidden Typical repository
address@hidden /usr/local/cvsroot, as example repository
address@hidden cvsroot
+
+The @sc{cvs} @dfn{repository} stores a complete copy of
+all the files and directories which are under version
+control.
+
+Normally, you never access any of the files in the
+repository directly. Instead, you use @sc{cvs}
+commands to get your own copy of the files into a
address@hidden directory}, and then
+work on that copy. When you've finished a set of
+changes, you check (or @dfn{commit}) them back into the
+repository. The repository then contains the changes
+which you have made, as well as recording exactly what
+you changed, when you changed it, and other such
+information. Note that the repository is not a
+subdirectory of the working directory, or vice versa;
+they should be in separate locations.
address@hidden Need some example, e.g. repository
address@hidden /usr/local/cvsroot; working directory
address@hidden /home/joe/sources. But this node is too long
address@hidden as it is; need a little reorganization...
+
address@hidden :local:, setting up
address@hidden can access a repository by a variety of
+means. It might be on the local computer, or it might
+be on a computer across the room or across the world.
+To distinguish various ways to access a repository, the
+repository name can start with an @dfn{access method}.
+For example, the access method @code{:local:} means to
+access a repository directory, so the repository
address@hidden:local:/usr/local/cvsroot} means that the
+repository is in @file{/usr/local/cvsroot} on the
+computer running @sc{cvs}. For information on other
+access methods, see @ref{Remote repositories}.
+
address@hidden Can se say this more concisely? Like by passing
address@hidden more of the buck to the Remote repositories node?
+If the access method is omitted, then if the repository
+starts with @samp{/}, then @code{:local:} is
+assumed. If it does not start with @samp{/} then either
address@hidden:ext:} or @code{:server:} is assumed. For
+example, if you have a local repository in
address@hidden/usr/local/cvsroot}, you can use
address@hidden/usr/local/cvsroot} instead of
address@hidden:local:/usr/local/cvsroot}. But if (under
+Windows NT, for example) your local repository is
address@hidden:\src\cvsroot}, then you must specify the access
+method, as in @code{:local:c:/src/cvsroot}.
+
address@hidden This might appear to go in Repository storage, but
address@hidden actually it is describing something which is quite
address@hidden user-visible, when you do a "cvs co CVSROOT". This
address@hidden isn't necessary the perfect place for that, though.
+The repository is split in two parts. @file{$CVSROOT/CVSROOT} contains
+administrative files for @sc{cvs}. The other directories contain the actual
+user-defined modules.
+
address@hidden
+* Specifying a repository:: Telling CVS where your repository is
+* Repository storage:: The structure of the repository
+* Working directory storage:: The structure of working directories
+* Intro administrative files:: Defining modules
+* Multiple repositories:: Multiple repositories
+* Creating a repository:: Creating a repository
+* Backing up:: Backing up a repository
+* Moving a repository:: Moving a repository
+* Remote repositories:: Accessing repositories on remote machines
+* Read-only access:: Granting read-only access to the repository
+* Server temporary directory:: The server creates temporary directories
address@hidden menu
+
address@hidden Specifying a repository
address@hidden Telling CVS where your repository is
+
+There are several ways to tell @sc{cvs}
+where to find the repository. You can name the
+repository on the command line explicitly, with the
address@hidden (for "directory") option:
+
address@hidden
+cvs -d /usr/local/cvsroot checkout yoyodyne/tc
address@hidden example
+
address@hidden .profile, setting CVSROOT in
address@hidden .cshrc, setting CVSROOT in
address@hidden .tcshrc, setting CVSROOT in
address@hidden .bashrc, setting CVSROOT in
address@hidden CVSROOT, environment variable
+ Or you can set the @code{$CVSROOT} environment
+variable to an absolute path to the root of the
+repository, @file{/usr/local/cvsroot} in this example.
+To set @code{$CVSROOT}, @code{csh} and @code{tcsh}
+users should have this line in their @file{.cshrc} or
address@hidden files:
+
address@hidden
+setenv CVSROOT /usr/local/cvsroot
address@hidden example
+
address@hidden
address@hidden and @code{bash} users should instead have these lines in their
address@hidden or @file{.bashrc}:
+
address@hidden
+CVSROOT=/usr/local/cvsroot
+export CVSROOT
address@hidden example
+
address@hidden Root file, in CVS directory
address@hidden CVS/Root file
+ A repository specified with @code{-d} will
+override the @code{$CVSROOT} environment variable.
+Once you've checked a working copy out from the
+repository, it will remember where its repository is
+(the information is recorded in the
address@hidden/Root} file in the working copy).
+
+The @code{-d} option and the @file{CVS/Root} file both
+override the @code{$CVSROOT} environment variable. If
address@hidden option differs from @file{CVS/Root}, the
+former is used. Of course, for proper operation they
+should be two ways of referring to the same repository.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Repository storage
address@hidden How data is stored in the repository
address@hidden Repository, how data is stored
+
+For most purposes it isn't important @emph{how}
address@hidden stores information in the repository. In
+fact, the format has changed in the past, and is likely
+to change in the future. Since in almost all cases one
+accesses the repository via @sc{cvs} commands, such
+changes need not be disruptive.
+
+However, in some cases it may be necessary to
+understand how @sc{cvs} stores data in the repository,
+for example you might need to track down @sc{cvs} locks
+(@pxref{Concurrency}) or you might need to deal with
+the file permissions appropriate for the repository.
+
address@hidden
+* Repository files:: What files are stored in the repository
+* File permissions:: File permissions
+* Windows permissions:: Issues specific to Windows
+* Attic:: Some files are stored in the Attic
+* CVS in repository:: Additional information in CVS directory
+* Locks:: CVS locks control concurrent accesses
+* CVSROOT storage:: A few things about CVSROOT are different
address@hidden menu
+
address@hidden Repository files
address@hidden Where files are stored within the repository
+
address@hidden @cindex Filenames, legal
address@hidden @cindex Legal filenames
address@hidden Somewhere we need to say something about legitimate
address@hidden characters in filenames in working directory and
address@hidden repository. Not "/" (not even on non-unix). And
address@hidden here is a specific set of issues:
address@hidden Files starting with a - are handled inconsistently. They can not
address@hidden be added to a repository with an add command, because it they
are
address@hidden interpreted as a switch. They can appear in a repository if
they are
address@hidden part of a tree that is imported. They can not be removed from
the tree
address@hidden once they are there.
address@hidden Note that "--" *is* supported (as a
address@hidden consequence of using GNU getopt). Should document
address@hidden this somewhere ("Common options"?). The other usual technique,
address@hidden "./-foo", isn't as effective, at least for "cvs add"
address@hidden which doesn't support pathnames containing "/".
+
+The overall structure of the repository is a directory
+tree corresponding to the directories in the working
+directory. For example, supposing the repository is in
+
address@hidden
+/usr/local/cvsroot
address@hidden example
+
address@hidden
+here is a possible directory tree (showing only the
+directories):
+
address@hidden
address@hidden/usr}
+ |
+ address@hidden
+ | |
+ | address@hidden
+ | | |
+ | | address@hidden
+ | (administrative files)
+ |
+ address@hidden
+ | |
+ | address@hidden
+ | | (source code to @sc{gnu} diff)
+ | |
+ | address@hidden
+ | | (source code to @sc{rcs})
+ | |
+ | address@hidden
+ | (source code to @sc{cvs})
+ |
+ address@hidden
+ |
+ address@hidden
+ | |
+ | address@hidden
+ | |
+ | address@hidden
+ |
+ +--(other Yoyodyne software)
address@hidden example
+
+With the directories are @dfn{history files} for each file
+under version control. The name of the history file is
+the name of the corresponding file with @samp{,v}
+appended to the end. Here is what the repository for
+the @file{yoyodyne/tc} directory might look like:
address@hidden FIXME: Should also mention CVS (CVSREP)
address@hidden FIXME? Should we introduce Attic with an xref to
address@hidden Attic? Not sure whether that is a good idea or not.
address@hidden
+ @code{$CVSROOT}
+ |
+ address@hidden
+ | |
+ | address@hidden
+ | | |
+ address@hidden,v}
+ address@hidden,v}
+ address@hidden,v}
+ address@hidden,v}
+ address@hidden,v}
+ address@hidden
+ | |
+ | address@hidden,v}
+ |
+ address@hidden
+ |
+ address@hidden,v}
+ address@hidden,v}
address@hidden example
+
address@hidden History files
address@hidden RCS history files
address@hidden The first sentence, about what history files
address@hidden contain, is kind of redundant with our intro to what the
address@hidden repository does in node Repository....
+The history files contain, among other things, enough
+information to recreate any revision of the file, a log
+of all commit messages and the user-name of the person
+who committed the revision. The history files are
+known as @dfn{RCS files}, because the first program to
+store files in that format was a version control system
+known as @sc{rcs}. For a full
+description of the file format, see the @code{man} page
address@hidden(5)}, distributed with @sc{rcs}, or the
+file @file{doc/RCSFILES} in the @sc{cvs} source
+distribution. This
+file format has become very common---many systems other
+than @sc{cvs} or @sc{rcs} can at least import history
+files in this format.
address@hidden FIXME: Think about including documentation for this
address@hidden rather than citing it? In the long run, getting
address@hidden this to be a standard (not sure if we can cope with
address@hidden a standards process as formal as IEEE/ANSI/ISO/etc,
address@hidden though...) is the way to go, so maybe citing is
address@hidden better.
+
+The @sc{rcs} files used in @sc{cvs} differ in a few
+ways from the standard format. The biggest difference
+is magic branches; for more information see @ref{Magic
+branch numbers}. Also in @sc{cvs} the valid tag names
+are a subset of what @sc{rcs} accepts; for @sc{cvs}'s
+rules see @ref{Tags}.
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden File permissions
address@hidden File permissions
address@hidden -- Move this to @node Creating a repository or similar
address@hidden Security, file permissions in repository
address@hidden File permissions, general
address@hidden Permissions, general
address@hidden FIXME: we need to somehow reflect "permissions in
address@hidden repository" versus "permissions in working
address@hidden directory" in the index entries.
address@hidden Group
address@hidden Read-only files, in repository
+All @samp{,v} files are created read-only, and you
+should not change the permission of those files. The
+directories inside the repository should be writable by
+the persons that have permission to modify the files in
+each directory. This normally means that you must
+create a UNIX group (see group(5)) consisting of the
+persons that are to edit the files in a project, and
+set up the repository so that it is that group that
+owns the directory.
+(On some systems, you also need to set the set-group-ID-on-execution bit
+on the repository directories (see chmod(1)) so that newly-created files
+and directories get the group-ID of the parent directory rather than
+that of the current process.)
+
address@hidden See also comment in commitinfo node regarding cases
address@hidden which are really awkward with unix groups.
+
+This means that you can only control access to files on
+a per-directory basis.
+
+Note that users must also have write access to check
+out files, because @sc{cvs} needs to create lock files
+(@pxref{Concurrency}). You can use LockDir in CVSROOT/config
+to put the lock files somewhere other than in the repository
+if you want to allow read-only access to some directories
+(@pxref{config}).
+
address@hidden CVS seems to use CVSUMASK in picking permissions for
address@hidden val-tags, but maybe we should say more about this.
address@hidden Like val-tags gets created by someone who doesn't
address@hidden have CVSUMASK set right?
+Also note that users must have write access to the
address@hidden/val-tags} file. @sc{cvs} uses it to keep
+track of what tags are valid tag names (it is sometimes
+updated when tags are used, as well as when they are
+created).
+
+Each @sc{rcs} file will be owned by the user who last
+checked it in. This has little significance; what
+really matters is who owns the directories.
+
address@hidden CVSUMASK, environment variable
address@hidden Umask, for repository files
address@hidden tries to set up reasonable file permissions
+for new directories that are added inside the tree, but
+you must fix the permissions manually when a new
+directory should have different permissions than its
+parent directory. If you set the @code{CVSUMASK}
+environment variable that will control the file
+permissions which @sc{cvs} uses in creating directories
+and/or files in the repository. @code{CVSUMASK} does
+not affect the file permissions in the working
+directory; such files have the permissions which are
+typical for newly created files, except that sometimes
address@hidden creates them read-only (see the sections on
+watches, @ref{Setting a watch}; -r, @ref{Global
+options}; or @code{CVSREAD}, @ref{Environment variables}).
address@hidden FIXME: Need more discussion of which
address@hidden group should own the file in the repository.
address@hidden Include a somewhat detailed example of the usual
address@hidden case where CVSUMASK is 007, the developers are all
address@hidden in a group, and that group owns stuff in the
address@hidden repository. Need to talk about group ownership of
address@hidden newly-created directories/files (on some unices,
address@hidden such as SunOS4, setting the setgid bit on the
address@hidden directories will make files inherit the directory's
address@hidden group. On other unices, your mileage may vary. I
address@hidden can't remember what POSIX says about this, if
address@hidden anything).
+
+Note that using the client/server @sc{cvs}
+(@pxref{Remote repositories}), there is no good way to
+set @code{CVSUMASK}; the setting on the client machine
+has no effect. If you are connecting with @code{rsh}, you
+can set @code{CVSUMASK} in @file{.bashrc} or @file{.cshrc}, as
+described in the documentation for your operating
+system. This behavior might change in future versions
+of @sc{cvs}; do not rely on the setting of
address@hidden on the client having no effect.
address@hidden FIXME: need to explain what a umask is or cite
address@hidden someplace which does.
address@hidden
address@hidden There is also a larger (largely separate) issue
address@hidden about the meaning of CVSUMASK in a non-unix context.
address@hidden For example, whether there is
address@hidden an equivalent which fits better into other
address@hidden protection schemes like POSIX.6, VMS, &c.
address@hidden
address@hidden FIXME: Need one place which discusses this
address@hidden read-only files thing. Why would one use -r or
address@hidden CVSREAD? Why would one use watches? How do they
address@hidden interact?
address@hidden
address@hidden FIXME: We need to state
address@hidden whether using CVSUMASK removes the need for manually
address@hidden fixing permissions (in fact, if we are going to mention
address@hidden manually fixing permission, we better document a lot
address@hidden better just what we mean by "fix").
+
+Using pserver, you will generally need stricter
+permissions on the @sc{cvsroot} directory and
+directories above it in the tree; see @ref{Password
+authentication security}.
+
address@hidden Setuid
address@hidden Setgid
address@hidden Security, setuid
address@hidden Installed images (VMS)
+Some operating systems have features which allow a
+particular program to run with the ability to perform
+operations which the caller of the program could not.
+For example, the set user ID (setuid) or set group ID
+(setgid) features of unix or the installed image
+feature of VMS. @sc{cvs} was not written to use such
+features and therefore attempting to install @sc{cvs} in
+this fashion will provide protection against only
+accidental lapses; anyone who is trying to circumvent
+the measure will be able to do so, and depending on how
+you have set it up may gain access to more than just
address@hidden You may wish to instead consider pserver. It
+shares some of the same attributes, in terms of
+possibly providing a false sense of security or opening
+security holes wider than the ones you are trying to
+fix, so read the documentation on pserver security
+carefully if you are considering this option
+(@ref{Password authentication security}).
+
address@hidden Windows permissions
address@hidden File Permission issues specific to Windows
address@hidden Windows, and permissions
address@hidden File permissions, Windows-specific
address@hidden Permissions, Windows-specific
+
+Some file permission issues are specific to Windows
+operating systems (Windows 95, Windows NT, and
+presumably future operating systems in this family.
+Some of the following might apply to OS/2 but I'm not
+sure).
+
+If you are using local @sc{cvs} and the repository is on a
+networked file system which is served by the Samba SMB
+server, some people have reported problems with
+permissions. Enabling WRITE=YES in the samba
+configuration is said to fix/workaround it.
+Disclaimer: I haven't investigated enough to know the
+implications of enabling that option, nor do I know
+whether there is something which @sc{cvs} could be doing
+differently in order to avoid the problem. If you find
+something out, please let us know as described in
address@hidden
+
address@hidden Attic
address@hidden The attic
address@hidden Attic
+
+You will notice that sometimes @sc{cvs} stores an
address@hidden file in the @code{Attic}. For example, if the
address@hidden is @file{/usr/local/cvsroot} and we are
+talking about the file @file{backend.c} in the
+directory @file{yoyodyne/tc}, then the file normally
+would be in
+
address@hidden
+/usr/local/cvsroot/yoyodyne/tc/backend.c,v
address@hidden example
+
address@hidden
+but if it goes in the attic, it would be in
+
address@hidden
+/usr/local/cvsroot/yoyodyne/tc/Attic/backend.c,v
address@hidden example
+
address@hidden
address@hidden Dead state
+instead. It should not matter from a user point of
+view whether a file is in the attic; @sc{cvs} keeps
+track of this and looks in the attic when it needs to.
+But in case you want to know, the rule is that the RCS
+file is stored in the attic if and only if the head
+revision on the trunk has state @code{dead}. A
address@hidden state means that file has been removed, or
+never added, for that revision. For example, if you
+add a file on a branch, it will have a trunk revision
+in @code{dead} state, and a branch revision in a
address@hidden state.
address@hidden Probably should have some more concrete examples
address@hidden here, or somewhere (not sure exactly how we should
address@hidden arrange the discussion of the dead state, versus
address@hidden discussion of the attic).
+
address@hidden CVS in repository
address@hidden The CVS directory in the repository
address@hidden CVS directory, in repository
+
+The @file{CVS} directory in each repository directory
+contains information such as file attributes (in a file
+called @file{CVS/fileattr}. In the
+future additional files may be added to this directory,
+so implementations should silently ignore additional
+files.
+
+This behavior is implemented only by @sc{cvs} 1.7 and
+later; for details see @ref{Watches Compatibility}.
+
+The format of the fileattr file is a series of entries
+of the following form (where @address@hidden and @address@hidden
+means the text between the braces can be repeated zero
+or more times):
+
address@hidden @var{filename} <tab> @var{attrname} = @var{attrval}
+ @{; @var{attrname} = @address@hidden <linefeed>
+
address@hidden is @samp{F} for a file, in which case the entry specifies the
+attributes for that file.
+
address@hidden is @samp{D},
+and @var{filename} empty, to specify default attributes
+to be used for newly added files.
+
+Other @var{ent-type} are reserved for future expansion. @sc{cvs} 1.9 and older
+will delete them any time it writes file attributes.
address@hidden 1.10 and later will preserve them.
+
+Note that the order of the lines is not significant;
+a program writing the fileattr file may
+rearrange them at its convenience.
+
+There is currently no way of quoting tabs or linefeeds in the
+filename, @samp{=} in @var{attrname},
address@hidden;} in @var{attrval}, etc. Note: some implementations also
+don't handle a NUL character in any of the fields, but
+implementations are encouraged to allow it.
+
+By convention, @var{attrname} starting with @samp{_} is for an attribute given
+special meaning by @sc{cvs}; other @var{attrname}s are for user-defined
attributes
+(or will be, once implementations start supporting user-defined attributes).
+
+Builtin attributes:
+
address@hidden @code
address@hidden _watched
+Present means the file is watched and should be checked out
+read-only.
+
address@hidden _watchers
+Users with watches for this file. Value is
address@hidden > @var{type} @{ , @var{watcher} > @var{type} @}
+where @var{watcher} is a username, and @var{type}
+is zero or more of edit,unedit,commit separated by
address@hidden (that is, nothing if none; there is no "none" or "all" keyword).
+
address@hidden _editors
+Users editing this file. Value is
address@hidden > @var{val} @{ , @var{editor} > @var{val} @}
+where @var{editor} is a username, and @var{val} is
address@hidden@address@hidden, where
address@hidden is when the @code{cvs edit} command (or
+equivalent) happened,
+and @var{hostname} and @var{pathname} are for the working directory.
address@hidden table
+
+Example:
+
address@hidden FIXME: sanity.sh should contain a similar test case
address@hidden so we can compare this example from something from
address@hidden Real Life(TM). See cvsclient.texi (under Notify) for more
address@hidden discussion of the date format of _editors.
address@hidden
+Ffile1 _watched=;_watchers=joe>edit,mary>commit
+Ffile2 _watched=;_editors=sue>8 Jan 1975+workstn1+/home/sue/cvs
+D _watched=
address@hidden example
+
address@hidden
+means that the file @file{file1} should be checked out
+read-only. Furthermore, joe is watching for edits and
+mary is watching for commits. The file @file{file2}
+should be checked out read-only; sue started editing it
+on 8 Jan 1975 in the directory @file{/home/sue/cvs} on
+the machine @code{workstn1}. Future files which are
+added should be checked out read-only. To represent
+this example here, we have shown a space after
address@hidden, @samp{Ffile1}, and @samp{Ffile2}, but in fact
+there must be a single tab character there and no spaces.
+
address@hidden Locks
address@hidden CVS locks in the repository
+
address@hidden #cvs.rfl, technical details
address@hidden #cvs.wfl, technical details
address@hidden #cvs.lock, technical details
address@hidden Locks, cvs, technical details
+For an introduction to @sc{cvs} locks focusing on
+user-visible behavior, see @ref{Concurrency}. The
+following section is aimed at people who are writing
+tools which want to access a @sc{cvs} repository without
+interfering with other tools accessing the same
+repository. If you find yourself confused by concepts
+described here, like @dfn{read lock}, @dfn{write lock},
+and @dfn{deadlock}, you might consult the literature on
+operating systems or databases.
+
address@hidden #cvs.tfl
+Any file in the repository with a name starting
+with @file{#cvs.rfl.} is a read lock. Any file in
+the repository with a name starting with
address@hidden is a write lock. Old versions of @sc{cvs}
+(before @sc{cvs} 1.5) also created files with names starting
+with @file{#cvs.tfl}, but they are not discussed here.
+The directory @file{#cvs.lock} serves as a master
+lock. That is, one must obtain this lock first before
+creating any of the other locks.
+
+To obtain a readlock, first create the @file{#cvs.lock}
+directory. This operation must be atomic (which should
+be true for creating a directory under most operating
+systems). If it fails because the directory already
+existed, wait for a while and try again. After
+obtaining the @file{#cvs.lock} lock, create a file
+whose name is @file{#cvs.rfl.} followed by information
+of your choice (for example, hostname and process
+identification number). Then remove the
address@hidden directory to release the master lock.
+Then proceed with reading the repository. When you are
+done, remove the @file{#cvs.rfl} file to release the
+read lock.
+
+To obtain a writelock, first create the
address@hidden directory, as with a readlock. Then
+check that there are no files whose names start with
address@hidden If there are, remove
address@hidden, wait for a while, and try again. If
+there are no readers, then create a file whose name is
address@hidden followed by information of your choice
+(for example, hostname and process identification
+number). Hang on to the @file{#cvs.lock} lock. Proceed
+with writing the repository. When you are done, first
+remove the @file{#cvs.wfl} file and then the
address@hidden directory. Note that unlike the
address@hidden file, the @file{#cvs.wfl} file is just
+informational; it has no effect on the locking operation
+beyond what is provided by holding on to the
address@hidden lock itself.
+
+Note that each lock (writelock or readlock) only locks
+a single directory in the repository, including
address@hidden and @file{CVS} but not including
+subdirectories which represent other directories under
+version control. To lock an entire tree, you need to
+lock each directory (note that if you fail to obtain
+any lock you need, you must release the whole tree
+before waiting and trying again, to avoid deadlocks).
+
+Note also that @sc{cvs} expects writelocks to control
+access to individual @file{foo,v} files. @sc{rcs} has
+a scheme where the @file{,foo,} file serves as a lock,
+but @sc{cvs} does not implement it and so taking out a
address@hidden writelock is recommended. See the comments at
+rcs_internal_lockfile in the @sc{cvs} source code for
+further discussion/rationale.
+
address@hidden CVSROOT storage
address@hidden How files are stored in the CVSROOT directory
address@hidden CVSROOT, storage of files
+
+The @file{$CVSROOT/CVSROOT} directory contains the
+various administrative files. In some ways this
+directory is just like any other directory in the
+repository; it contains @sc{rcs} files whose names end
+in @samp{,v}, and many of the @sc{cvs} commands operate
+on it the same way. However, there are a few
+differences.
+
+For each administrative file, in addition to the
address@hidden file, there is also a checked out copy of the
+file. For example, there is an @sc{rcs} file
address@hidden,v} and a file @file{loginfo} which
+contains the latest revision contained in
address@hidden,v}. When you check in an administrative
+file, @sc{cvs} should print
+
address@hidden
+cvs commit: Rebuilding administrative file database
address@hidden example
+
address@hidden
+and update the checked out copy in
address@hidden/CVSROOT}. If it does not, there is
+something wrong (@pxref{BUGS}). To add your own files
+to the files to be updated in this fashion, you can add
+them to the @file{checkoutlist} administrative file
+(@pxref{checkoutlist}).
+
address@hidden modules.db
address@hidden modules.pag
address@hidden modules.dir
+By default, the @file{modules} file behaves as
+described above. If the modules file is very large,
+storing it as a flat text file may make looking up
+modules slow (I'm not sure whether this is as much of a
+concern now as when @sc{cvs} first evolved this
+feature; I haven't seen benchmarks). Therefore, by
+making appropriate edits to the @sc{cvs} source code
+one can store the modules file in a database which
+implements the @code{ndbm} interface, such as Berkeley
+db or GDBM. If this option is in use, then the modules
+database will be stored in the files @file{modules.db},
address@hidden, and/or @file{modules.dir}.
address@hidden I think fileattr also will use the database stuff.
address@hidden Anything else?
+
+For information on the meaning of the various
+administrative files, see @ref{Administrative files}.
+
address@hidden Working directory storage
address@hidden How data is stored in the working directory
+
address@hidden FIXME: Somewhere we should discuss timestamps (test
address@hidden case "stamps" in sanity.sh). But not here. Maybe
address@hidden in some kind of "working directory" chapter which
address@hidden would encompass the "Builds" one? But I'm not sure
address@hidden whether that is a good organization (is it based on
address@hidden what the user wants to do?).
+
address@hidden CVS directory, in working directory
+While we are discussing @sc{cvs} internals which may
+become visible from time to time, we might as well talk
+about what @sc{cvs} puts in the @file{CVS} directories
+in the working directories. As with the repository,
address@hidden handles this information and one can usually
+access it via @sc{cvs} commands. But in some cases it
+may be useful to look at it, and other programs, such
+as the @code{jCVS} graphical user interface or the
address@hidden package for emacs, may need to look at it.
+Such programs should follow the recommendations in this
+section if they hope to be able to work with other
+programs which use those files, including future
+versions of the programs just mentioned and the
+command-line @sc{cvs} client.
+
+The @file{CVS} directory contains several files.
+Programs which are reading this directory should
+silently ignore files which are in the directory but
+which are not documented here, to allow for future
+expansion.
+
+The files are stored according to the text file
+convention for the system in question. This means that
+working directories are not portable between systems
+with differing conventions for storing text files.
+This is intentional, on the theory that the files being
+managed by @sc{cvs} probably will not be portable between
+such systems either.
+
address@hidden @file
address@hidden Root
+This file contains the current @sc{cvs} root, as
+described in @ref{Specifying a repository}.
+
address@hidden Repository file, in CVS directory
address@hidden CVS/Repository file
address@hidden Repository
+This file contains the directory within the repository
+which the current directory corresponds with. It can
+be either an absolute pathname or a relative pathname;
address@hidden has had the ability to read either format
+since at least version 1.3 or so. The relative
+pathname is relative to the root, and is the more
+sensible approach, but the absolute pathname is quite
+common and implementations should accept either. For
+example, after the command
+
address@hidden
+cvs -d :local:/usr/local/cvsroot checkout yoyodyne/tc
address@hidden example
+
address@hidden
address@hidden will contain
+
address@hidden
+:local:/usr/local/cvsroot
address@hidden example
+
address@hidden
+and @file{Repository} will contain either
+
address@hidden
+/usr/local/cvsroot/yoyodyne/tc
address@hidden example
+
address@hidden
+or
+
address@hidden
+yoyodyne/tc
address@hidden example
+
+If the particular working directory does not correspond
+to a directory in the repository, then @file{Repository}
+should contain @file{CVSROOT/Emptydir}.
address@hidden Emptydir, in CVSROOT directory
address@hidden CVSROOT/Emptydir directory
+
address@hidden Entries file, in CVS directory
address@hidden CVS/Entries file
address@hidden Entries
+This file lists the files and directories in the
+working directory.
+The first character of each line indicates what sort of
+line it is. If the character is unrecognized, programs
+reading the file should silently skip that line, to
+allow for future expansion.
+
+If the first character is @samp{/}, then the format is:
+
address@hidden
+/@var{name}/@var{revision}/@address@hidden/@var{options}/@var{tagdate}
address@hidden example
+
address@hidden
+where @samp{[} and @samp{]} are not part of the entry,
+but instead indicate that the @samp{+} and conflict
+marker are optional. @var{name} is the name of the
+file within the directory. @var{revision} is the
+revision that the file in the working derives from, or
address@hidden for an added file, or @samp{-} followed by a
+revision for a removed file. @var{timestamp} is the
+timestamp of the file at the time that @sc{cvs} created
+it; if the timestamp differs with the actual
+modification time of the file it means the file has
+been modified. It is stored in
+the format used by the ISO C asctime() function (for
+example, @samp{Sun Apr 7 01:29:26 1996}). One may
+write a string which is not in that format, for
+example, @samp{Result of merge}, to indicate that the
+file should always be considered to be modified. This
+is not a special case; to see whether a file is
+modified a program should take the timestamp of the file
+and simply do a string compare with @var{timestamp}.
+If there was a conflict, @var{conflict} can be set to
+the modification time of the file after the file has been
+written with conflict markers (@pxref{Conflicts example}).
+Thus if @var{conflict} is subsequently the same as the actual
+modification time of the file it means that the user
+has obviously not resolved the conflict. @var{options}
+contains sticky options (for example @samp{-kb} for a
+binary file). @var{tagdate} contains @samp{T} followed
+by a tag name, or @samp{D} for a date, followed by a
+sticky tag or date. Note that if @var{timestamp}
+contains a pair of timestamps separated by a space,
+rather than a single timestamp, you are dealing with a
+version of @sc{cvs} earlier than @sc{cvs} 1.5 (not
+documented here).
+
+The timezone on the timestamp in CVS/Entries (local or
+universal) should be the same as the operating system
+stores for the timestamp of the file itself. For
+example, on Unix the file's timestamp is in universal
+time (UT), so the timestamp in CVS/Entries should be
+too. On @sc{vms}, the file's timestamp is in local
+time, so @sc{cvs} on @sc{vms} should use local time.
+This rule is so that files do not appear to be modified
+merely because the timezone changed (for example, to or
+from summer time).
address@hidden See comments and calls to gmtime() and friends in
address@hidden src/vers_ts.c (function time_stamp).
+
+If the first character of a line in @file{Entries} is
address@hidden, then it indicates a subdirectory. @samp{D}
+on a line all by itself indicates that the program
+which wrote the @file{Entries} file does record
+subdirectories (therefore, if there is such a line and
+no other lines beginning with @samp{D}, one knows there
+are no subdirectories). Otherwise, the line looks
+like:
+
address@hidden
+D/@var{name}/@var{filler1}/@var{filler2}/@var{filler3}/@var{filler4}
address@hidden example
+
address@hidden
+where @var{name} is the name of the subdirectory, and
+all the @var{filler} fields should be silently ignored,
+for future expansion. Programs which modify
address@hidden files should preserve these fields.
+
+The lines in the @file{Entries} file can be in any order.
+
address@hidden Entries.Log file, in CVS directory
address@hidden CVS/Entries.Log file
address@hidden Entries.Log
+This file does not record any information beyond that
+in @file{Entries}, but it does provide a way to update
+the information without having to rewrite the entire
address@hidden file, including the ability to preserve
+the information even if the program writing
address@hidden and @file{Entries.Log} abruptly aborts.
+Programs which are reading the @file{Entries} file
+should also check for @file{Entries.Log}. If the latter
+exists, they should read @file{Entries} and then apply
+the changes mentioned in @file{Entries.Log}. After
+applying the changes, the recommended practice is to
+rewrite @file{Entries} and then delete @file{Entries.Log}.
+The format of a line in @file{Entries.Log} is a single
+character command followed by a space followed by a
+line in the format specified for a line in
address@hidden The single character command is
address@hidden to indicate that the entry is being added,
address@hidden to indicate that the entry is being removed,
+or any other character to indicate that the entire line
+in @file{Entries.Log} should be silently ignored (for
+future expansion). If the second character of the line
+in @file{Entries.Log} is not a space, then it was
+written by an older version of @sc{cvs} (not documented
+here).
+
+Programs which are writing rather than reading can
+safely ignore @file{Entries.Log} if they so choose.
+
address@hidden Entries.Backup file, in CVS directory
address@hidden CVS/Entries.Backup file
address@hidden Entries.Backup
+This is a temporary file. Recommended usage is to
+write a new entries file to @file{Entries.Backup}, and
+then to rename it (atomically, where possible) to @file{Entries}.
+
address@hidden Entries.Static file, in CVS directory
address@hidden CVS/Entries.Static file
address@hidden Entries.Static
+The only relevant thing about this file is whether it
+exists or not. If it exists, then it means that only
+part of a directory was gotten and @sc{cvs} will
+not create additional files in that directory. To
+clear it, use the @code{update} command with the
address@hidden option, which will get the additional files
+and remove @file{Entries.Static}.
address@hidden FIXME: This needs to be better documented, in places
address@hidden other than Working Directory Storage.
address@hidden FIXCVS: The fact that this setting exists needs to
address@hidden be more visible to the user. For example "cvs
address@hidden status foo", in the case where the file would be
address@hidden gotten except for Entries.Static, might say
address@hidden something to distinguish this from other cases.
address@hidden One thing that periodically gets suggested is to
address@hidden have "cvs update" print something when it skips
address@hidden files due to Entries.Static, but IMHO that kind of
address@hidden noise pretty much makes the Entries.Static feature
address@hidden useless.
+
address@hidden Tag file, in CVS directory
address@hidden CVS/Tag file
address@hidden Sticky tags/dates, per-directory
address@hidden Per-directory sticky tags/dates
address@hidden Tag
+This file contains per-directory sticky tags or dates.
+The first character is @samp{T} for a branch tag,
address@hidden for a non-branch tag, or @samp{D} for a date,
+or another character to mean the file should be
+silently ignored, for future expansion. This character
+is followed by the tag or date. Note that
+per-directory sticky tags or dates are used for things
+like applying to files which are newly added; they
+might not be the same as the sticky tags or dates on
+individual files. For general information on sticky
+tags and dates, see @ref{Sticky tags}.
address@hidden FIXME: This needs to be much better documented,
address@hidden preferably not in the context of "working directory
address@hidden storage".
address@hidden FIXME: The Sticky tags node needs to discuss, or xref to
address@hidden someplace which discusses, per-directory sticky
address@hidden tags and the distinction with per-file sticky tags.
+
address@hidden Notify file, in CVS directory
address@hidden CVS/Notify file
address@hidden Notify
+This file stores notifications (for example, for
address@hidden or @code{unedit}) which have not yet been
+sent to the server. Its format is not yet documented
+here.
+
address@hidden Notify.tmp file, in CVS directory
address@hidden CVS/Notify.tmp file
address@hidden Notify.tmp
+This file is to @file{Notify} as @file{Entries.Backup}
+is to @file{Entries}. That is, to write @file{Notify},
+first write the new contents to @file{Notify.tmp} and
+then (atomically where possible), rename it to
address@hidden
+
address@hidden Base directory, in CVS directory
address@hidden CVS/Base directory
address@hidden Base
+If watches are in use, then an @code{edit} command
+stores the original copy of the file in the @file{Base}
+directory. This allows the @code{unedit} command to
+operate even if it is unable to communicate with the
+server.
+
address@hidden Baserev file, in CVS directory
address@hidden CVS/Baserev file
address@hidden Baserev
+The file lists the revision for each of the files in
+the @file{Base} directory. The format is:
+
address@hidden
address@hidden/@var{rev}/@var{expansion}
address@hidden example
+
address@hidden
+where @var{expansion} should be ignored, to allow for
+future expansion.
+
address@hidden Baserev.tmp file, in CVS directory
address@hidden CVS/Baserev.tmp file
address@hidden Baserev.tmp
+This file is to @file{Baserev} as @file{Entries.Backup}
+is to @file{Entries}. That is, to write @file{Baserev},
+first write the new contents to @file{Baserev.tmp} and
+then (atomically where possible), rename it to
address@hidden
+
address@hidden Template file, in CVS directory
address@hidden CVS/Template file
address@hidden Template
+This file contains the template specified by the
address@hidden file (@pxref{rcsinfo}). It is only used
+by the client; the non-client/server @sc{cvs} consults
address@hidden directly.
address@hidden table
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Intro administrative files
address@hidden The administrative files
address@hidden Administrative files (intro)
address@hidden Modules file
address@hidden CVSROOT, module name
address@hidden Defining modules (intro)
+
address@hidden FIXME: this node should be reorganized into "general
address@hidden information about admin files" and put the "editing
address@hidden admin files" stuff up front rather than jumping into
address@hidden the details of modules right away. Then the
address@hidden Administrative files node can go away, the information
address@hidden on each admin file distributed to a place appropriate
address@hidden to its function, and this node can contain a table
address@hidden listing each file and a @ref to its detailed description.
+
+The directory @file{$CVSROOT/CVSROOT} contains some @dfn{administrative
+files}. @xref{Administrative files}, for a complete description.
+You can use @sc{cvs} without any of these files, but
+some commands work better when at least the
address@hidden file is properly set up.
+
+The most important of these files is the @file{modules}
+file. It defines all modules in the repository. This
+is a sample @file{modules} file.
+
address@hidden FIXME: The CVSROOT line is a goofy example now that
address@hidden mkmodules doesn't exist.
address@hidden
+CVSROOT CVSROOT
+modules CVSROOT modules
+cvs gnu/cvs
+rcs gnu/rcs
+diff gnu/diff
+tc yoyodyne/tc
address@hidden example
+
+The @file{modules} file is line oriented. In its
+simplest form each line contains the name of the
+module, whitespace, and the directory where the module
+resides. The directory is a path relative to
address@hidden The last four lines in the example
+above are examples of such lines.
+
address@hidden FIXME: might want to introduce the concept of options in modules
file
address@hidden (the old example which was here, -i mkmodules, is obsolete).
+
+The line that defines the module called @samp{modules}
+uses features that are not explained here.
address@hidden, for a full explanation of all the
+available features.
+
address@hidden FIXME: subsection without node is bogus
address@hidden Editing administrative files
address@hidden Editing administrative files
address@hidden Administrative files, editing them
+
+You edit the administrative files in the same way that you would edit
+any other module. Use @samp{cvs checkout CVSROOT} to get a working
+copy, edit it, and commit your changes in the normal way.
+
+It is possible to commit an erroneous administrative
+file. You can often fix the error and check in a new
+revision, but sometimes a particularly bad error in the
+administrative file makes it impossible to commit new
+revisions.
address@hidden @xref{Bad administrative files} for a hint
address@hidden about how to solve such situations.
address@hidden -- administrative file checking--
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Multiple repositories
address@hidden Multiple repositories
address@hidden Multiple repositories
address@hidden Repositories, multiple
address@hidden Many repositories
address@hidden Parallel repositories
address@hidden Disjoint repositories
address@hidden CVSROOT, multiple repositories
+
+In some situations it is a good idea to have more than
+one repository, for instance if you have two
+development groups that work on separate projects
+without sharing any code. All you have to do to have
+several repositories is to specify the appropriate
+repository, using the @code{CVSROOT} environment
+variable, the @samp{-d} option to @sc{cvs}, or (once
+you have checked out a working directory) by simply
+allowing @sc{cvs} to use the repository that was used
+to check out the working directory
+(@pxref{Specifying a repository}).
+
+The big advantage of having multiple repositories is
+that they can reside on different servers. With @sc{cvs}
+version 1.10, a single command cannot recurse into
+directories from different repositories. With development
+versions of @sc{cvs}, you can check out code from multiple
+servers into your working directory. @sc{cvs} will
+recurse and handle all the details of making
+connections to as many server machines as necessary to
+perform the requested command. Here is an example of
+how to set up a working directory:
+
address@hidden
+cvs -d server1:/cvs co dir1
+cd dir1
+cvs -d server2:/root co sdir
+cvs update
address@hidden example
+
+The @code{cvs co} commands set up the working
+directory, and then the @code{cvs update} command will
+contact server2, to update the dir1/sdir subdirectory,
+and server1, to update everything else.
+
address@hidden FIXME: Does the FAQ have more about this? I have a
address@hidden dim recollection, but I'm too lazy to check right now.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Creating a repository
address@hidden Creating a repository
+
address@hidden Repository, setting up
address@hidden Creating a repository
address@hidden Setting up a repository
+
+To set up a @sc{cvs} repository, first choose the
+machine and disk on which you want to store the
+revision history of the source files. CPU and memory
+requirements are modest, so most machines should be
+adequate. For details see @ref{Server requirements}.
address@hidden Possible that we should be providing a quick rule of
address@hidden thumb, like the 32M memory for the server. That
address@hidden might increase the number of people who are happy
address@hidden with the answer, without following the xref.
+
+To estimate disk space
+requirements, if you are importing RCS files from
+another system, the size of those files is the
+approximate initial size of your repository, or if you
+are starting without any version history, a rule of
+thumb is to allow for the server approximately three
+times the size of the code to be under @sc{cvs} for the
+repository (you will eventually outgrow this, but not
+for a while). On the machines on which the developers
+will be working, you'll want disk space for
+approximately one working directory for each developer
+(either the entire tree or a portion of it, depending
+on what each developer uses).
+
+The repository should be accessible
+(directly or via a networked file system) from all
+machines which want to use @sc{cvs} in server or local
+mode; the client machines need not have any access to
+it other than via the @sc{cvs} protocol. It is not
+possible to use @sc{cvs} to read from a repository
+which one only has read access to; @sc{cvs} needs to be
+able to create lock files (@pxref{Concurrency}).
+
address@hidden init (subcommand)
+To create a repository, run the @code{cvs init}
+command. It will set up an empty repository in the
address@hidden root specified in the usual way
+(@pxref{Repository}). For example,
+
address@hidden
+cvs -d /usr/local/cvsroot init
address@hidden example
+
address@hidden init} is careful to never overwrite any
+existing files in the repository, so no harm is done if
+you run @code{cvs init} on an already set-up
+repository.
+
address@hidden init} will enable history logging; if you
+don't want that, remove the history file after running
address@hidden init}. @xref{history file}.
+
address@hidden Backing up
address@hidden Backing up a repository
address@hidden Repository, backing up
address@hidden Backing up, repository
+
+There is nothing particularly magical about the files
+in the repository; for the most part it is possible to
+back them up just like any other files. However, there
+are a few issues to consider.
+
address@hidden Locks, cvs, and backups
address@hidden #cvs.rfl, and backups
+The first is that to be paranoid, one should either not
+use @sc{cvs} during the backup, or have the backup
+program lock @sc{cvs} while doing the backup. To not
+use @sc{cvs}, you might forbid logins to machines which
+can access the repository, turn off your @sc{cvs}
+server, or similar mechanisms. The details would
+depend on your operating system and how you have
address@hidden set up. To lock @sc{cvs}, you would create
address@hidden locks in each repository directory.
+See @ref{Concurrency}, for more on @sc{cvs} locks.
+Having said all this, if you just back up without any
+of these precautions, the results are unlikely to be
+particularly dire. Restoring from backup, the
+repository might be in an inconsistent state, but this
+would not be particularly hard to fix manually.
+
+When you restore a repository from backup, assuming
+that changes in the repository were made after the time
+of the backup, working directories which were not
+affected by the failure may refer to revisions which no
+longer exist in the repository. Trying to run @sc{cvs}
+in such directories will typically produce an error
+message. One way to get those changes back into the
+repository is as follows:
+
address@hidden @bullet
address@hidden
+Get a new working directory.
+
address@hidden
+Copy the files from the working directory from before
+the failure over to the new working directory (do not
+copy the contents of the @file{CVS} directories, of
+course).
+
address@hidden
+Working in the new working directory, use commands such
+as @code{cvs update} and @code{cvs diff} to figure out
+what has changed, and then when you are ready, commit
+the changes into the repository.
address@hidden itemize
+
address@hidden Moving a repository
address@hidden Moving a repository
address@hidden Repository, moving
address@hidden Moving a repository
address@hidden Copying a repository
+
+Just as backing up the files in the repository is
+pretty much like backing up any other files, if you
+need to move a repository from one place to another it
+is also pretty much like just moving any other
+collection of files.
+
+The main thing to consider is that working directories
+point to the repository. The simplest way to deal with
+a moved repository is to just get a fresh working
+directory after the move. Of course, you'll want to
+make sure that the old working directory had been
+checked in before the move, or you figured out some
+other way to make sure that you don't lose any
+changes. If you really do want to reuse the existing
+working directory, it should be possible with manual
+surgery on the @file{CVS/Repository} files. You can
+see @ref{Working directory storage}, for information on
+the @file{CVS/Repository} and @file{CVS/Root} files, but
+unless you are sure you want to bother, it probably
+isn't worth it.
address@hidden FIXME: Surgery on CVS/Repository should be avoided
address@hidden by making RELATIVE_REPOS the default.
address@hidden FIXME-maybe: might want some documented way to
address@hidden change the CVS/Root files in some particular tree.
address@hidden But then again, I don't know, maybe just having
address@hidden people do this in perl/shell/&c isn't so bad...
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Remote repositories
address@hidden Remote repositories
address@hidden Repositories, remote
address@hidden Remote repositories
address@hidden Client/Server Operation
address@hidden Server, CVS
address@hidden Remote repositories, port specification
address@hidden Repositories, remote, port specification
address@hidden Client/Server Operation, port specification
address@hidden pserver (client/server connection method), port specification
address@hidden kserver (client/server connection method), port specification
address@hidden gserver (client/server connection method), port specification
address@hidden port, specifying for remote repositories
+
+ Your working copy of the sources can be on a
+different machine than the repository. Using @sc{cvs}
+in this manner is known as @dfn{client/server}
+operation. You run @sc{cvs} on a machine which can
+mount your working directory, known as the
address@hidden, and tell it to communicate to a machine
+which can mount the repository, known as the
address@hidden Generally, using a remote
+repository is just like using a local one, except that
+the format of the repository name is:
+
address@hidden
+[:@var{method}:address@hidden:@var{password}]@@address@hidden:address@hidden/path/to/repository
address@hidden example
+
+Specifying a password in the repository name is not recommended during
+checkout, since this will cause @sc{cvs} to store a cleartext copy of the
+password in each created directory. @code{cvs login} first instead
+(@pxref{Password authentication client}).
+
+The details of exactly what needs to be set up depend
+on how you are connecting to the server.
+
+If @var{method} is not specified, and the repository
+name contains @samp{:}, then the default is @code{ext}
+or @code{server}, depending on your platform; both are
+described in @ref{Connecting via rsh}.
address@hidden Should we try to explain which platforms are which?
address@hidden Platforms like unix and VMS, which only allow
address@hidden privileged programs to bind to sockets <1024 lose on
address@hidden :server:
address@hidden Platforms like Mac and VMS, whose rsh program is
address@hidden unusable or nonexistent, lose on :ext:
address@hidden Platforms like OS/2 and NT probably could plausibly
address@hidden default either way (modulo -b troubles).
+
address@hidden FIXME: We need to have a better way of explaining
address@hidden what method to use. This presentation totally
address@hidden obscures the fact that :ext: and CVS_RSH is the way to
address@hidden use SSH, for example. Plus it incorrectly implies
address@hidden that you need an @code{rsh} binary on the client to use
address@hidden :server:.
address@hidden Also note that rsh not pserver is the right choice if you want
address@hidden users to be able to create their own repositories
address@hidden (because of the --allow-root related issues).
address@hidden
+* Server requirements:: Memory and other resources for servers
+* Connecting via rsh:: Using the @code{rsh} program to connect
+* Password authenticated:: Direct connections using passwords
+* GSSAPI authenticated:: Direct connections using GSSAPI
+* Kerberos authenticated:: Direct connections with kerberos
+* Connecting via fork:: Using a forked @code{cvs server} to connect
address@hidden menu
+
address@hidden Server requirements
address@hidden Server requirements
+
+The quick answer to what sort of machine is suitable as
+a server is that requirements are modest---a server
+with 32M of memory or even less can handle a fairly
+large source tree with a fair amount of activity.
address@hidden Say something about CPU speed too? I'm even less sure
address@hidden what to say on that subject...
+
+The real answer, of course, is more complicated.
+Estimating the known areas of large memory consumption
+should be sufficient to estimate memory requirements.
+There are two such areas documented here; other memory
+consumption should be small by comparison (if you find
+that is not the case, let us know, as described in
address@hidden, so we can update this documentation).
+
+The first area of big memory consumption is large
+checkouts, when using the @sc{cvs} server. The server
+consists of two processes for each client that it is
+serving. Memory consumption on the child process
+should remain fairly small. Memory consumption on the
+parent process, particularly if the network connection
+to the client is slow, can be expected to grow to
+slightly more than the size of the sources in a single
+directory, or two megabytes, whichever is larger.
address@hidden "two megabytes" of course is SERVER_HI_WATER. But
address@hidden we don't mention that here because we are
address@hidden documenting the default configuration of CVS. If it
address@hidden is a "standard" thing to change that value, it
address@hidden should be some kind of run-time configuration.
address@hidden
address@hidden See cvsclient.texi for more on the design decision
address@hidden to not have locks in place while waiting for the
address@hidden client, which is what results in memory consumption
address@hidden as high as this.
+
+Multiplying the size of each @sc{cvs} server by the
+number of servers which you expect to have active at
+one time should give an idea of memory requirements for
+the server. For the most part, the memory consumed by
+the parent process probably can be swap space rather
+than physical memory.
address@hidden Has anyone verified that notion about swap space?
address@hidden I say it based pretty much on guessing that the
address@hidden ->text of the struct buffer_data only gets accessed
address@hidden in a first in, first out fashion, but I haven't
address@hidden looked very closely.
+
address@hidden What about disk usage in /tmp on the server? I think that
address@hidden it can be substantial, but I haven't looked at this
address@hidden again and tried to figure it out ("cvs import" is
address@hidden probably the worst case...).
+
+The second area of large memory consumption is
address@hidden, when checking in large files. This is
+required even for binary files. The rule of thumb is
+to allow about ten times the size of the largest file
+you will want to check in, although five times may be
+adequate. For example, if you want to check in a file
+which is 10 megabytes, you should have 100 megabytes of
+memory on the machine doing the checkin (the server
+machine for client/server, or the machine running
address@hidden for non-client/server). This can be swap
+space rather than physical memory. Because the memory
+is only required briefly, there is no particular need
+to allow memory for more than one such checkin at a
+time.
address@hidden The 5-10 times rule of thumb is from Paul Eggert for
address@hidden GNU diff. I don't think it is in the GNU diff
address@hidden manual or anyplace like that.
address@hidden
address@hidden Probably we could be saying more about
address@hidden non-client/server CVS.
address@hidden I would guess for non-client/server CVS in an NFS
address@hidden environment the biggest issues are the network and
address@hidden the NFS server.
+
+Resource consumption for the client is even more
+modest---any machine with enough capacity to run the
+operating system in question should have little
+trouble.
address@hidden Is that true? I think the client still wants to
address@hidden (bogusly) store entire files in memory at times.
+
+For information on disk space requirements, see
address@hidden a repository}.
+
address@hidden Connecting via rsh
address@hidden Connecting with rsh
+
address@hidden rsh
address@hidden uses the @samp{rsh} protocol to perform these
+operations, so the remote user host needs to have a
address@hidden file which grants access to the local
+user. Note that the program that @sc{cvs} uses for this
+purpose may be specified using the @file{--with-rsh}
+flag to configure.
+
+For example, suppose you are the user @samp{mozart} on
+the local machine @samp{toe.example.com}, and the
+server machine is @samp{faun.example.org}. On
+faun, put the following line into the file
address@hidden in @samp{bach}'s home directory:
+
address@hidden
+toe.example.com mozart
address@hidden example
+
address@hidden
+Then test that @samp{rsh} is working with
+
address@hidden
+rsh -l bach faun.example.org 'echo $PATH'
address@hidden example
+
address@hidden CVS_SERVER, environment variable
+Next you have to make sure that @code{rsh} will be able
+to find the server. Make sure that the path which
address@hidden printed in the above example includes the
+directory containing a program named @code{cvs} which
+is the server. You need to set the path in
address@hidden, @file{.cshrc}, etc., not @file{.login}
+or @file{.profile}. Alternately, you can set the
+environment variable @code{CVS_SERVER} on the client
+machine to the filename of the server you want to use,
+for example @file{/usr/local/bin/cvs-1.6}.
address@hidden FIXME: there should be a way to specify the
address@hidden program in CVSROOT, not CVS_SERVER, so that one can use
address@hidden different ones for different roots. e.g. ":server;cvs=cvs-1.6:"
address@hidden instead of ":server:".
+
+There is no need to edit @file{inetd.conf} or start a
address@hidden server daemon.
+
address@hidden :server:, setting up
address@hidden :ext:, setting up
address@hidden Kerberos, using kerberized rsh
address@hidden SSH (rsh replacement)
address@hidden rsh replacements (Kerberized, SSH, &c)
+There are two access methods that you use in @code{CVSROOT}
+for rsh. @code{:server:} specifies an internal rsh
+client, which is supported only by some @sc{cvs} ports.
address@hidden:ext:} specifies an external rsh program. By
+default this is @code{rsh} (unless otherwise specified
+by the @file{--with-rsh} flag to configure) but you may set the
address@hidden environment variable to invoke another
+program which can access the remote server (for
+example, @code{remsh} on HP-UX 9 because @code{rsh} is
+something different). It must be a program which can
+transmit data to and from the server without modifying
+it; for example the Windows NT @code{rsh} is not
+suitable since it by default translates between CRLF
+and LF. The OS/2 @sc{cvs} port has a hack to pass @samp{-b}
+to @code{rsh} to get around this, but since this could
+potentially cause problems for programs other than the
+standard @code{rsh}, it may change in the future. If
+you set @code{CVS_RSH} to @code{SSH} or some other rsh
+replacement, the instructions in the rest of this
+section concerning @file{.rhosts} and so on are likely
+to be inapplicable; consult the documentation for your rsh
+replacement.
address@hidden FIXME: there should be a way to specify the
address@hidden program in CVSROOT, not CVS_RSH, so that one can use
address@hidden different ones for different roots. e.g. ":ext;rsh=remsh:"
address@hidden instead of ":ext:".
address@hidden See also the comment in src/client.c for rationale
address@hidden concerning "rsh" being the default and never
address@hidden "remsh".
+
+Continuing our example, supposing you want to access
+the module @file{foo} in the repository
address@hidden/usr/local/cvsroot/}, on machine
address@hidden, you are ready to go:
+
address@hidden
+cvs -d :ext:bach@@faun.example.org:/usr/local/cvsroot checkout foo
address@hidden example
+
address@hidden
+(The @file{bach@@} can be omitted if the username is
+the same on both the local and remote hosts.)
+
address@hidden Should we mention "rsh host echo hi" and "rsh host
address@hidden cat" (the latter followed by typing text and ^D)
address@hidden as troubleshooting techniques? Probably yes
address@hidden (people tend to have trouble setting this up),
address@hidden but this kind of thing can be hard to spell out.
+
address@hidden Password authenticated
address@hidden Direct connection with password authentication
+
+The @sc{cvs} client can also connect to the server
+using a password protocol. This is particularly useful
+if using @code{rsh} is not feasible (for example,
+the server is behind a firewall), and Kerberos also is
+not available.
+
+ To use this method, it is necessary to make
+some adjustments on both the server and client sides.
+
address@hidden
+* Password authentication server:: Setting up the server
+* Password authentication client:: Using the client
+* Password authentication security:: What this method does and does not do
address@hidden menu
+
address@hidden Password authentication server
address@hidden Setting up the server for password authentication
+
+First of all, you probably want to tighten the
+permissions on the @file{$CVSROOT} and
address@hidden/CVSROOT} directories. See @ref{Password
+authentication security}, for more details.
+
address@hidden pserver (subcommand)
address@hidden Remote repositories, port specification
address@hidden Repositories, remote, port specification
address@hidden Client/Server Operation, port specification
address@hidden pserver (client/server connection method), port specification
address@hidden kserver (client/server connection method), port specification
address@hidden gserver (client/server connection method), port specification
address@hidden port, specifying for remote repositories
address@hidden Password server, setting up
address@hidden Authenticating server, setting up
address@hidden inetd, configuring for pserver
address@hidden xinetd, configuring for pserver
address@hidden FIXME: this isn't quite right regarding port
address@hidden numbers; CVS looks up "cvspserver" in
address@hidden /etc/services (on unix, but what about non-unix?).
+On the server side, the file @file{/etc/inetd.conf}
+needs to be edited so @code{inetd} knows to run the
+command @code{cvs pserver} when it receives a
+connection on the right port. By default, the port
+number is 2401; it would be different if your client
+were compiled with @code{CVS_AUTH_PORT} defined to
+something else, though. This can also be specified in the CVSROOT variable
+(@pxref{Remote repositories}) or overridden with the CVS_CLIENT_PORT
+environment variable (@pxref{Environment variables}).
+
+ If your @code{inetd} allows raw port numbers in
address@hidden/etc/inetd.conf}, then the following (all on a
+single line in @file{inetd.conf}) should be sufficient:
+
address@hidden
+2401 stream tcp nowait root /usr/local/bin/cvs
+cvs -f --allow-root=/usr/cvsroot pserver
address@hidden example
+
address@hidden
+(You could also use the
address@hidden option to specify a temporary directory.)
+
+The @samp{--allow-root} option specifies the allowable
address@hidden directory. Clients which attempt to use a
+different @sc{cvsroot} directory will not be allowed to
+connect. If there is more than one @sc{cvsroot}
+directory which you want to allow, repeat the option.
+(Unfortunately, many versions of @code{inetd} have very small
+limits on the number of arguments and/or the total length
+of the command. The usual solution to this problem is
+to have @code{inetd} run a shell script which then invokes
address@hidden with the necessary arguments.)
+
+ If your @code{inetd} wants a symbolic service
+name instead of a raw port number, then put this in
address@hidden/etc/services}:
+
address@hidden
+cvspserver 2401/tcp
address@hidden example
+
address@hidden
+and put @code{cvspserver} instead of @code{2401} in @file{inetd.conf}.
+
+If your system uses @code{xinetd} instead of @code{inetd},
+the procedure is slightly different.
+Create a file called @file{/etc/xinetd.d/cvspserver} containing the following:
+
address@hidden
+service cvspserver
address@hidden
+ port = 2401
+ socket_type = stream
+ protocol = tcp
+ wait = no
+ user = root
+ passenv = PATH
+ server = /usr/local/bin/cvs
+ server_args = -f --allow-root=/usr/cvsroot pserver
address@hidden
address@hidden example
+
address@hidden
+(If @code{cvspserver} is defined in @file{/etc/services}, you can omit
+the @code{port} line.)
+
+ Once the above is taken care of, restart your
address@hidden, or do whatever is necessary to force it
+to reread its initialization files.
+
+If you are having trouble setting this up, see
address@hidden
+
address@hidden CVS passwd file
address@hidden passwd (admin file)
+Because the client stores and transmits passwords in
+cleartext (almost---see @ref{Password authentication
+security}, for details), a separate @sc{cvs} password
+file is generally used, so people don't compromise
+their regular passwords when they access the
+repository. This file is
address@hidden/CVSROOT/passwd} (@pxref{Intro
+administrative files}). It uses a colon-separated
+format, similar to @file{/etc/passwd} on Unix systems,
+except that it has fewer fields: @sc{cvs} username,
+optional password, and an optional system username for
address@hidden to run as if authentication succeeds. Here is
+an example @file{passwd} file with five entries:
+
address@hidden
+anonymous:
+bach:ULtgRLXo7NRxs
+spwang:1sOp854gDF3DY
+melissa:tGX1fS8sun6rY:pubcvs
+qproj:XR4EZcEs0szik:pubcvs
address@hidden example
+
address@hidden
+(The passwords are encrypted according to the standard
+Unix @code{crypt()} function, so it is possible to
+paste in passwords directly from regular Unix
address@hidden/etc/passwd} files.)
+
+The first line in the example will grant access to any
address@hidden client attempting to authenticate as user
address@hidden, no matter what password they use,
+including an empty password. (This is typical for
+sites granting anonymous read-only access; for
+information on how to do the "read-only" part, see
address@hidden access}.)
+
+The second and third lines will grant access to
address@hidden and @code{spwang} if they supply their
+respective plaintext passwords.
+
address@hidden User aliases
+The fourth line will grant access to @code{melissa}, if
+she supplies the correct password, but her @sc{cvs}
+operations will actually run on the server side under
+the system user @code{pubcvs}. Thus, there need not be
+any system user named @code{melissa}, but there
address@hidden be one named @code{pubcvs}.
+
+The fifth line shows that system user identities can be
+shared: any client who successfully authenticates as
address@hidden will actually run as @code{pubcvs}, just
+as @code{melissa} does. That way you could create a
+single, shared system user for each project in your
+repository, and give each developer their own line in
+the @file{$CVSROOT/CVSROOT/passwd} file. The @sc{cvs}
+username on each line would be different, but the
+system username would be the same. The reason to have
+different @sc{cvs} usernames is that @sc{cvs} will log their
+actions under those names: when @code{melissa} commits
+a change to a project, the checkin is recorded in the
+project's history under the name @code{melissa}, not
address@hidden And the reason to have them share a
+system username is so that you can arrange permissions
+in the relevant area of the repository such that only
+that account has write-permission there.
+
+If the system-user field is present, all
+password-authenticated @sc{cvs} commands run as that
+user; if no system user is specified, @sc{cvs} simply
+takes the @sc{cvs} username as the system username and
+runs commands as that user. In either case, if there
+is no such user on the system, then the @sc{cvs}
+operation will fail (regardless of whether the client
+supplied a valid password).
+
+The password and system-user fields can both be omitted
+(and if the system-user field is omitted, then also
+omit the colon that would have separated it from the
+encrypted password). For example, this would be a
+valid @file{$CVSROOT/CVSROOT/passwd} file:
+
address@hidden
+anonymous::pubcvs
+fish:rKa5jzULzmhOo:kfogel
+sussman:1sOp854gDF3DY
address@hidden example
+
address@hidden
+When the password field is omitted or empty, then the
+client's authentication attempt will succeed with any
+password, including the empty string. However, the
+colon after the @sc{cvs} username is always necessary,
+even if the password is empty.
+
address@hidden can also fall back to use system authentication.
+When authenticating a password, the server first checks
+for the user in the @file{$CVSROOT/CVSROOT/passwd}
+file. If it finds the user, it will use that entry for
+authentication as described above. But if it does not
+find the user, or if the @sc{cvs} @file{passwd} file
+does not exist, then the server can try to authenticate
+the username and password using the operating system's
+user-lookup routines (this "fallback" behavior can be
+disabled by setting @code{SystemAuth=no} in the
address@hidden @file{config} file, @pxref{config}).
+
+The default fallback behaviour is to look in
address@hidden/etc/passwd} for this system password unless your
+system has PAM (Pluggable Authentication Modules)
+and your @sc{cvs} server executable was configured to
+use it at compile time (using @code{./configure --enable-pam} - see the
+INSTALL file for more). In this case, PAM will be consulted instead.
+This means that @sc{cvs} can be configured to use any password
+authentication source PAM can be configured to use (possibilities
+include a simple UNIX password, NIS, LDAP, and others) in its
+global configuration file (usually @file{/etc/pam.conf}
+or possibly @file{/etc/pam.d/cvs}). See your PAM documentation
+for more details on PAM configuration.
+
+Note that PAM is an experimental feature in @sc{cvs} and feedback is
+encouraged. Please send a mail to one of the @sc{cvs} mailing lists
+(@code{info-cvs@@gnu.org} or @code{bug-cvs@@gnu.org}) if you use the
address@hidden PAM support.
+
address@hidden: Using PAM gives the system administrator much more
+flexibility about how @sc{cvs} users are authenticated but
+no more security than other methods. See below for more.}
+
+CVS needs an "auth" and "account" module in the
+PAM configuration file. A typical PAM configuration
+would therefore have the following lines
+in @file{/etc/pam.conf} to emulate the standard @sc{cvs}
+system @file{/etc/passwd} authentication:
+
address@hidden
+cvs auth required pam_unix.so
+cvs account required pam_unix.so
address@hidden example
+
+The the equivalent @file{/etc/pam.d/cvs} would contain
+
address@hidden
+auth required pam_unix.so
+account required pam_unix.so
address@hidden example
+
+Some systems require a full path to the module so that
address@hidden (Linux) would become something like
address@hidden/usr/lib/security/$ISA/pam_unix.so.1} (Sun Solaris).
+See the @file{contrib/pam} subdirectory of the @sc{cvs}
+source distribution for further example configurations.
+
+The PAM service name given above as "cvs" is just
+the service name in the default configuration amd can be
+set using
address@hidden/configure --with-hardcoded-pam-service-name=<pam-service-name>}
+before compiling. @sc{cvs} can also be configured to use whatever
+name it is invoked as as its PAM service name using
address@hidden/configure --without-hardcoded-pam-service-name}, but this
+feature should not be used if you may not have control of the name
address@hidden will be invoked as.
+
+Be aware, also, that falling back to system
+authentication might be a security risk: @sc{cvs}
+operations would then be authenticated with that user's
+regular login password, and the password flies across
+the network in plaintext. See @ref{Password
+authentication security} for more on this.
+This may be more of a problem with PAM authentication
+because it is likely that the source of the system
+password is some central authentication service like
+LDAP which is also used to authenticate other services.
+
+On the other hand, PAM makes it very easy to change your password
+regularly. If they are given the option of a one-password system for
+all of their activities, users are often more willing to change their
+password on a regular basis.
+
+In the non-PAM configuration where the password is stored in the
address@hidden/passwd} file, it is difficult to change passwords on a
+regular basis since only administrative users (or in some cases
+processes that act as an administrative user) are typicaly given
+access to modify this file. Either there needs to be some
+hand-crafted web page or set-uid program to update the file, or the
+update needs to be done by submitting a request to an administrator to
+perform the duty by hand. In the first case, having to remember to
+update a separate password on a periodic basis can be difficult. In
+the second case, the manual nature of the change will typically mean
+that the password will not be changed unless it is absolutely
+necessary.
+
+Note that PAM administrators should probably avoid configuring
+one-time-passwords (OTP) for @sc{cvs} authentication/authorization. If
+OTPs are desired, the administrator may wish to encourage the use of
+one of the other Client/Server access methods. See the section on
address@hidden repositories} for a list of other methods.
+
+Right now, the only way to put a password in the
address@hidden @file{passwd} file is to paste it there from
+somewhere else. Someday, there may be a @code{cvs
+passwd} command.
+
+Unlike many of the files in @file{$CVSROOT/CVSROOT}, it
+is normal to edit the @file{passwd} file in-place,
+rather than via @sc{cvs}. This is because of the
+possible security risks of having the @file{passwd}
+file checked out to people's working copies. If you do
+want to include the @file{passwd} file in checkouts of
address@hidden/CVSROOT}, see @ref{checkoutlist}.
+
address@hidden We might also suggest using the @code{htpasswd} command
address@hidden from freely available web servers as well, but that
address@hidden would open up a can of worms in that the users next
address@hidden questions are likely to be "where do I get it?" and
address@hidden "how do I use it?"
address@hidden Also note that htpasswd, at least the version I had,
address@hidden likes to clobber the third field.
+
address@hidden Password authentication client
address@hidden Using the client with password authentication
address@hidden Login (subcommand)
address@hidden Password client, using
address@hidden Authenticated client, using
address@hidden :pserver:, setting up
+To run a @sc{cvs} command on a remote repository via
+the password-authenticating server, one specifies the
address@hidden protocol, optional username, repository host, an
+optional port number, and path to the repository. For example:
+
address@hidden
+cvs -d :pserver:faun.example.org:/usr/local/cvsroot checkout someproj
address@hidden example
+
address@hidden
+or
+
address@hidden
+CVSROOT=:pserver:bach@@faun.example.org:2401/usr/local/cvsroot
+cvs checkout someproj
address@hidden example
+
+However, unless you're connecting to a public-access
+repository (i.e., one where that username doesn't
+require a password), you'll need to supply a password or @dfn{log in} first.
+Logging in verifies your password with the repository and stores it in a file.
+It's done with the @code{login} command, which will
+prompt you interactively for the password if you didn't supply one as part of
address@hidden:
+
address@hidden
+cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot login
+CVS password:
address@hidden example
+
address@hidden
+or
+
address@hidden
+cvs -d :pserver:bach:p4ss30rd@@faun.example.org:/usr/local/cvsroot login
address@hidden example
+
+After you enter the password, @sc{cvs} verifies it with
+the server. If the verification succeeds, then that
+combination of username, host, repository, and password
+is permanently recorded, so future transactions with
+that repository won't require you to run @code{cvs
+login}. (If verification fails, @sc{cvs} will exit
+complaining that the password was incorrect, and
+nothing will be recorded.)
+
+The records are stored, by default, in the file
address@hidden/.cvspass}. That file's format is
+human-readable, and to a degree human-editable, but
+note that the passwords are not stored in
+cleartext---they are trivially encoded to protect them
+from "innocent" compromise (i.e., inadvertent viewing
+by a system administrator or other non-malicious
+person).
+
address@hidden CVS_PASSFILE, environment variable
+You can change the default location of this file by
+setting the @code{CVS_PASSFILE} environment variable.
+If you use this variable, make sure you set it
address@hidden @code{cvs login} is run. If you were to
+set it after running @code{cvs login}, then later
address@hidden commands would be unable to look up the
+password for transmission to the server.
+
+Once you have logged in, all @sc{cvs} commands using
+that remote repository and username will authenticate
+with the stored password. So, for example
+
address@hidden
+cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot checkout foo
address@hidden example
+
address@hidden
+should just work (unless the password changes on the
+server side, in which case you'll have to re-run
address@hidden login}).
+
+Note that if the @samp{:pserver:} were not present in
+the repository specification, @sc{cvs} would assume it
+should use @code{rsh} to connect with the server
+instead (@pxref{Connecting via rsh}).
+
+Of course, once you have a working copy checked out and
+are running @sc{cvs} commands from within it, there is
+no longer any need to specify the repository
+explicitly, because @sc{cvs} can deduce the repository
+from the working copy's @file{CVS} subdirectory.
+
address@hidden FIXME: seems to me this needs somewhat more
address@hidden explanation.
address@hidden Logout (subcommand)
+The password for a given remote repository can be
+removed from the @code{CVS_PASSFILE} by using the
address@hidden logout} command.
+
address@hidden Password authentication security
address@hidden Security considerations with password authentication
+
address@hidden Security, of pserver
+The passwords are stored on the client side in a
+trivial encoding of the cleartext, and transmitted in
+the same encoding. The encoding is done only to
+prevent inadvertent password compromises (i.e., a
+system administrator accidentally looking at the file),
+and will not prevent even a naive attacker from gaining
+the password.
+
address@hidden FIXME: The bit about "access to the repository
address@hidden implies general access to the system is *not* specific
address@hidden to pserver; it applies to kerberos and SSH and
address@hidden everything else too. Should reorganize the
address@hidden documentation to make this clear.
+The separate @sc{cvs} password file (@pxref{Password
+authentication server}) allows people
+to use a different password for repository access than
+for login access. On the other hand, once a user has
+non-read-only
+access to the repository, she can execute programs on
+the server system through a variety of means. Thus, repository
+access implies fairly broad system access as well. It
+might be possible to modify @sc{cvs} to prevent that,
+but no one has done so as of this writing.
address@hidden OpenBSD uses chroot() and copies the repository to
address@hidden provide anonymous read-only access (for details see
address@hidden http://www.openbsd.org/anoncvs.shar). While this
address@hidden closes the most obvious holes, I'm not sure it
address@hidden closes enough holes to recommend it (plus it is
address@hidden *very* easy to accidentally screw up a setup of this
address@hidden type).
+
+Note that because the @file{$CVSROOT/CVSROOT} directory
+contains @file{passwd} and other files which are used
+to check security, you must control the permissions on
+this directory as tightly as the permissions on
address@hidden/etc}. The same applies to the @file{$CVSROOT}
+directory itself and any directory
+above it in the tree. Anyone who has write access to
+such a directory will have the ability to become any
+user on the system. Note that these permissions are
+typically tighter than you would use if you are not
+using pserver.
address@hidden TODO: Would be really nice to document/implement a
address@hidden scheme where the CVS server can run as some non-root
address@hidden user, e.g. "cvs". CVSROOT/passwd would contain a
address@hidden bunch of entries of the form foo:xxx:cvs (or the "cvs"
address@hidden would be implicit). This would greatly reduce
address@hidden security risks such as those hinted at in the
address@hidden previous paragraph. I think minor changes to CVS
address@hidden might be required but mostly this would just need
address@hidden someone who wants to play with it, document it, &c.
+
+In summary, anyone who gets the password gets
+repository access (which may imply some measure of general system
+access as well). The password is available to anyone
+who can sniff network packets or read a protected
+(i.e., user read-only) file. If you want real
+security, get Kerberos.
+
address@hidden GSSAPI authenticated
address@hidden Direct connection with GSSAPI
+
address@hidden GSSAPI
address@hidden Security, GSSAPI
address@hidden :gserver:, setting up
address@hidden Kerberos, using :gserver:
+GSSAPI is a generic interface to network security
+systems such as Kerberos 5.
+If you have a working GSSAPI library, you can have
address@hidden connect via a direct @sc{tcp} connection,
+authenticating with GSSAPI.
+
+To do this, @sc{cvs} needs to be compiled with GSSAPI
+support; when configuring @sc{cvs} it tries to detect
+whether GSSAPI libraries using kerberos version 5 are
+present. You can also use the @file{--with-gssapi}
+flag to configure.
+
+The connection is authenticated using GSSAPI, but the
+message stream is @emph{not} authenticated by default.
+You must use the @code{-a} global option to request
+stream authentication.
+
+The data transmitted is @emph{not} encrypted by
+default. Encryption support must be compiled into both
+the client and the server; use the
address@hidden configure option to turn it on.
+You must then use the @code{-x} global option to
+request encryption.
+
+GSSAPI connections are handled on the server side by
+the same server which handles the password
+authentication server; see @ref{Password authentication
+server}. If you are using a GSSAPI mechanism such as
+Kerberos which provides for strong authentication, you
+will probably want to disable the ability to
+authenticate via cleartext passwords. To do so, create
+an empty @file{CVSROOT/passwd} password file, and set
address@hidden in the config file
+(@pxref{config}).
+
+The GSSAPI server uses a principal name of
+cvs/@var{hostname}, where @var{hostname} is the
+canonical name of the server host. You will have to
+set this up as required by your GSSAPI mechanism.
+
+To connect using GSSAPI, use @samp{:gserver:}. For
+example,
+
address@hidden
+cvs -d :gserver:faun.example.org:/usr/local/cvsroot checkout foo
address@hidden example
+
address@hidden Kerberos authenticated
address@hidden Direct connection with kerberos
+
address@hidden Kerberos, using :kserver:
address@hidden Security, kerberos
address@hidden :kserver:, setting up
+The easiest way to use kerberos is to use the kerberos
address@hidden, as described in @ref{Connecting via rsh}.
+The main disadvantage of using rsh is that all the data
+needs to pass through additional programs, so it may be
+slower. So if you have kerberos installed you can
+connect via a direct @sc{tcp} connection,
+authenticating with kerberos.
+
+This section concerns the kerberos network security
+system, version 4. Kerberos version 5 is supported via
+the GSSAPI generic network security interface, as
+described in the previous section.
+
+To do this, @sc{cvs} needs to be compiled with kerberos
+support; when configuring @sc{cvs} it tries to detect
+whether kerberos is present or you can use the
address@hidden flag to configure.
+
+The data transmitted is @emph{not} encrypted by
+default. Encryption support must be compiled into both
+the client and server; use the
address@hidden configure option to turn it
+on. You must then use the @code{-x} global option to
+request encryption.
+
address@hidden CVS_CLIENT_PORT
+You need to edit @file{inetd.conf} on the server
+machine to run @code{cvs kserver}. The client uses
+port 1999 by default; if you want to use another port
+specify it in the @code{CVSROOT} (@pxref{Remote repositories})
+or the @code{CVS_CLIENT_PORT} environment variable
+(@pxref{Environment variables}) on the client.
+
address@hidden kinit
+When you want to use @sc{cvs}, get a ticket in the
+usual way (generally @code{kinit}); it must be a ticket
+which allows you to log into the server machine. Then
+you are ready to go:
+
address@hidden
+cvs -d :kserver:faun.example.org:/usr/local/cvsroot checkout foo
address@hidden example
+
+Previous versions of @sc{cvs} would fall back to a
+connection via rsh; this version will not do so.
+
address@hidden Connecting via fork
address@hidden Connecting with fork
+
address@hidden fork, access method
address@hidden :fork:, setting up
+This access method allows you to connect to a
+repository on your local disk via the remote protocol.
+In other words it does pretty much the same thing as
address@hidden:local:}, but various quirks, bugs and the like are
+those of the remote @sc{cvs} rather than the local
address@hidden
+
+For day-to-day operations you might prefer either
address@hidden:local:} or @code{:fork:}, depending on your
+preferences. Of course @code{:fork:} comes in
+particularly handy in testing or
+debugging @code{cvs} and the remote protocol.
+Specifically, we avoid all of the network-related
+setup/configuration, timeouts, and authentication
+inherent in the other remote access methods but still
+create a connection which uses the remote protocol.
+
+To connect using the @code{fork} method, use
address@hidden:fork:} and the pathname to your local
+repository. For example:
+
address@hidden
+cvs -d :fork:/usr/local/cvsroot checkout foo
address@hidden example
+
address@hidden CVS_SERVER, and :fork:
+As with @code{:ext:}, the server is called @samp{cvs}
+by default, or the value of the @code{CVS_SERVER}
+environment variable.
+
address@hidden
---------------------------------------------------------------------
address@hidden Read-only access
address@hidden Read-only repository access
address@hidden Read-only repository access
address@hidden readers (admin file)
address@hidden writers (admin file)
+
+ It is possible to grant read-only repository
+access to people using the password-authenticated
+server (@pxref{Password authenticated}). (The
+other access methods do not have explicit support for
+read-only users because those methods all assume login
+access to the repository machine anyway, and therefore
+the user can do whatever local file permissions allow
+her to do.)
+
+ A user who has read-only access can do only
+those @sc{cvs} operations which do not modify the
+repository, except for certain ``administrative'' files
+(such as lock files and the history file). It may be
+desirable to use this feature in conjunction with
+user-aliasing (@pxref{Password authentication server}).
+
+Unlike with previous versions of @sc{cvs}, read-only
+users should be able merely to read the repository, and
+not to execute programs on the server or otherwise gain
+unexpected levels of access. Or to be more accurate,
+the @emph{known} holes have been plugged. Because this
+feature is new and has not received a comprehensive
+security audit, you should use whatever level of
+caution seems warranted given your attitude concerning
+security.
+
+ There are two ways to specify read-only access
+for a user: by inclusion, and by exclusion.
+
+ "Inclusion" means listing that user
+specifically in the @file{$CVSROOT/CVSROOT/readers}
+file, which is simply a newline-separated list of
+users. Here is a sample @file{readers} file:
+
address@hidden
+melissa
+splotnik
+jrandom
address@hidden example
+
address@hidden
+ (Don't forget the newline after the last user.)
+
+ "Exclusion" means explicitly listing everyone
+who has @emph{write} access---if the file
+
address@hidden
+$CVSROOT/CVSROOT/writers
address@hidden example
+
address@hidden
+exists, then only
+those users listed in it have write access, and
+everyone else has read-only access (of course, even the
+read-only users still need to be listed in the
address@hidden @file{passwd} file). The
address@hidden file has the same format as the
address@hidden file.
+
+ Note: if your @sc{cvs} @file{passwd}
+file maps cvs users onto system users (@pxref{Password
+authentication server}), make sure you deny or grant
+read-only access using the @emph{cvs} usernames, not
+the system usernames. That is, the @file{readers} and
address@hidden files contain cvs usernames, which may
+or may not be the same as system usernames.
+
+ Here is a complete description of the server's
+behavior in deciding whether to grant read-only or
+read-write access:
+
+ If @file{readers} exists, and this user is
+listed in it, then she gets read-only access. Or if
address@hidden exists, and this user is NOT listed in
+it, then she also gets read-only access (this is true
+even if @file{readers} exists but she is not listed
+there). Otherwise, she gets full read-write access.
+
+ Of course there is a conflict if the user is
+listed in both files. This is resolved in the more
+conservative way, it being better to protect the
+repository too much than too little: such a user gets
+read-only access.
+
address@hidden Server temporary directory
address@hidden Temporary directories for the server
address@hidden Temporary directories, and server
address@hidden Server, temporary directories
+
+While running, the @sc{cvs} server creates temporary
+directories. They are named
+
address@hidden
address@hidden
address@hidden example
+
address@hidden
+where @var{pid} is the process identification number of
+the server.
+They are located in the directory specified by
+the @samp{-T} global option (@pxref{Global options}),
+the @code{TMPDIR} environment variable (@pxref{Environment variables}),
+or, failing that, @file{/tmp}.
+
+In most cases the server will remove the temporary
+directory when it is done, whether it finishes normally
+or abnormally. However, there are a few cases in which
+the server does not or cannot remove the temporary
+directory, for example:
+
address@hidden @bullet
address@hidden
+If the server aborts due to an internal server error,
+it may preserve the directory to aid in debugging
+
address@hidden
+If the server is killed in a way that it has no way of
+cleaning up (most notably, @samp{kill -KILL} on unix).
+
address@hidden
+If the system shuts down without an orderly shutdown,
+which tells the server to clean up.
address@hidden itemize
+
+In cases such as this, you will need to manually remove
+the @address@hidden directories. As long as
+there is no server running with process identification
+number @var{pid}, it is safe to do so.
+
address@hidden
---------------------------------------------------------------------
address@hidden Starting a new project
address@hidden Starting a project with CVS
address@hidden Starting a project with CVS
address@hidden Creating a project
+
address@hidden --moduledb--
+Because renaming files and moving them between
+directories is somewhat inconvenient, the first thing
+you do when you start a new project should be to think
+through your file organization. It is not impossible
+to rename or move files, but it does increase the
+potential for confusion and @sc{cvs} does have some
+quirks particularly in the area of renaming
+directories. @xref{Moving files}.
+
+What to do next depends on the situation at hand.
+
address@hidden
+* Setting up the files:: Getting the files into the repository
+* Defining the module:: How to make a module of the files
address@hidden menu
address@hidden -- File permissions!
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Setting up the files
address@hidden Setting up the files
+
+The first step is to create the files inside the repository. This can
+be done in a couple of different ways.
+
address@hidden -- The contributed scripts
address@hidden
+* From files:: This method is useful with old projects
+ where files already exists.
+* From other version control systems:: Old projects where you want to
+ preserve history from another system.
+* From scratch:: Creating a directory tree from scratch.
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden From files
address@hidden Creating a directory tree from a number of files
address@hidden Importing files
+
+When you begin using @sc{cvs}, you will probably already have several
+projects that can be
+put under @sc{cvs} control. In these cases the easiest way is to use the
address@hidden command. An example is probably the easiest way to
+explain how to use it. If the files you want to install in
address@hidden reside in @address@hidden, and you want them to appear in the
+repository as @file{$CVSROOT/yoyodyne/@var{rdir}}, you can do this:
+
address@hidden
+$ cd @var{wdir}
+$ cvs import -m "Imported sources" yoyodyne/@var{rdir} yoyo start
address@hidden example
+
+Unless you supply a log message with the @samp{-m}
+flag, @sc{cvs} starts an editor and prompts for a
+message. The string @samp{yoyo} is a @dfn{vendor tag},
+and @samp{start} is a @dfn{release tag}. They may fill
+no purpose in this context, but since @sc{cvs} requires
+them they must be present. @xref{Tracking sources}, for
+more information about them.
+
+You can now verify that it worked, and remove your
+original source directory.
address@hidden FIXME: Need to say more about "verify that it
address@hidden worked". What should the user look for in the output
address@hidden from "diff -r"?
+
address@hidden
+$ cd ..
+$ cvs checkout yoyodyne/@var{rdir} # @r{Explanation below}
+$ diff -r @var{wdir} yoyodyne/@var{rdir}
+$ rm -r @var{wdir}
address@hidden example
+
address@hidden
+Erasing the original sources is a good idea, to make sure that you do
+not accidentally edit them in @var{wdir}, bypassing @sc{cvs}.
+Of course, it would be wise to make sure that you have
+a backup of the sources before you remove them.
+
+The @code{checkout} command can either take a module
+name as argument (as it has done in all previous
+examples) or a path name relative to @code{$CVSROOT},
+as it did in the example above.
+
+It is a good idea to check that the permissions
address@hidden sets on the directories inside @code{$CVSROOT}
+are reasonable, and that they belong to the proper
+groups. @xref{File permissions}.
+
+If some of the files you want to import are binary, you
+may want to use the wrappers features to specify which
+files are binary and which are not. @xref{Wrappers}.
+
address@hidden The node name is too long, but I am having trouble
address@hidden thinking of something more concise.
address@hidden From other version control systems
address@hidden Creating Files From Other Version Control Systems
address@hidden Importing files, from other version control systems
+
+If you have a project which you are maintaining with
+another version control system, such as @sc{rcs}, you
+may wish to put the files from that project into
address@hidden, and preserve the revision history of the
+files.
+
address@hidden @asis
address@hidden RCS, importing files from
address@hidden From RCS
+If you have been using @sc{rcs}, find the @sc{rcs}
+files---usually a file named @file{foo.c} will have its
address@hidden file in @file{RCS/foo.c,v} (but it could be
+other places; consult the @sc{rcs} documentation for
+details). Then create the appropriate directories in
address@hidden if they do not already exist. Then copy the
+files into the appropriate directories in the @sc{cvs}
+repository (the name in the repository must be the name
+of the source file with @samp{,v} added; the files go
+directly in the appropriate directory of the repository,
+not in an @file{RCS} subdirectory). This is one of the
+few times when it is a good idea to access the @sc{cvs}
+repository directly, rather than using @sc{cvs}
+commands. Then you are ready to check out a new
+working directory.
address@hidden Someday there probably should be a "cvs import -t
address@hidden rcs" or some such. It could even create magic
address@hidden branches. It could also do something about the case
address@hidden where the RCS file had a (non-magic) "0" branch.
+
+The @sc{rcs} file should not be locked when you move it
+into @sc{cvs}; if it is, @sc{cvs} will have trouble
+letting you operate on it.
address@hidden What is the easiest way to unlock your files if you
address@hidden have them locked? Especially if you have a lot of them?
address@hidden This is a CVS bug/misfeature; importing RCS files
address@hidden should ignore whether they are locked and leave them in
address@hidden an unlocked state. Yet another reason for a separate
address@hidden "import RCS file" command.
+
address@hidden How many is "many"? Or do they just import RCS files?
address@hidden From another version control system
+Many version control systems have the ability to export
address@hidden files in the standard format. If yours does,
+export the @sc{rcs} files and then follow the above
+instructions.
+
+Failing that, probably your best bet is to write a
+script that will check out the files one revision at a
+time using the command line interface to the other
+system, and then check the revisions into @sc{cvs}.
+The @file{sccs2rcs} script mentioned below may be a
+useful example to follow.
+
address@hidden SCCS, importing files from
address@hidden From SCCS
+There is a script in the @file{contrib} directory of
+the @sc{cvs} source distribution called @file{sccs2rcs}
+which converts @sc{sccs} files to @sc{rcs} files.
+Note: you must run it on a machine which has both
address@hidden and @sc{rcs} installed, and like everything
+else in contrib it is unsupported (your mileage may
+vary).
+
address@hidden PVCS, importing files from
address@hidden From PVCS
+There is a script in the @file{contrib} directory of
+the @sc{cvs} source distribution called @file{pvcs_to_rcs}
+which converts @sc{pvcs} archives to @sc{rcs} files.
+You must run it on a machine which has both
address@hidden and @sc{rcs} installed, and like everything
+else in contrib it is unsupported (your mileage may
+vary). See the comments in the script for details.
address@hidden table
address@hidden CMZ and/or PATCHY were systems that were used in the
address@hidden high energy physics community (especially for
address@hidden CERNLIB). CERN has replaced them with CVS, but the
address@hidden CAR format seems to live on as a way to submit
address@hidden changes. There is a program car2cvs which converts
address@hidden but I'm not sure where one gets a copy.
address@hidden Not sure it is worth mentioning here, since it would
address@hidden appear to affect only one particular community.
address@hidden Best page for more information is:
address@hidden http://wwwcn1.cern.ch/asd/cvs/index.html
address@hidden See also:
address@hidden http://ecponion.cern.ch/ecpsa/cernlib.html
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden From scratch
address@hidden Creating a directory tree from scratch
+
address@hidden Also/instead should be documenting
address@hidden $ cvs co -l .
address@hidden $ mkdir tc
address@hidden $ cvs add tc
address@hidden $ cd tc
address@hidden $ mkdir man
address@hidden $ cvs add man
address@hidden etc.
address@hidden Using import to create the directories only is
address@hidden probably a somewhat confusing concept.
+For a new project, the easiest thing to do is probably
+to create an empty directory structure, like this:
+
address@hidden
+$ mkdir tc
+$ mkdir tc/man
+$ mkdir tc/testing
address@hidden example
+
+After that, you use the @code{import} command to create
+the corresponding (empty) directory structure inside
+the repository:
+
address@hidden
+$ cd tc
+$ cvs import -m "Created directory structure" yoyodyne/@var{dir} yoyo start
address@hidden example
+
+Then, use @code{add} to add files (and new directories)
+as they appear.
+
+Check that the permissions @sc{cvs} sets on the
+directories inside @code{$CVSROOT} are reasonable.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Defining the module
address@hidden Defining the module
address@hidden Defining a module
address@hidden Editing the modules file
address@hidden Module, defining
address@hidden Modules file, changing
+
+The next step is to define the module in the
address@hidden file. This is not strictly necessary,
+but modules can be convenient in grouping together
+related files and directories.
+
+In simple cases these steps are sufficient to define a module.
+
address@hidden
address@hidden
+Get a working copy of the modules file.
+
address@hidden
+$ cvs checkout CVSROOT/modules
+$ cd CVSROOT
address@hidden example
+
address@hidden
+Edit the file and insert a line that defines the module. @xref{Intro
+administrative files}, for an introduction. @xref{modules}, for a full
+description of the modules file. You can use the
+following line to define the module @samp{tc}:
+
address@hidden
+tc yoyodyne/tc
address@hidden example
+
address@hidden
+Commit your changes to the modules file.
+
address@hidden
+$ cvs commit -m "Added the tc module." modules
address@hidden example
+
address@hidden
+Release the modules module.
+
address@hidden
+$ cd ..
+$ cvs release -d CVSROOT
address@hidden example
address@hidden enumerate
+
address@hidden
---------------------------------------------------------------------
address@hidden Revisions
address@hidden Revisions
+
+For many uses of @sc{cvs}, one doesn't need to worry
+too much about revision numbers; @sc{cvs} assigns
+numbers such as @code{1.1}, @code{1.2}, and so on, and
+that is all one needs to know. However, some people
+prefer to have more knowledge and control concerning
+how @sc{cvs} assigns revision numbers.
+
+If one wants to keep track of a set of revisions
+involving more than one file, such as which revisions
+went into a particular release, one uses a @dfn{tag},
+which is a symbolic revision which can be assigned to a
+numeric revision in each file.
+
address@hidden
+* Revision numbers:: The meaning of a revision number
+* Versions revisions releases:: Terminology used in this manual
+* Assigning revisions:: Assigning revisions
+* Tags:: Tags--Symbolic revisions
+* Tagging the working directory:: The cvs tag command
+* Tagging by date/tag:: The cvs rtag command
+* Modifying tags:: Adding, renaming, and deleting tags
+* Tagging add/remove:: Tags with adding and removing files
+* Sticky tags:: Certain tags are persistent
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Revision numbers
address@hidden Revision numbers
address@hidden Revision numbers
address@hidden Revision tree
address@hidden Linear development
address@hidden Number, revision-
address@hidden Decimal revision number
address@hidden Branch number
address@hidden Number, branch
+
+Each version of a file has a unique @dfn{revision
+number}. Revision numbers look like @samp{1.1},
address@hidden, @samp{1.3.2.2} or even @samp{1.3.2.2.4.5}.
+A revision number always has an even number of
+period-separated decimal integers. By default revision
+1.1 is the first revision of a file. Each successive
+revision is given a new number by increasing the
+rightmost number by one. The following figure displays
+a few revisions, with newer revisions to the right.
+
address@hidden
+ +-----+ +-----+ +-----+ +-----+ +-----+
+ ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
+ +-----+ +-----+ +-----+ +-----+ +-----+
address@hidden example
+
+It is also possible to end up with numbers containing
+more than one period, for example @samp{1.3.2.2}. Such
+revisions represent revisions on branches
+(@pxref{Branching and merging}); such revision numbers
+are explained in detail in @ref{Branches and
+revisions}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Versions revisions releases
address@hidden Versions, revisions and releases
address@hidden Revisions, versions and releases
address@hidden Versions, revisions and releases
address@hidden Releases, revisions and versions
+
+A file can have several versions, as described above.
+Likewise, a software product can have several versions.
+A software product is often given a version number such
+as @samp{4.1.1}.
+
+Versions in the first sense are called @dfn{revisions}
+in this document, and versions in the second sense are
+called @dfn{releases}. To avoid confusion, the word
address@hidden is almost never used in this document.
+
address@hidden Assigning revisions
address@hidden Assigning revisions
+
address@hidden We avoid the "major revision" terminology. It seems
address@hidden like jargon. Hopefully "first number" is clear enough.
address@hidden
address@hidden Well, in the context of software release numbers,
address@hidden "major" and "minor" release or version numbers are
address@hidden documented in at least the GNU Coding Standards, but I'm
address@hidden still not sure I find that a valid reason to apply the
address@hidden terminology to RCS revision numbers. "First", "Second",
address@hidden "subsequent", and so on is almost surely clearer,
address@hidden especially to a novice reader. -DRP
+By default, @sc{cvs} will assign numeric revisions by
+leaving the first number the same and incrementing the
+second number. For example, @code{1.1}, @code{1.2},
address@hidden, etc.
+
+When adding a new file, the second number will always
+be one and the first number will equal the highest
+first number of any file in that directory. For
+example, the current directory contains files whose
+highest numbered revisions are @code{1.7}, @code{3.1},
+and @code{4.12}, then an added file will be given the
+numeric revision @code{4.1}.
+
address@hidden This is sort of redundant with something we said a
address@hidden while ago. Somewhere we need a better way of
address@hidden introducing how the first number can be anything
address@hidden except "1", perhaps. Also I don't think this
address@hidden presentation is clear on why we are discussing releases
address@hidden and first numbers of numeric revisions in the same
address@hidden breath.
+Normally there is no reason to care
+about the revision numbers---it is easier to treat them
+as internal numbers that @sc{cvs} maintains, and tags
+provide a better way to distinguish between things like
+release 1 versus release 2 of your product
+(@pxref{Tags}). However, if you want to set the
+numeric revisions, the @samp{-r} option to @code{cvs
+commit} can do that. The @samp{-r} option implies the
address@hidden option, in the sense that it causes the
+files to be committed even if they are not modified.
+
+For example, to bring all your files up to
+revision 3.0 (including those that haven't changed),
+you might invoke:
+
address@hidden
+$ cvs commit -r 3.0
address@hidden example
+
+Note that the number you specify with @samp{-r} must be
+larger than any existing revision number. That is, if
+revision 3.0 exists, you cannot @samp{cvs commit
+-r 1.3}. If you want to maintain several releases in
+parallel, you need to use a branch (@pxref{Branching and merging}).
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Tags
address@hidden Tags--Symbolic revisions
address@hidden Tags
+
+The revision numbers live a life of their own. They
+need not have anything at all to do with the release
+numbers of your software product. Depending
+on how you use @sc{cvs} the revision numbers might change several times
+between two releases. As an example, some of the
+source files that make up @sc{rcs} 5.6 have the following
+revision numbers:
address@hidden RCS revision numbers
+
address@hidden
+ci.c 5.21
+co.c 5.9
+ident.c 5.3
+rcs.c 5.12
+rcsbase.h 5.11
+rcsdiff.c 5.10
+rcsedit.c 5.11
+rcsfcmp.c 5.9
+rcsgen.c 5.10
+rcslex.c 5.11
+rcsmap.c 5.2
+rcsutil.c 5.10
address@hidden example
+
address@hidden tag (subcommand), introduction
address@hidden Tags, symbolic name
address@hidden Symbolic name (tag)
address@hidden Name, symbolic (tag)
address@hidden HEAD, as reserved tag name
address@hidden BASE, as reserved tag name
+You can use the @code{tag} command to give a symbolic name to a
+certain revision of a file. You can use the @samp{-v} flag to the
address@hidden command to see all tags that a file has, and
+which revision numbers they represent. Tag names must
+start with an uppercase or lowercase letter and can
+contain uppercase and lowercase letters, digits,
address@hidden, and @samp{_}. The two tag names @code{BASE}
+and @code{HEAD} are reserved for use by @sc{cvs}. It
+is expected that future names which are special to
address@hidden will be specially named, for example by
+starting with @samp{.}, rather than being named analogously to
address@hidden and @code{HEAD}, to avoid conflicts with
+actual tag names.
address@hidden Including a character such as % or = has also been
address@hidden suggested as the naming convention for future
address@hidden special tag names. Starting with . is nice because
address@hidden that is not a legal tag name as far as RCS is concerned.
address@hidden FIXME: CVS actually accepts quite a few characters
address@hidden in tag names, not just the ones documented above
address@hidden (see RCS_check_tag). RCS
address@hidden defines legitimate tag names by listing illegal
address@hidden characters rather than legal ones. CVS is said to lose its
address@hidden mind if you try to use "/" (try making such a tag sticky
address@hidden and using "cvs status" client/server--see remote
address@hidden protocol format for entries line for probable cause).
address@hidden TODO: The testsuite
address@hidden should test for whatever are documented above as
address@hidden officially-OK tag names, and CVS should at least reject
address@hidden characters that won't work, like "/".
+
+You'll want to choose some convention for naming tags,
+based on information such as the name of the program
+and the version number of the release. For example,
+one might take the name of the program, immediately
+followed by the version number with @samp{.} changed to
address@hidden, so that @sc{cvs} 1.9 would be tagged with the name
address@hidden If you choose a consistent convention,
+then you won't constantly be guessing whether a tag is
address@hidden or @code{cvs1_9} or what. You might
+even want to consider enforcing your convention in the
+taginfo file (@pxref{user-defined logging}).
address@hidden Might be nice to say more about using taginfo this
address@hidden way, like giving an example, or pointing out any particular
address@hidden issues which arise.
+
address@hidden Adding a tag
address@hidden Tags, example
+The following example shows how you can add a tag to a
+file. The commands must be issued inside your working
+directory. That is, you should issue the
+command in the directory where @file{backend.c}
+resides.
+
address@hidden
+$ cvs tag rel-0-4 backend.c
+T backend.c
+$ cvs status -v backend.c
+===================================================================
+File: backend.c Status: Up-to-date
+
+ Version: 1.4 Tue Dec 1 14:39:01 1992
+ RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v
+ Sticky Tag: (none)
+ Sticky Date: (none)
+ Sticky Options: (none)
+
+ Existing Tags:
+ rel-0-4 (revision: 1.4)
+
address@hidden example
+
+For a complete summary of the syntax of @code{cvs tag},
+including the various options, see @ref{Invoking CVS}.
+
+There is seldom reason to tag a file in isolation. A more common use is
+to tag all the files that constitute a module with the same tag at
+strategic points in the development life-cycle, such as when a release
+is made.
+
address@hidden
+$ cvs tag rel-1-0 .
+cvs tag: Tagging .
+T Makefile
+T backend.c
+T driver.c
+T frontend.c
+T parser.c
address@hidden example
+
address@hidden
+(When you give @sc{cvs} a directory as argument, it generally applies the
+operation to all the files in that directory, and (recursively), to any
+subdirectories that it may contain. @xref{Recursive behavior}.)
+
address@hidden Retrieving an old revision using tags
address@hidden Tags, retrieving old revisions
+The @code{checkout} command has a flag, @samp{-r}, that lets you check out
+a certain revision of a module. This flag makes it easy to
+retrieve the sources that make up release 1.0 of the module @samp{tc} at
+any time in the future:
+
address@hidden
+$ cvs checkout -r rel-1-0 tc
address@hidden example
+
address@hidden
+This is useful, for instance, if someone claims that there is a bug in
+that release, but you cannot find the bug in the current working copy.
+
+You can also check out a module as it was at any given date.
address@hidden options}. When specifying @samp{-r} to
+any of these commands, you will need beware of sticky
+tags; see @ref{Sticky tags}.
+
+When you tag more than one file with the same tag you
+can think about the tag as "a curve drawn through a
+matrix of filename vs. revision number." Say we have 5
+files with the following revisions:
+
address@hidden
address@hidden
+ file1 file2 file3 file4 file5
+
+ 1.1 1.1 1.1 1.1 /--1.1* <-*- TAG
+ 1.2*- 1.2 1.2 -1.2*-
+ 1.3 \- 1.3*- 1.3 / 1.3
+ 1.4 \ 1.4 / 1.4
+ \-1.5*- 1.5
+ 1.6
address@hidden group
address@hidden example
+
+At some time in the past, the @code{*} versions were tagged.
+You can think of the tag as a handle attached to the curve
+drawn through the tagged revisions. When you pull on
+the handle, you get all the tagged revisions. Another
+way to look at it is that you "sight" through a set of
+revisions that is "flat" along the tagged revisions,
+like this:
+
address@hidden
address@hidden
+ file1 file2 file3 file4 file5
+
+ 1.1
+ 1.2
+ 1.1 1.3 _
+ 1.1 1.2 1.4 1.1 /
+ 1.2*----1.3*----1.5*----1.2*----1.1 (--- <--- Look here
+ 1.3 1.6 1.3 \_
+ 1.4 1.4
+ 1.5
address@hidden group
address@hidden example
+
address@hidden Tagging the working directory
address@hidden Specifying what to tag from the working directory
+
address@hidden tag (subcommand)
+The example in the previous section demonstrates one of
+the most common ways to choose which revisions to tag.
+Namely, running the @code{cvs tag} command without
+arguments causes @sc{cvs} to select the revisions which
+are checked out in the current working directory. For
+example, if the copy of @file{backend.c} in working
+directory was checked out from revision 1.4, then
address@hidden will tag revision 1.4. Note that the tag is
+applied immediately to revision 1.4 in the repository;
+tagging is not like modifying a file, or other
+operations in which one first modifies the working
+directory and then runs @code{cvs commit} to transfer
+that modification to the repository.
+
+One potentially surprising aspect of the fact that
address@hidden tag} operates on the repository is that you
+are tagging the checked-in revisions, which may differ
+from locally modified files in your working directory.
+If you want to avoid doing this by mistake, specify the
address@hidden option to @code{cvs tag}. If there are any
+locally modified files, @sc{cvs} will abort with an
+error before it tags any files:
+
address@hidden
+$ cvs tag -c rel-0-4
+cvs tag: backend.c is locally modified
+cvs [tag aborted]: correct the above errors first!
address@hidden example
+
address@hidden Tagging by date/tag
address@hidden Specifying what to tag by date or revision
address@hidden rtag (subcommand)
+
+The @code{cvs rtag} command tags the repository as of a
+certain date or time (or can be used to tag the latest
+revision). @code{rtag} works directly on the
+repository contents (it requires no prior checkout and
+does not look for a working directory).
+
+The following options specify which date or revision to
+tag. See @ref{Common options}, for a complete
+description of them.
+
address@hidden @code
address@hidden -D @var{date}
+Tag the most recent revision no later than @var{date}.
+
address@hidden -f
+Only useful with the @samp{-D @var{date}} or @samp{-r @var{tag}}
+flags. If no matching revision is found, use the most
+recent revision (instead of ignoring the file).
+
address@hidden -r @var{tag}
+Only tag those files that contain existing tag @var{tag}.
address@hidden table
+
+The @code{cvs tag} command also allows one to specify
+files by revision or date, using the same @samp{-r},
address@hidden, and @samp{-f} options. However, this
+feature is probably not what you want. The reason is
+that @code{cvs tag} chooses which files to tag based on
+the files that exist in the working directory, rather
+than the files which existed as of the given tag/date.
+Therefore, you are generally better off using @code{cvs
+rtag}. The exceptions might be cases like:
+
address@hidden
+cvs tag -r 1.4 stable backend.c
address@hidden example
+
address@hidden Modifying tags
address@hidden Deleting, moving, and renaming tags
+
address@hidden Also see:
address@hidden "How do I move or rename a magic branch tag?"
address@hidden in the FAQ (I think the issues it talks about still
address@hidden apply, but this could use some sanity.sh work).
+
+Normally one does not modify tags. They exist in order
+to record the history of the repository and so deleting
+them or changing their meaning would, generally, not be
+what you want.
+
+However, there might be cases in which one uses a tag
+temporarily or accidentally puts one in the wrong
+place. Therefore, one might delete, move, or rename a
+tag.
+
address@hidden
address@hidden: the commands in this section are
+dangerous; they permanently discard historical
+information and it can be difficult or impossible to
+recover from errors. If you are a @sc{cvs}
+administrator, you may consider restricting these
+commands with taginfo (@pxref{user-defined logging}).}
+
address@hidden Deleting tags
address@hidden Deleting branch tags
address@hidden Removing tags
address@hidden Removing branch tags
address@hidden Tags, deleting
address@hidden Branch tags, deleting
+To delete a tag, specify the @samp{-d} option to either
address@hidden tag} or @code{cvs rtag}. For example:
+
address@hidden
+cvs rtag -d rel-0-4 tc
address@hidden example
+
address@hidden
+deletes the non-branch tag @code{rel-0-4} from the module @code{tc}.
+In the event that branch tags are encountered within the repository
+with the given name, a warning message will be issued and the branch
+tag will not be deleted. If you are absolutely certain you know what
+you are doing, the @code{-B} option may be specified to allow deletion
+of branch tags. In that case, any non-branch tags encountered will
+trigger warnings and will not be deleted.
+
address@hidden
address@hidden: Moving branch tags is very dangerous! If you think
+you need the @code{-B} option, think again and ask your @sc{cvs}
+administrator about it (if that isn't you). There is almost certainly
+another way to accomplish what you want to accomplish.}
+
address@hidden Moving tags
address@hidden Moving branch tags
address@hidden Tags, moving
address@hidden Branch tags, moving
+When we say @dfn{move} a tag, we mean to make the same
+name point to different revisions. For example, the
address@hidden tag may currently point to revision 1.4
+of @file{backend.c} and perhaps we want to make it
+point to revision 1.6. To move a non-branch tag, specify the
address@hidden option to either @code{cvs tag} or @code{cvs
+rtag}. For example, the task just mentioned might be
+accomplished as:
+
address@hidden
+cvs tag -r 1.6 -F stable backend.c
address@hidden example
+
address@hidden
+If any branch tags are encountered in the repository
+with the given name, a warning is issued and the branch
+tag is not disturbed. If you are absolutely certain you
+wish to move the branch tag, the @code{-B} option may be specified.
+In that case, non-branch tags encountered with the given
+name are ignored with a warning message.
+
address@hidden
address@hidden: Moving branch tags is very dangerous! If you think you
+need the @code{-B} option, think again and ask your @sc{cvs}
+administrator about it (if that isn't you). There is almost certainly
+another way to accomplish what you want to accomplish.}
+
address@hidden Renaming tags
address@hidden Tags, renaming
+When we say @dfn{rename} a tag, we mean to make a
+different name point to the same revisions as the old
+tag. For example, one may have misspelled the tag name
+and want to correct it (hopefully before others are
+relying on the old spelling). To rename a tag, first
+create a new tag using the @samp{-r} option to
address@hidden rtag}, and then delete the old name. (Caution:
+this method will not work with branch tags.)
+This leaves the new tag on exactly the
+same files as the old tag. For example:
+
address@hidden
+cvs rtag -r old-name-0-4 rel-0-4 tc
+cvs rtag -d old-name-0-4 tc
address@hidden example
+
address@hidden Tagging add/remove
address@hidden Tagging and adding and removing files
+
+The subject of exactly how tagging interacts with
+adding and removing files is somewhat obscure; for the
+most part @sc{cvs} will keep track of whether files
+exist or not without too much fussing. By default,
+tags are applied to only files which have a revision
+corresponding to what is being tagged. Files which did
+not exist yet, or which were already removed, simply
+omit the tag, and @sc{cvs} knows to treat the absence
+of a tag as meaning that the file didn't exist as of
+that tag.
+
+However, this can lose a small amount of information.
+For example, suppose a file was added and then removed.
+Then, if the tag is missing for that file, there is no
+way to know whether the tag refers to the time before
+the file was added, or the time after it was removed.
+If you specify the @samp{-r} option to @code{cvs rtag},
+then @sc{cvs} tags the files which have been removed,
+and thereby avoids this problem. For example, one
+might specify @code{-r HEAD} to tag the head.
+
+On the subject of adding and removing files, the
address@hidden rtag} command has a @samp{-a} option which
+means to clear the tag from removed files that would
+not otherwise be tagged. For example, one might
+specify this option in conjunction with @samp{-F} when
+moving a tag. If one moved a tag without @samp{-a},
+then the tag in the removed files might still refer to
+the old revision, rather than reflecting the fact that
+the file had been removed. I don't think this is
+necessary if @samp{-r} is specified, as noted above.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Sticky tags
address@hidden Sticky tags
address@hidden Sticky tags
address@hidden Tags, sticky
+
address@hidden A somewhat related issue is per-directory sticky
address@hidden tags (see comment at CVS/Tag in node Working
address@hidden directory storage); we probably want to say
address@hidden something like "you can set a sticky tag for only
address@hidden some files, but you don't want to" or some such.
+
+Sometimes a working copy's revision has extra data
+associated with it, for example it might be on a branch
+(@pxref{Branching and merging}), or restricted to
+versions prior to a certain date by @samp{checkout -D}
+or @samp{update -D}. Because this data persists --
+that is, it applies to subsequent commands in the
+working copy -- we refer to it as @dfn{sticky}.
+
+Most of the time, stickiness is an obscure aspect of
address@hidden that you don't need to think about. However,
+even if you don't want to use the feature, you may need
+to know @emph{something} about sticky tags (for
+example, how to avoid them!).
+
+You can use the @code{status} command to see if any
+sticky tags or dates are set:
+
address@hidden
+$ cvs status driver.c
+===================================================================
+File: driver.c Status: Up-to-date
+
+ Version: 1.7.2.1 Sat Dec 5 19:35:03 1992
+ RCS Version: 1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v
+ Sticky Tag: rel-1-0-patches (branch: 1.7.2)
+ Sticky Date: (none)
+ Sticky Options: (none)
+
address@hidden example
+
address@hidden Resetting sticky tags
address@hidden Sticky tags, resetting
address@hidden Deleting sticky tags
+The sticky tags will remain on your working files until
+you delete them with @samp{cvs update -A}. The
address@hidden option merges local changes into the version of the
+file from the head of the trunk, removing any sticky tags,
+dates, or options. See @ref{update} for more on the operation
+of @code{cvs update}.
+
address@hidden Sticky date
+The most common use of sticky tags is to identify which
+branch one is working on, as described in
address@hidden branches}. However, non-branch
+sticky tags have uses as well. For example,
+suppose that you want to avoid updating your working
+directory, to isolate yourself from possibly
+destabilizing changes other people are making. You
+can, of course, just refrain from running @code{cvs
+update}. But if you want to avoid updating only a
+portion of a larger tree, then sticky tags can help.
+If you check out a certain revision (such as 1.4) it
+will become sticky. Subsequent @code{cvs update}
+commands will
+not retrieve the latest revision until you reset the
+tag with @code{cvs update -A}. Likewise, use of the
address@hidden option to @code{update} or @code{checkout}
+sets a @dfn{sticky date}, which, similarly, causes that
+date to be used for future retrievals.
+
+People often want to retrieve an old version of
+a file without setting a sticky tag. This can
+be done with the @samp{-p} option to @code{checkout} or
address@hidden, which sends the contents of the file to
+standard output. For example:
address@hidden
+$ cvs update -p -r 1.1 file1 >file1
+===================================================================
+Checking out file1
+RCS: /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v
+VERS: 1.1
+***************
+$
address@hidden example
+
+However, this isn't the easiest way, if you are asking
+how to undo a previous checkin (in this example, put
address@hidden back to the way it was as of revision
+1.1). In that case you are better off using the
address@hidden option to @code{update}; for further
+discussion see @ref{Merging two revisions}.
+
address@hidden
---------------------------------------------------------------------
address@hidden Branching and merging
address@hidden Branching and merging
address@hidden Branching
address@hidden Merging
address@hidden Copying changes
address@hidden Main trunk and branches
address@hidden Revision tree, making branches
address@hidden Branches, copying changes between
address@hidden Changes, copying between branches
address@hidden Modifications, copying between branches
+
address@hidden allows you to isolate changes onto a separate
+line of development, known as a @dfn{branch}. When you
+change files on a branch, those changes do not appear
+on the main trunk or other branches.
+
+Later you can move changes from one branch to another
+branch (or the main trunk) by @dfn{merging}. Merging
+involves first running @code{cvs update -j}, to merge
+the changes into the working directory.
+You can then commit that revision, and thus effectively
+copy the changes onto another branch.
+
address@hidden
+* Branches motivation:: What branches are good for
+* Creating a branch:: Creating a branch
+* Accessing branches:: Checking out and updating branches
+* Branches and revisions:: Branches are reflected in revision numbers
+* Magic branch numbers:: Magic branch numbers
+* Merging a branch:: Merging an entire branch
+* Merging more than once:: Merging from a branch several times
+* Merging two revisions:: Merging differences between two revisions
+* Merging adds and removals:: What if files are added or removed?
+* Merging and keywords:: Avoiding conflicts due to keyword substitution
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Branches motivation
address@hidden What branches are good for
address@hidden Branches motivation
address@hidden What branches are good for
address@hidden Motivation for branches
+
address@hidden FIXME: this node mentions one way to use branches,
address@hidden but it is by no means the only way. For example,
address@hidden the technique of committing a new feature on a branch,
address@hidden until it is ready for the main trunk. The whole
address@hidden thing is generally speaking more akin to the
address@hidden "Revision management" node although it isn't clear to
address@hidden me whether policy matters should be centralized or
address@hidden distributed throughout the relevant sections.
+Suppose that release 1.0 of tc has been made. You are continuing to
+develop tc, planning to create release 1.1 in a couple of months. After a
+while your customers start to complain about a fatal bug. You check
+out release 1.0 (@pxref{Tags}) and find the bug
+(which turns out to have a trivial fix). However, the current revision
+of the sources are in a state of flux and are not expected to be stable
+for at least another month. There is no way to make a
+bugfix release based on the newest sources.
+
+The thing to do in a situation like this is to create a @dfn{branch} on
+the revision trees for all the files that make up
+release 1.0 of tc. You can then make
+modifications to the branch without disturbing the main trunk. When the
+modifications are finished you can elect to either incorporate them on
+the main trunk, or leave them on the branch.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Creating a branch
address@hidden Creating a branch
address@hidden Creating a branch
address@hidden Branch, creating a
address@hidden tag (subcommand), creating a branch using
address@hidden rtag (subcommand), creating a branch using
+
+You can create a branch with @code{tag -b}; for
+example, assuming you're in a working copy:
+
address@hidden
+$ cvs tag -b rel-1-0-patches
address@hidden example
+
address@hidden FIXME: we should be more explicit about the value of
address@hidden having a tag on the branchpoint. For example
address@hidden "cvs tag rel-1-0-patches-branchpoint" before
address@hidden the "cvs tag -b". This points out that
address@hidden rel-1-0-patches is a pretty awkward name for
address@hidden this example (more so than for the rtag example
address@hidden below).
+
+This splits off a branch based on the current revisions
+in the working copy, assigning that branch the name
address@hidden
+
+It is important to understand that branches get created
+in the repository, not in the working copy. Creating a
+branch based on current revisions, as the above example
+does, will @emph{not} automatically switch the working
+copy to be on the new branch. For information on how
+to do that, see @ref{Accessing branches}.
+
+You can also create a branch without reference to any
+working copy, by using @code{rtag}:
+
address@hidden
+$ cvs rtag -b -r rel-1-0 rel-1-0-patches tc
address@hidden example
+
address@hidden rel-1-0} says that this branch should be
+rooted at the revision that
+corresponds to the tag @samp{rel-1-0}. It need not
+be the most recent revision -- it's often useful to
+split a branch off an old revision (for example, when
+fixing a bug in a past release otherwise known to be
+stable).
+
+As with @samp{tag}, the @samp{-b} flag tells
address@hidden to create a branch (rather than just a
+symbolic revision name). Note that the numeric
+revision number that matches @samp{rel-1-0} will
+probably be different from file to file.
+
+So, the full effect of the command is to create a new
+branch -- named @samp{rel-1-0-patches} -- in module
address@hidden, rooted in the revision tree at the point tagged
+by @samp{rel-1-0}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Accessing branches
address@hidden Accessing branches
address@hidden Check out a branch
address@hidden Retrieve a branch
address@hidden Access a branch
address@hidden Identifying a branch
address@hidden Branch, check out
address@hidden Branch, retrieving
address@hidden Branch, accessing
address@hidden Branch, identifying
+
+You can retrieve a branch in one of two ways: by
+checking it out fresh from the repository, or by
+switching an existing working copy over to the branch.
+
+To check out a branch from the repository, invoke
address@hidden with the @samp{-r} flag, followed by
+the tag name of the branch (@pxref{Creating a branch}):
+
address@hidden
+$ cvs checkout -r rel-1-0-patches tc
address@hidden example
+
+Or, if you already have a working copy, you can switch
+it to a given branch with @samp{update -r}:
+
address@hidden
+$ cvs update -r rel-1-0-patches tc
address@hidden example
+
address@hidden
+or equivalently:
+
address@hidden
+$ cd tc
+$ cvs update -r rel-1-0-patches
address@hidden example
+
+It does not matter if the working copy was originally
+on the main trunk or on some other branch -- the above
+command will switch it to the named branch. And
+similarly to a regular @samp{update} command,
address@hidden -r} merges any changes you have made,
+notifying you of conflicts where they occur.
+
+Once you have a working copy tied to a particular
+branch, it remains there until you tell it otherwise.
+This means that changes checked in from the working
+copy will add new revisions on that branch, while
+leaving the main trunk and other branches unaffected.
+
address@hidden Branches, sticky
+To find out what branch a working copy is on, you can
+use the @samp{status} command. In its output, look for
+the field named @samp{Sticky tag} (@pxref{Sticky tags})
+-- that's @sc{cvs}'s way of telling you the branch, if
+any, of the current working files:
+
address@hidden
+$ cvs status -v driver.c backend.c
+===================================================================
+File: driver.c Status: Up-to-date
+
+ Version: 1.7 Sat Dec 5 18:25:54 1992
+ RCS Version: 1.7 /u/cvsroot/yoyodyne/tc/driver.c,v
+ Sticky Tag: rel-1-0-patches (branch: 1.7.2)
+ Sticky Date: (none)
+ Sticky Options: (none)
+
+ Existing Tags:
+ rel-1-0-patches (branch: 1.7.2)
+ rel-1-0 (revision: 1.7)
+
+===================================================================
+File: backend.c Status: Up-to-date
+
+ Version: 1.4 Tue Dec 1 14:39:01 1992
+ RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v
+ Sticky Tag: rel-1-0-patches (branch: 1.4.2)
+ Sticky Date: (none)
+ Sticky Options: (none)
+
+ Existing Tags:
+ rel-1-0-patches (branch: 1.4.2)
+ rel-1-0 (revision: 1.4)
+ rel-0-4 (revision: 1.4)
+
address@hidden example
+
+Don't be confused by the fact that the branch numbers
+for each file are different (@samp{1.7.2} and
address@hidden respectively). The branch tag is the
+same, @samp{rel-1-0-patches}, and the files are
+indeed on the same branch. The numbers simply reflect
+the point in each file's revision history at which the
+branch was made. In the above example, one can deduce
+that @samp{driver.c} had been through more changes than
address@hidden before this branch was created.
+
+See @ref{Branches and revisions} for details about how
+branch numbers are constructed.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Branches and revisions
address@hidden Branches and revisions
address@hidden Branch number
address@hidden Number, branch
address@hidden Revision numbers (branches)
+
+Ordinarily, a file's revision history is a linear
+series of increments (@pxref{Revision numbers}):
+
address@hidden
+ +-----+ +-----+ +-----+ +-----+ +-----+
+ ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
+ +-----+ +-----+ +-----+ +-----+ +-----+
address@hidden example
+
+However, @sc{cvs} is not limited to linear development. The
address@hidden tree} can be split into @dfn{branches},
+where each branch is a self-maintained line of
+development. Changes made on one branch can easily be
+moved back to the main trunk.
+
+Each branch has a @dfn{branch number}, consisting of an
+odd number of period-separated decimal integers. The
+branch number is created by appending an integer to the
+revision number where the corresponding branch forked
+off. Having branch numbers allows more than one branch
+to be forked off from a certain revision.
+
address@hidden 3500
+All revisions on a branch have revision numbers formed
+by appending an ordinal number to the branch number.
+The following figure illustrates branching with an
+example.
+
address@hidden
address@hidden This example used to have a 1.2.2.4 revision, which
address@hidden might help clarify that development can continue on
address@hidden 1.2.2. Might be worth reinstating if it can be done
address@hidden without overfull hboxes.
address@hidden
+ +-------------+
+ Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 !
+ / +-------------+
+ /
+ /
+ +---------+ +---------+ +---------+
+Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
+ / +---------+ +---------+ +---------+
+ /
+ /
++-----+ +-----+ +-----+ +-----+ +-----+
+! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
++-----+ +-----+ +-----+ +-----+ +-----+
+ !
+ !
+ ! +---------+ +---------+ +---------+
+Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 !
+ +---------+ +---------+ +---------+
+
address@hidden group
address@hidden example
+
address@hidden -- However, at least for me the figure is not enough. I
suggest more
address@hidden -- text to accompany it. "A picture is worth a thousand
words", so you
address@hidden -- have to make sure the reader notices the couple of hundred
words
address@hidden -- *you* had in mind more than the others!
+
address@hidden -- Why an even number of segments? This section implies that
this is
address@hidden -- how the main trunk is distinguished from branch roots, but
you never
address@hidden -- explicitly say that this is the purpose of the [by itself
rather
address@hidden -- surprising] restriction to an even number of segments.
+
+The exact details of how the branch number is
+constructed is not something you normally need to be
+concerned about, but here is how it works: When
address@hidden creates a branch number it picks the first
+unused even integer, starting with 2. So when you want
+to create a branch from revision 6.4 it will be
+numbered 6.4.2. All branch numbers ending in a zero
+(such as 6.4.0) are used internally by @sc{cvs}
+(@pxref{Magic branch numbers}). The branch 1.1.1 has a
+special meaning. @xref{Tracking sources}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Magic branch numbers
address@hidden Magic branch numbers
+
address@hidden Want xref to here from "log"?
+
+This section describes a @sc{cvs} feature called
address@hidden branches}. For most purposes, you need not
+worry about magic branches; @sc{cvs} handles them for
+you. However, they are visible to you in certain
+circumstances, so it may be useful to have some idea of
+how it works.
+
+Externally, branch numbers consist of an odd number of
+dot-separated decimal integers. @xref{Revision
+numbers}. That is not the whole truth, however. For
+efficiency reasons @sc{cvs} sometimes inserts an extra 0
+in the second rightmost position (1.2.4 becomes
+1.2.0.4, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so
+on).
+
address@hidden does a pretty good job at hiding these so
+called magic branches, but in a few places the hiding
+is incomplete:
+
address@hidden @bullet
address@hidden
+The magic branch number appears in the output from
address@hidden log}.
address@hidden What output should appear instead?
+
address@hidden
+You cannot specify a symbolic branch name to @code{cvs
+admin}.
+
address@hidden itemize
+
address@hidden Can CVS do this automatically the first time
address@hidden you check something in to that branch? Should
address@hidden it?
+You can use the @code{admin} command to reassign a
+symbolic name to a branch the way @sc{rcs} expects it
+to be. If @code{R4patches} is assigned to the branch
+1.4.2 (magic branch number 1.4.0.2) in file
address@hidden you can do this:
+
address@hidden
+$ cvs admin -NR4patches:1.4.2 numbers.c
address@hidden example
+
+It only works if at least one revision is already
+committed on the branch. Be very careful so that you
+do not assign the tag to the wrong number. (There is
+no way to see how the tag was assigned yesterday).
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Merging a branch
address@hidden Merging an entire branch
address@hidden Merging a branch
address@hidden -j (merging branches)
+
+You can merge changes made on a branch into your working copy by giving
+the @samp{-j @var{branchname}} flag to the @code{update} subcommand. With one
address@hidden @var{branchname}} option it merges the changes made between the
+greatest common ancestor (GCA) of the branch and the destination revision (in
+the simple case below the GCA is the point where the branch forked) and the
+newest revision on that branch into your working copy.
+
address@hidden Join
+The @samp{-j} stands for ``join''.
+
address@hidden Branch merge example
address@hidden Example, branch merge
address@hidden Merge, branch example
+Consider this revision tree:
+
address@hidden
++-----+ +-----+ +-----+ +-----+
+! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 ! <- The main trunk
++-----+ +-----+ +-----+ +-----+
+ !
+ !
+ ! +---------+ +---------+
+Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
+ +---------+ +---------+
address@hidden example
+
address@hidden
+The branch 1.2.2 has been given the tag (symbolic name) @samp{R1fix}. The
+following example assumes that the module @samp{mod} contains only one
+file, @file{m.c}.
+
address@hidden
+$ cvs checkout mod # @r{Retrieve the latest revision, 1.4}
+
+$ cvs update -j R1fix m.c # @r{Merge all changes made on the branch,}
+ # @r{i.e. the changes between revision 1.2}
+ # @r{and 1.2.2.2, into your working copy}
+ # @r{of the file.}
+
+$ cvs commit -m "Included R1fix" # @r{Create revision 1.5.}
address@hidden example
+
+A conflict can result from a merge operation. If that
+happens, you should resolve it before committing the
+new revision. @xref{Conflicts example}.
+
+If your source files contain keywords (@pxref{Keyword substitution}),
+you might be getting more conflicts than strictly necessary. See
address@hidden and keywords}, for information on how to avoid this.
+
+The @code{checkout} command also supports the @samp{-j @var{branchname}} flag.
The
+same effect as above could be achieved with this:
+
address@hidden
+$ cvs checkout -j R1fix mod
+$ cvs commit -m "Included R1fix"
address@hidden example
+
+It should be noted that @code{update -j @var{tagname}} will also work but may
+not produce the desired result. @xref{Merging adds and removals}, for more.
+
address@hidden Merging more than once
address@hidden Merging from a branch several times
+
+Continuing our example, the revision tree now looks
+like this:
+
address@hidden
++-----+ +-----+ +-----+ +-----+ +-----+
+! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
++-----+ +-----+ +-----+ +-----+ +-----+
+ ! *
+ ! *
+ ! +---------+ +---------+
+Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
+ +---------+ +---------+
address@hidden example
+
address@hidden
+where the starred line represents the merge from the
address@hidden branch to the main trunk, as just
+discussed.
+
+Now suppose that development continues on the
address@hidden branch:
+
address@hidden
++-----+ +-----+ +-----+ +-----+ +-----+
+! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
++-----+ +-----+ +-----+ +-----+ +-----+
+ ! *
+ ! *
+ ! +---------+ +---------+ +---------+
+Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
+ +---------+ +---------+ +---------+
address@hidden example
+
address@hidden
+and then you want to merge those new changes onto the
+main trunk. If you just use the @code{cvs update -j
+R1fix m.c} command again, @sc{cvs} will attempt to
+merge again the changes which you have already merged,
+which can have undesirable side effects.
+
+So instead you need to specify that you only want to
+merge the changes on the branch which have not yet been
+merged into the trunk. To do that you specify two
address@hidden options, and @sc{cvs} merges the changes from
+the first revision to the second revision. For
+example, in this case the simplest way would be
+
address@hidden
+cvs update -j 1.2.2.2 -j R1fix m.c # @r{Merge changes from 1.2.2.2 to the}
+ # @r{head of the R1fix branch}
address@hidden example
+
+The problem with this is that you need to specify the
+1.2.2.2 revision manually. A slightly better approach
+might be to use the date the last merge was done:
+
address@hidden
+cvs update -j R1fix:yesterday -j R1fix m.c
address@hidden example
+
+Better yet, tag the R1fix branch after every merge into
+the trunk, and then use that tag for subsequent merges:
+
address@hidden
+cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Merging two revisions
address@hidden Merging differences between any two revisions
address@hidden Merging two revisions
address@hidden Revisions, merging differences between
address@hidden Differences, merging
+
+With two @samp{-j @var{revision}} flags, the @code{update}
+(and @code{checkout}) command can merge the differences
+between any two revisions into your working file.
+
address@hidden Undoing a change
address@hidden Removing a change
address@hidden
+$ cvs update -j 1.5 -j 1.3 backend.c
address@hidden example
+
address@hidden
+will undo all changes made between revision
+1.3 and 1.5. Note the order of the revisions!
+
+If you try to use this option when operating on
+multiple files, remember that the numeric revisions will
+probably be very different between the various files.
+You almost always use symbolic
+tags rather than revision numbers when operating on
+multiple files.
+
address@hidden Restoring old version of removed file
address@hidden Resurrecting old version of dead file
+Specifying two @samp{-j} options can also undo file
+removals or additions. For example, suppose you have
+a file
+named @file{file1} which existed as revision 1.1, and
+you then removed it (thus adding a dead revision 1.2).
+Now suppose you want to add it again, with the same
+contents it had previously. Here is how to do it:
+
address@hidden
+$ cvs update -j 1.2 -j 1.1 file1
+U file1
+$ cvs commit -m test
+Checking in file1;
+/tmp/cvs-sanity/cvsroot/first-dir/file1,v <-- file1
+new revision: 1.3; previous revision: 1.2
+done
+$
address@hidden example
+
address@hidden Merging adds and removals
address@hidden Merging can add or remove files
+
+If the changes which you are merging involve removing
+or adding some files, @code{update -j} will reflect
+such additions or removals.
+
address@hidden FIXME: This example needs a lot more explanation.
address@hidden We also need other examples for some of the other
address@hidden cases (not all--there are too many--as long as we present a
address@hidden coherent general principle).
+For example:
address@hidden
+cvs update -A
+touch a b c
+cvs add a b c ; cvs ci -m "added" a b c
+cvs tag -b branchtag
+cvs update -r branchtag
+touch d ; cvs add d
+rm a ; cvs rm a
+cvs ci -m "added d, removed a"
+cvs update -A
+cvs update -jbranchtag
address@hidden example
+
+After these commands are executed and a @samp{cvs commit} is done,
+file @file{a} will be removed and file @file{d} added in the main branch.
address@hidden (which was determined by trying it)
+
+Note that using a single static tag (@samp{-j @var{tagname}})
+rather than a dynamic tag (@samp{-j @var{branchname}}) to merge
+changes from a branch will usually not remove files which were removed on the
+branch since @sc{cvs} does not automatically add static tags to dead revisions.
+The exception to this rule occurs when
+a static tag has been attached to a dead revision manually. Use the branch tag
+to merge all changes from the branch or use two static tags as merge endpoints
+to be sure that all intended changes are propagated in the merge.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Merging and keywords
address@hidden Merging and keywords
address@hidden Merging, and keyword substitution
address@hidden Keyword substitution, and merging
address@hidden -j (merging branches), and keyword substitution
address@hidden -kk, to avoid conflicts during a merge
+
+If you merge files containing keywords (@pxref{Keyword
+substitution}), you will normally get numerous
+conflicts during the merge, because the keywords are
+expanded differently in the revisions which you are
+merging.
+
+Therefore, you will often want to specify the
address@hidden (@pxref{Substitution modes}) switch to the
+merge command line. By substituting just the name of
+the keyword, not the expanded value of that keyword,
+this option ensures that the revisions which you are
+merging will be the same as each other, and avoid
+spurious conflicts.
+
+For example, suppose you have a file like this:
+
address@hidden
+ +---------+
+ _! 1.1.2.1 ! <- br1
+ / +---------+
+ /
+ /
++-----+ +-----+
+! 1.1 !----! 1.2 !
++-----+ +-----+
address@hidden example
+
address@hidden
+and your working directory is currently on the trunk
+(revision 1.2). Then you might get the following
+results from a merge:
+
address@hidden
+$ cat file1
+key $ Revision: 1.2 $
+. . .
+$ cvs update -j br1
+U file1
+RCS file: /cvsroot/first-dir/file1,v
+retrieving revision 1.1
+retrieving revision 1.1.2.1
+Merging differences between 1.1 and 1.1.2.1 into file1
+rcsmerge: warning: conflicts during merge
+$ cat file1
address@hidden<<<<<<< file1
+key $ Revision: 1.2 $
address@hidden
+key $ Revision: 1.1.2.1 $
address@hidden>>>>>>> 1.1.2.1
+. . .
address@hidden example
+
+What happened was that the merge tried to merge the
+differences between 1.1 and 1.1.2.1 into your working
+directory. So, since the keyword changed from
address@hidden: 1.1} to @code{Revision: 1.1.2.1},
address@hidden tried to merge that change into your working
+directory, which conflicted with the fact that your
+working directory had contained @code{Revision: 1.2}.
+
+Here is what happens if you had used @samp{-kk}:
+
address@hidden
+$ cat file1
+key $ Revision: 1.2 $
+. . .
+$ cvs update -kk -j br1
+U file1
+RCS file: /cvsroot/first-dir/file1,v
+retrieving revision 1.1
+retrieving revision 1.1.2.1
+Merging differences between 1.1 and 1.1.2.1 into file1
+$ cat file1
+key $ Revision$
+. . .
address@hidden example
+
+What is going on here is that revision 1.1 and 1.1.2.1
+both expand as plain @code{Revision}, and therefore
+merging the changes between them into the working
+directory need not change anything. Therefore, there
+is no conflict.
+
address@hidden: In versions of @sc{cvs} prior to 1.12.2, there was a
+major problem with using @samp{-kk} on merges. Namely, @samp{-kk}
+overrode any default keyword expansion mode set in the archive file in
+the repository. This could, unfortunately for some users, cause data
+corruption in binary files (with a default keyword expansion mode set
+to @samp{-kb}). Therefore, when a repository contained binary files,
+conflicts had to be dealt with manually rather than using @samp{-kk} in
+a merge command.}
+
+In @sc{cvs} version 1.12.2 and later, the keyword expansion mode
+provided on the command line to any @sc{cvs} command no longer
+overrides the @samp{-kb} keyword expansion mode setting for binary
+files, though it will still override other default keyword expansion
+modes. You can now safely merge using @samp{-kk} to avoid spurious conflicts
+on lines containing RCS keywords, even when your repository contains
+binary files.
+
address@hidden
---------------------------------------------------------------------
address@hidden Recursive behavior
address@hidden Recursive behavior
address@hidden Recursive (directory descending)
address@hidden Directory, descending
address@hidden Descending directories
address@hidden Subdirectories
+
+Almost all of the subcommands of @sc{cvs} work
+recursively when you specify a directory as an
+argument. For instance, consider this directory
+structure:
+
address@hidden
+ @code{$HOME}
+ |
+ address@hidden
+ | |
+ address@hidden
+ | (internal @sc{cvs} files)
+ address@hidden
+ address@hidden
+ address@hidden
+ address@hidden
+ address@hidden
+ address@hidden
+ | |
+ | address@hidden
+ | | (internal @sc{cvs} files)
+ | address@hidden
+ |
+ address@hidden
+ |
+ address@hidden
+ | (internal @sc{cvs} files)
+ address@hidden
+ address@hidden
address@hidden example
+
address@hidden
+If @file{tc} is the current working directory, the
+following is true:
+
address@hidden @bullet
address@hidden
address@hidden update testing} is equivalent to
+
address@hidden
+cvs update testing/testpgm.t testing/test2.t
address@hidden example
+
address@hidden
address@hidden update testing man} updates all files in the
+subdirectories
+
address@hidden
address@hidden update .} or just @samp{cvs update} updates
+all files in the @code{tc} directory
address@hidden itemize
+
+If no arguments are given to @code{update} it will
+update all files in the current working directory and
+all its subdirectories. In other words, @file{.} is a
+default argument to @code{update}. This is also true
+for most of the @sc{cvs} subcommands, not only the
address@hidden command.
+
+The recursive behavior of the @sc{cvs} subcommands can be
+turned off with the @samp{-l} option.
+Conversely, the @samp{-R} option can be used to force recursion if
address@hidden is specified in @file{~/.cvsrc} (@pxref{~/.cvsrc}).
+
address@hidden
+$ cvs update -l # @r{Don't update files in subdirectories}
address@hidden example
+
address@hidden
---------------------------------------------------------------------
address@hidden Adding and removing
address@hidden Adding, removing, and renaming files and directories
+
+In the course of a project, one will often add new
+files. Likewise with removing or renaming, or with
+directories. The general concept to keep in mind in
+all these cases is that instead of making an
+irreversible change you want @sc{cvs} to record the
+fact that a change has taken place, just as with
+modifying an existing file. The exact mechanisms to do
+this in @sc{cvs} vary depending on the situation.
+
address@hidden
+* Adding files:: Adding files
+* Removing files:: Removing files
+* Removing directories:: Removing directories
+* Moving files:: Moving and renaming files
+* Moving directories:: Moving and renaming directories
address@hidden menu
+
address@hidden Adding files
address@hidden Adding files to a directory
address@hidden Adding files
+
+To add a new file to a directory, follow these steps.
+
address@hidden @bullet
address@hidden
+You must have a working copy of the directory.
address@hidden the source}.
+
address@hidden
+Create the new file inside your working copy of the directory.
+
address@hidden
+Use @samp{cvs add @var{filename}} to tell @sc{cvs} that you
+want to version control the file. If the file contains
+binary data, specify @samp{-kb} (@pxref{Binary files}).
+
address@hidden
+Use @samp{cvs commit @var{filename}} to actually check
+in the file into the repository. Other developers
+cannot see the file until you perform this step.
address@hidden itemize
+
+You can also use the @code{add} command to add a new
+directory.
address@hidden FIXCVS and/or FIXME: Adding a directory doesn't
address@hidden require the commit step. This probably can be
address@hidden considered a CVS bug, but it is possible we should
address@hidden warn people since this behavior probably won't be
address@hidden changing right away.
+
+Unlike most other commands, the @code{add} command is
+not recursive. You cannot even type @samp{cvs add
+foo/bar}! Instead, you have to
address@hidden FIXCVS: This is, of course, not a feature. It is
address@hidden just that no one has gotten around to fixing "cvs add
address@hidden foo/bar".
+
address@hidden
+$ cd foo
+$ cvs add bar
address@hidden example
+
address@hidden add (subcommand)
address@hidden Command {cvs add} address@hidden kflag] address@hidden message]
files @dots{}
+
+Schedule @var{files} to be added to the repository.
+The files or directories specified with @code{add} must
+already exist in the current directory. To add a whole
+new directory hierarchy to the source repository (for
+example, files received from a third-party vendor), use
+the @code{import} command instead. @xref{import}.
+
+The added files are not placed in the source repository
+until you use @code{commit} to make the change
+permanent. Doing an @code{add} on a file that was
+removed with the @code{remove} command will undo the
+effect of the @code{remove}, unless a @code{commit}
+command intervened. @xref{Removing files}, for an
+example.
+
+The @samp{-k} option specifies the default way that
+this file will be checked out; for more information see
address@hidden modes}.
+
address@hidden As noted in BUGS, -m is broken client/server (Nov
address@hidden 96). Also see testsuite log2-* tests.
+The @samp{-m} option specifies a description for the
+file. This description appears in the history log (if
+it is enabled, @pxref{history file}). It will also be
+saved in the version history inside the repository when
+the file is committed. The @code{log} command displays
+this description. The description can be changed using
address@hidden -t}. @xref{admin}. If you omit the
address@hidden @var{description}} flag, an empty string will
+be used. You will not be prompted for a description.
address@hidden deffn
+
+For example, the following commands add the file
address@hidden to the repository:
+
address@hidden This example used to specify
address@hidden -m "Optimizer and code generation passes."
address@hidden to the cvs add command, but that doesn't work
address@hidden client/server (see log2 in sanity.sh). Should fix CVS,
address@hidden but also seems strange to document things which
address@hidden don't work...
address@hidden
+$ cvs add backend.c
+$ cvs commit -m "Early version. Not yet compilable." backend.c
address@hidden example
+
+When you add a file it is added only on the branch
+which you are working on (@pxref{Branching and merging}). You can
+later merge the additions to another branch if you want
+(@pxref{Merging adds and removals}).
address@hidden Should we mention that earlier versions of CVS
address@hidden lacked this feature (1.3) or implemented it in a buggy
address@hidden way (well, 1.8 had many bugs in cvs update -j)?
address@hidden Should we mention the bug/limitation regarding a
address@hidden file being a regular file on one branch and a directory
address@hidden on another?
address@hidden FIXME: This needs an example, or several, here or
address@hidden elsewhere, for it to make much sense.
address@hidden Somewhere we need to discuss the aspects of death
address@hidden support which don't involve branching, I guess.
address@hidden Like the ability to re-create a release from a tag.
+
address@hidden
---------------------------------------------------------------------
address@hidden Removing files
address@hidden Removing files
address@hidden Removing files
address@hidden Deleting files
+
address@hidden FIXME: this node wants to be split into several
address@hidden smaller nodes. Could make these children of
address@hidden "Adding and removing", probably (death support could
address@hidden be its own section, for example, as could the
address@hidden various bits about undoing mistakes in adding and
address@hidden removing).
+Directories change. New files are added, and old files
+disappear. Still, you want to be able to retrieve an
+exact copy of old releases.
+
+Here is what you can do to remove a file,
+but remain able to retrieve old revisions:
+
address@hidden @bullet
address@hidden FIXME: should probably be saying something about
address@hidden having a working directory in the first place.
address@hidden
+Make sure that you have not made any uncommitted
+modifications to the file. @xref{Viewing differences},
+for one way to do that. You can also use the
address@hidden or @code{update} command. If you remove
+the file without committing your changes, you will of
+course not be able to retrieve the file as it was
+immediately before you deleted it.
+
address@hidden
+Remove the file from your working copy of the directory.
+You can for instance use @code{rm}.
+
address@hidden
+Use @samp{cvs remove @var{filename}} to tell @sc{cvs} that
+you really want to delete the file.
+
address@hidden
+Use @samp{cvs commit @var{filename}} to actually
+perform the removal of the file from the repository.
address@hidden itemize
+
address@hidden FIXME: Somehow this should be linked in with a more
address@hidden general discussion of death support. I don't know
address@hidden whether we want to use the term "death support" or
address@hidden not (we can perhaps get by without it), but we do
address@hidden need to discuss the "dead" state in "cvs log" and
address@hidden related subjects. The current discussion is
address@hidden scattered around, and not xref'd to each other.
address@hidden FIXME: I think this paragraph wants to be moved
address@hidden later down, at least after the first example.
+When you commit the removal of the file, @sc{cvs}
+records the fact that the file no longer exists. It is
+possible for a file to exist on only some branches and
+not on others, or to re-add another file with the same
+name later. @sc{cvs} will correctly create or not create
+the file, based on the @samp{-r} and @samp{-D} options
+specified to @code{checkout} or @code{update}.
+
address@hidden FIXME: This style seems to clash with how we
address@hidden document things in general.
address@hidden Remove (subcommand)
address@hidden Command {cvs remove} [options] files @dots{}
+
+Schedule file(s) to be removed from the repository
+(files which have not already been removed from the
+working directory are not processed). This command
+does not actually remove the file from the repository
+until you commit the removal. For a full list of
+options, see @ref{Invoking CVS}.
address@hidden deffn
+
+Here is an example of removing several files:
+
address@hidden
+$ cd test
+$ rm *.c
+$ cvs remove
+cvs remove: Removing .
+cvs remove: scheduling a.c for removal
+cvs remove: scheduling b.c for removal
+cvs remove: use 'cvs commit' to remove these files permanently
+$ cvs ci -m "Removed unneeded files"
+cvs commit: Examining .
+cvs commit: Committing .
address@hidden example
+
+As a convenience you can remove the file and @code{cvs
+remove} it in one step, by specifying the @samp{-f}
+option. For example, the above example could also be
+done like this:
+
address@hidden
+$ cd test
+$ cvs remove -f *.c
+cvs remove: scheduling a.c for removal
+cvs remove: scheduling b.c for removal
+cvs remove: use 'cvs commit' to remove these files permanently
+$ cvs ci -m "Removed unneeded files"
+cvs commit: Examining .
+cvs commit: Committing .
address@hidden example
+
+If you execute @code{remove} for a file, and then
+change your mind before you commit, you can undo the
address@hidden with an @code{add} command.
+
address@hidden FIXME: what if you change your mind after you commit
address@hidden it? (answer is also "cvs add" but we don't say that...).
address@hidden We need some index entries for thinks like "undoing
address@hidden removal" too.
+
address@hidden
+$ ls
+CVS ja.h oj.c
+$ rm oj.c
+$ cvs remove oj.c
+cvs remove: scheduling oj.c for removal
+cvs remove: use 'cvs commit' to remove this file permanently
+$ cvs add oj.c
+U oj.c
+cvs add: oj.c, version 1.1.1.1, resurrected
address@hidden example
+
+If you realize your mistake before you run the
address@hidden command you can use @code{update} to
+resurrect the file:
+
address@hidden
+$ rm oj.c
+$ cvs update oj.c
+cvs update: warning: oj.c was lost
+U oj.c
address@hidden example
+
+When you remove a file it is removed only on the branch
+which you are working on (@pxref{Branching and merging}). You can
+later merge the removals to another branch if you want
+(@pxref{Merging adds and removals}).
+
address@hidden Removing directories
address@hidden Removing directories
address@hidden Removing directories
address@hidden Directories, removing
+
+In concept removing directories is somewhat similar to
+removing files---you want the directory to not exist in
+your current working directories, but you also want to
+be able to retrieve old releases in which the directory
+existed.
+
+The way that you remove a directory is to remove all
+the files in it. You don't remove the directory
+itself; there is no way to do that.
+Instead you specify the @samp{-P} option to
address@hidden update} or @code{cvs checkout},
+which will cause @sc{cvs} to remove empty
+directories from working directories.
+(Note that @code{cvs export} always removes empty directories.)
+Probably the
+best way to do this is to always specify @samp{-P}; if
+you want an empty directory then put a dummy file (for
+example @file{.keepme}) in it to prevent @samp{-P} from
+removing it.
+
address@hidden I'd try to give a rationale for this, but I'm not
address@hidden sure there is a particularly convincing one. What
address@hidden we would _like_ is for CVS to do a better job of version
address@hidden controlling whether directories exist, to eliminate the
address@hidden need for -P and so that a file can be a directory in
address@hidden one revision and a regular file in another.
+Note that @samp{-P} is implied by the @samp{-r} or @samp{-D}
+options of @code{checkout}. This way
address@hidden will be able to correctly create the directory
+or not depending on whether the particular version you
+are checking out contains any files in that directory.
+
address@hidden
---------------------------------------------------------------------
address@hidden Moving files
address@hidden Moving and renaming files
address@hidden Moving files
address@hidden Renaming files
address@hidden Files, moving
+
+Moving files to a different directory or renaming them
+is not difficult, but some of the ways in which this
+works may be non-obvious. (Moving or renaming a
+directory is even harder. @xref{Moving directories}.).
+
+The examples below assume that the file @var{old} is renamed to
address@hidden
+
address@hidden
+* Outside:: The normal way to Rename
+* Inside:: A tricky, alternative way
+* Rename by copying:: Another tricky, alternative way
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Outside
address@hidden The Normal way to Rename
+
address@hidden More rename issues. Not sure whether these are
address@hidden worth documenting; I'm putting them here because
address@hidden it seems to be as good a place as any to try to
address@hidden set down the issues.
address@hidden * "cvs annotate" will annotate either the new
address@hidden file or the old file; it cannot annotate _each
address@hidden line_ based on whether it was last changed in the
address@hidden new or old file. Unlike "cvs log", where the
address@hidden consequences of having to select either the new
address@hidden or old name seem fairly benign, this may be a
address@hidden real advantage to having CVS know about renames
address@hidden other than as a deletion and an addition.
+
+The normal way to move a file is to copy @var{old} to
address@hidden, and then issue the normal @sc{cvs} commands
+to remove @var{old} from the repository, and add
address@hidden to it.
address@hidden The following sentence is not true: one must cd into
address@hidden the directory to run "cvs add".
address@hidden (Both @var{old} and @var{new} could
address@hidden contain relative paths, for example @file{foo/bar.c}).
+
address@hidden
+$ mv @var{old} @var{new}
+$ cvs remove @var{old}
+$ cvs add @var{new}
+$ cvs commit -m "Renamed @var{old} to @var{new}" @var{old} @var{new}
address@hidden example
+
+This is the simplest way to move a file, it is not
+error-prone, and it preserves the history of what was
+done. Note that to access the history of the file you
+must specify the old or the new name, depending on what
+portion of the history you are accessing. For example,
address@hidden log @var{old}} will give the log up until the
+time of the rename.
+
+When @var{new} is committed its revision numbers will
+start again, usually at 1.1, so if that bothers you,
+use the @samp{-r rev} option to commit. For more
+information see @ref{Assigning revisions}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Inside
address@hidden Moving the history file
+
+This method is more dangerous, since it involves moving
+files inside the repository. Read this entire section
+before trying it out!
+
address@hidden
+$ cd $CVSROOT/@var{dir}
+$ mv @var{old},v @var{new},v
address@hidden example
+
address@hidden
+Advantages:
+
address@hidden @bullet
address@hidden
+The log of changes is maintained intact.
+
address@hidden
+The revision numbers are not affected.
address@hidden itemize
+
address@hidden
+Disadvantages:
+
address@hidden @bullet
address@hidden
+Old releases cannot easily be fetched from the
+repository. (The file will show up as @var{new} even
+in revisions from the time before it was renamed).
+
address@hidden
+There is no log information of when the file was renamed.
+
address@hidden
+Nasty things might happen if someone accesses the history file
+while you are moving it. Make sure no one else runs any of the @sc{cvs}
+commands while you move it.
address@hidden itemize
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Rename by copying
address@hidden Copying the history file
+
+This way also involves direct modifications to the
+repository. It is safe, but not without drawbacks.
+
address@hidden
+# @r{Copy the @sc{rcs} file inside the repository}
+$ cd $CVSROOT/@var{dir}
+$ cp @var{old},v @var{new},v
+# @r{Remove the old file}
+$ cd ~/@var{dir}
+$ rm @var{old}
+$ cvs remove @var{old}
+$ cvs commit @var{old}
+# @r{Remove all tags from @var{new}}
+$ cvs update @var{new}
+$ cvs log @var{new} # @r{Remember the non-branch tag names}
+$ cvs tag -d @var{tag1} @var{new}
+$ cvs tag -d @var{tag2} @var{new}
address@hidden
address@hidden example
+
+By removing the tags you will be able to check out old
+revisions.
+
address@hidden
+Advantages:
+
address@hidden @bullet
address@hidden
address@hidden FIXME: Is this true about -D now that we have death
address@hidden support? See 5B.3 in the FAQ.
+Checking out old revisions works correctly, as long as
+you use @address@hidden and not @address@hidden
+to retrieve the revisions.
+
address@hidden
+The log of changes is maintained intact.
+
address@hidden
+The revision numbers are not affected.
address@hidden itemize
+
address@hidden
+Disadvantages:
+
address@hidden @bullet
address@hidden
+You cannot easily see the history of the file across the rename.
+
address@hidden itemize
+
address@hidden
---------------------------------------------------------------------
address@hidden Moving directories
address@hidden Moving and renaming directories
address@hidden Moving directories
address@hidden Renaming directories
address@hidden Directories, moving
+
+The normal way to rename or move a directory is to
+rename or move each file within it as described in
address@hidden Then check out with the @samp{-P}
+option, as described in @ref{Removing directories}.
+
+If you really want to hack the repository to rename or
+delete a directory in the repository, you can do it
+like this:
+
address@hidden
address@hidden
+Inform everyone who has a checked out copy of the directory that the
+directory will be renamed. They should commit all
+their changes, and remove their working copies,
+before you take the steps below.
+
address@hidden
+Rename the directory inside the repository.
+
address@hidden
+$ cd $CVSROOT/@var{parent-dir}
+$ mv @var{old-dir} @var{new-dir}
address@hidden example
+
address@hidden
+Fix the @sc{cvs} administrative files, if necessary (for
+instance if you renamed an entire module).
+
address@hidden
+Tell everyone that they can check out again and continue
+working.
+
address@hidden enumerate
+
+If someone had a working copy the @sc{cvs} commands will
+cease to work for him, until he removes the directory
+that disappeared inside the repository.
+
+It is almost always better to move the files in the
+directory instead of moving the directory. If you move the
+directory you are unlikely to be able to retrieve old
+releases correctly, since they probably depend on the
+name of the directories.
+
address@hidden
---------------------------------------------------------------------
address@hidden History browsing
address@hidden History browsing
address@hidden History browsing
address@hidden Traceability
address@hidden Isolation
+
+
address@hidden kind of lame, in a lot of ways the above text inside
address@hidden the @ignore motivates this chapter better
+Once you have used @sc{cvs} to store a version control
+history---what files have changed when, how, and by
+whom, there are a variety of mechanisms for looking
+through the history.
+
address@hidden FIXME: should also be talking about how you look at
address@hidden old revisions (e.g. "cvs update -p -r 1.2 foo.c").
address@hidden
+* log messages:: Log messages
+* history database:: The history database
+* user-defined logging:: User-defined logging
+* annotate:: What revision modified each line of a file?
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden log messages
address@hidden Log messages
+
address@hidden FIXME: @xref to place where we talk about how to
address@hidden specify message to commit.
+Whenever you commit a file you specify a log message.
+
address@hidden FIXME: bring the information here, and get rid of or
address@hidden greatly shrink the "log" node.
+To look through the log messages which have been
+specified for every revision which has been committed,
+use the @code{cvs log} command (@pxref{log}).
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden history database
address@hidden The history database
+
address@hidden FIXME: bring the information from the history file
address@hidden and history nodes here. Rewrite it to be motivated
address@hidden better (start out by clearly explaining what gets
address@hidden logged in history, for example).
+You can use the history file (@pxref{history file}) to
+log various @sc{cvs} actions. To retrieve the
+information from the history file, use the @code{cvs
+history} command (@pxref{history}).
+
+Note: you can control what is logged to this file by using the
address@hidden keyword in the @file{CVSROOT/config} file
+(@pxref{config}).
+
address@hidden
address@hidden The history database has many problems:
address@hidden * It is very unclear what field means what. This
address@hidden could be improved greatly by better documentation,
address@hidden but there are still non-orthogonalities (for
address@hidden example, tag does not record the "repository"
address@hidden field but most records do).
address@hidden * Confusion about files, directories, and modules.
address@hidden Some commands record one, some record others.
address@hidden * File removal is not logged. There is an 'R'
address@hidden record type documented, but CVS never uses it.
address@hidden * Tags are only logged for the "cvs rtag" command,
address@hidden not "cvs tag". The fix for this is not completely
address@hidden clear (see above about modules vs. files).
address@hidden * Are there other cases of operations that are not
address@hidden logged? One would hope for all changes to the
address@hidden repository to be logged somehow (particularly
address@hidden operations like tagging, "cvs admin -k", and other
address@hidden operations which do not record a history that one
address@hidden can get with "cvs log"). Operations on the working
address@hidden directory, like export, get, and release, are a
address@hidden second category also covered by the current "cvs
address@hidden history".
address@hidden * The history file does not record the options given
address@hidden to a command. The most serious manifestation of
address@hidden this is perhaps that it doesn't record whether a command
address@hidden was recursive. It is not clear to me whether one
address@hidden wants to log at a level very close to the command
address@hidden line, as a sort of way of logging each command
address@hidden (more or less), or whether one wants
address@hidden to log more at the level of what was changed (or
address@hidden something in between), but either way the current
address@hidden information has pretty big gaps.
address@hidden * Further details about a tag--like whether it is a
address@hidden branch tag or, if a non-branch tag, which branch it
address@hidden is on. One can find out this information about the
address@hidden tag as it exists _now_, but if the tag has been
address@hidden moved, one doesn't know what it was like at the time
address@hidden the history record was written.
address@hidden * Whether operating on a particular tag, date, or
address@hidden options was implicit (sticky) or explicit.
address@hidden
address@hidden Another item, only somewhat related to the above, is a
address@hidden way to control what is logged in the history file.
address@hidden This is probably the only good way to handle
address@hidden different people having different ideas about
address@hidden information/space tradeoffs.
address@hidden
address@hidden It isn't really clear that it makes sense to try to
address@hidden patch up the history file format as it exists now to
address@hidden include all that stuff. It might be better to
address@hidden design a whole new CVSROOT/nhistory file and "cvs
address@hidden nhistory" command, or some such, or in some other
address@hidden way trying to come up with a clean break from the
address@hidden past, which can address the above concerns. Another
address@hidden open question is how/whether this relates to
address@hidden taginfo/loginfo/etc.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden user-defined logging
address@hidden User-defined logging
+
address@hidden FIXME: should probably also mention the fact the -l
address@hidden global option can disable most of the mechanisms
address@hidden discussed here (why? What is the -l global option for?).
address@hidden
address@hidden FIXME: probably should centralize this information
address@hidden here, at least to some extent. Maybe by moving the
address@hidden loginfo, etc., nodes here and replacing
address@hidden the "user-defined logging" node with one node for
address@hidden each method.
+You can customize @sc{cvs} to log various kinds of
+actions, in whatever manner you choose. These
+mechanisms operate by executing a script at various
+times. The script might append a message to a file
+listing the information and the programmer who created
+it, or send mail to a group of developers, or, perhaps,
+post a message to a particular newsgroup. To log
+commits, use the @file{loginfo} file (@pxref{loginfo}).
address@hidden FIXME: What is difference between doing it in the
address@hidden modules file and using loginfo/taginfo? Why should
address@hidden user use one or the other?
+To log commits, checkouts, exports, and tags,
+respectively, you can also use the @samp{-i},
address@hidden, @samp{-e}, and @samp{-t} options in the
+modules file. For a more flexible way of giving
+notifications to various users, which requires less in
+the way of keeping centralized scripts up to date, use
+the @code{cvs watch add} command (@pxref{Getting
+Notified}); this command is useful even if you are not
+using @code{cvs watch on}.
+
address@hidden taginfo
address@hidden Exit status, of taginfo
+The @file{taginfo} file defines programs to execute
+when someone executes a @code{tag} or @code{rtag}
+command. The @file{taginfo} file has the standard form
+for administrative files (@pxref{Administrative
+files}), where each line is a regular expression
+followed by a command to execute. The arguments passed
+to the command are, in order, the @var{tagname},
address@hidden (@code{add} for @code{tag},
address@hidden for @code{tag -F}, and @code{del} for
address@hidden -d}), @var{repository}, and any remaining are
+pairs of @var{filename} @var{revision}. A non-zero
+exit of the filter program will cause the tag to be
+aborted.
+
+Here is an example of using taginfo to log tag and rtag
+commands. In the taginfo file put:
+
address@hidden
+ALL /usr/local/cvsroot/CVSROOT/loggit
address@hidden example
+
address@hidden
+Where @file{/usr/local/cvsroot/CVSROOT/loggit} contains the
+following script:
+
address@hidden
+#!/bin/sh
+echo "$@@" >>/home/kingdon/cvsroot/CVSROOT/taglog
address@hidden example
+
address@hidden annotate
address@hidden Annotate command
address@hidden annotate (subcommand)
+
address@hidden Command {cvs annotate} address@hidden address@hidden
rev}|@code{-D date}] files @dots{}
+
+For each file in @var{files}, print the head revision
+of the trunk, together with information on the last
+modification for each line. For example:
+
address@hidden
+$ cvs annotate ssfile
+Annotations for ssfile
+***************
+1.1 (mary 27-Mar-96): ssfile line 1
+1.2 (joe 28-Mar-96): ssfile line 2
address@hidden example
+
+The file @file{ssfile} currently contains two lines.
+The @code{ssfile line 1} line was checked in by
address@hidden on March 27. Then, on March 28, @code{joe}
+added a line @code{ssfile line 2}, without modifying
+the @code{ssfile line 1} line. This report doesn't
+tell you anything about lines which have been deleted
+or replaced; you need to use @code{cvs diff} for that
+(@pxref{diff}).
+
address@hidden deffn
+
+The options to @code{cvs annotate} are listed in
address@hidden CVS}, and can be used to select the files
+and revisions to annotate. The options are described
+in more detail there and in @ref{Common options}.
+
address@hidden FIXME: maybe an example using the options? Just
address@hidden what it means to select a revision might be worth a
address@hidden few words of explanation ("you want to see who
address@hidden changed this line *before* 1.4"...).
+
address@hidden
---------------------------------------------------------------------
address@hidden Binary files
address@hidden Handling binary files
address@hidden Binary files
+
+The most common use for @sc{cvs} is to store text
+files. With text files, @sc{cvs} can merge revisions,
+display the differences between revisions in a
+human-visible fashion, and other such operations.
+However, if you are willing to give up a few of these
+abilities, @sc{cvs} can store binary files. For
+example, one might store a web site in @sc{cvs}
+including both text files and binary images.
+
address@hidden
+* Binary why:: More details on issues with binary files
+* Binary howto:: How to store them
address@hidden menu
+
address@hidden Binary why
address@hidden The issues with binary files
+
+While the need to manage binary files may seem obvious
+if the files that you customarily work with are binary,
+putting them into version control does present some
+additional issues.
+
+One basic function of version control is to show the
+differences between two revisions. For example, if
+someone else checked in a new version of a file, you
+may wish to look at what they changed and determine
+whether their changes are good. For text files,
address@hidden provides this functionality via the @code{cvs
+diff} command. For binary files, it may be possible to
+extract the two revisions and then compare them with a
+tool external to @sc{cvs} (for example, word processing
+software often has such a feature). If there is no
+such tool, one must track changes via other mechanisms,
+such as urging people to write good log messages, and
+hoping that the changes they actually made were the
+changes that they intended to make.
+
+Another ability of a version control system is the
+ability to merge two revisions. For @sc{cvs} this
+happens in two contexts. The first is when users make
+changes in separate working directories
+(@pxref{Multiple developers}). The second is when one
+merges explicitly with the @samp{update -j} command
+(@pxref{Branching and merging}).
+
+In the case of text
+files, @sc{cvs} can merge changes made independently,
+and signal a conflict if the changes conflict. With
+binary files, the best that @sc{cvs} can do is present
+the two different copies of the file, and leave it to
+the user to resolve the conflict. The user may choose
+one copy or the other, or may run an external merge
+tool which knows about that particular file format, if
+one exists.
+Note that having the user merge relies primarily on the
+user to not accidentally omit some changes, and thus is
+potentially error prone.
+
+If this process is thought to be undesirable, the best
+choice may be to avoid merging. To avoid the merges
+that result from separate working directories, see the
+discussion of reserved checkouts (file locking) in
address@hidden developers}. To avoid the merges
+resulting from branches, restrict use of branches.
+
address@hidden Binary howto
address@hidden How to store binary files
+
+There are two issues with using @sc{cvs} to store
+binary files. The first is that @sc{cvs} by default
+converts line endings between the canonical form in
+which they are stored in the repository (linefeed
+only), and the form appropriate to the operating system
+in use on the client (for example, carriage return
+followed by line feed for Windows NT).
+
+The second is that a binary file might happen to
+contain data which looks like a keyword (@pxref{Keyword
+substitution}), so keyword expansion must be turned
+off.
+
address@hidden FIXME: the third is that one can't do merges with
address@hidden binary files. xref to Multiple Developers and the
address@hidden reserved checkout issues.
+
+The @samp{-kb} option available with some @sc{cvs}
+commands insures that neither line ending conversion
+nor keyword expansion will be done.
+
+Here is an example of how you can create a new file
+using the @samp{-kb} flag:
+
address@hidden
+$ echo '$ Id$' > kotest
+$ cvs add -kb -m"A test file" kotest
+$ cvs ci -m"First checkin; contains a keyword" kotest
address@hidden example
+
+If a file accidentally gets added without @samp{-kb},
+one can use the @code{cvs admin} command to recover.
+For example:
+
address@hidden
+$ echo '$ Id$' > kotest
+$ cvs add -m"A test file" kotest
+$ cvs ci -m"First checkin; contains a keyword" kotest
+$ cvs admin -kb kotest
+$ cvs update -A kotest
+# @r{For non-unix systems:}
+# @r{Copy in a good copy of the file from outside CVS}
+$ cvs commit -m "make it binary" kotest
address@hidden example
+
address@hidden Trying to describe this for both unix and non-unix
address@hidden in the same description is very confusing. Might
address@hidden want to split the two, or just ditch the unix "shortcut"
address@hidden (unixheads don't do much with binary files, anyway).
address@hidden This used to say "(Try the above example, and do a
address@hidden @code{cat kotest} after every command)". But that
address@hidden only really makes sense for the unix case.
+When you check in the file @file{kotest} the file is
+not preserved as a binary file, because you did not
+check it in as a binary file. The @code{cvs
+admin -kb} command sets the default keyword
+substitution method for this file, but it does not
+alter the working copy of the file that you have. If you need to
+cope with line endings (that is, you are using
address@hidden on a non-unix system), then you need to
+check in a new copy of the file, as shown by the
address@hidden commit} command above.
+On unix, the @code{cvs update -A} command suffices.
address@hidden FIXME: should also describe what the *other users*
address@hidden need to do, if they have checked out copies which
address@hidden have been corrupted by lack of -kb. I think maybe
address@hidden "cvs update -kb" or "cvs
address@hidden update -A" would suffice, although the user who
address@hidden reported this suggested removing the file, manually
address@hidden removing it from CVS/Entries, and then "cvs update"
+(Note that you can use @code{cvs log} to determine the default keyword
+substitution method for a file and @code{cvs status} to determine
+the keyword substitution method for a working copy.)
+
+However, in using @code{cvs admin -k} to change the
+keyword expansion, be aware that the keyword expansion
+mode is not version controlled. This means that, for
+example, that if you have a text file in old releases,
+and a binary file with the same name in new releases,
address@hidden provides no way to check out the file in text
+or binary mode depending on what version you are
+checking out. There is no good workaround for this
+problem.
+
+You can also set a default for whether @code{cvs add}
+and @code{cvs import} treat a file as binary based on
+its name; for example you could say that files who
+names end in @samp{.exe} are binary. @xref{Wrappers}.
+There is currently no way to have @sc{cvs} detect
+whether a file is binary based on its contents. The
+main difficulty with designing such a feature is that
+it is not clear how to distinguish between binary and
+non-binary files, and the rules to apply would vary
+considerably with the operating system.
address@hidden For example, it would be good on MS-DOS-family OSes
address@hidden for anything containing ^Z to be binary. Having
address@hidden characters with the 8th bit set imply binary is almost
address@hidden surely a bad idea in the context of ISO-8859-* and
address@hidden other such character sets. On VMS or the Mac, we
address@hidden could use the OS's file typing. This is a
address@hidden commonly-desired feature, and something of this sort
address@hidden may make sense. But there are a lot of pitfalls here.
address@hidden
address@hidden Another, probably better, way to tell is to read the
address@hidden file in text mode, write it to a temp file in text
address@hidden mode, and then do a binary mode compare of the two
address@hidden files. If they differ, it is a binary file. This
address@hidden might have problems on VMS (or some other system
address@hidden with several different text modes), but in general
address@hidden should be relatively portable. The only other
address@hidden downside I can think of is that it would be fairly
address@hidden slow, but that is perhaps a small price to pay for
address@hidden not having your files corrupted. Another issue is
address@hidden what happens if you import a text file with bare
address@hidden linefeeds on Windows. Such files will show up on
address@hidden Windows sometimes (I think some native windows
address@hidden programs even write them, on occasion). Perhaps it
address@hidden is reasonable to treat such files as binary; after
address@hidden all it is something of a presumption to assume that
address@hidden the user would want the linefeeds converted to CRLF.
+
address@hidden
---------------------------------------------------------------------
address@hidden Multiple developers
address@hidden Multiple developers
address@hidden Multiple developers
address@hidden Team of developers
address@hidden File locking
address@hidden Locking files
address@hidden Working copy
address@hidden Reserved checkouts
address@hidden Unreserved checkouts
address@hidden RCS-style locking
+
+When more than one person works on a software project
+things often get complicated. Often, two people try to
+edit the same file simultaneously. One solution, known
+as @dfn{file locking} or @dfn{reserved checkouts}, is
+to allow only one person to edit each file at a time.
+This is the only solution with some version control
+systems, including @sc{rcs} and @sc{sccs}. Currently
+the usual way to get reserved checkouts with @sc{cvs}
+is the @code{cvs admin -l} command (@pxref{admin
+options}). This is not as nicely integrated into
address@hidden as the watch features, described below, but it
+seems that most people with a need for reserved
+checkouts find it adequate.
address@hidden Or "find it better than worrying about implementing
address@hidden nicely integrated reserved checkouts" or ...?
+It also may be possible to use the watches
+features described below, together with suitable
+procedures (not enforced by software), to avoid having
+two people edit at the same time.
+
address@hidden Our unreserved checkout model might not
address@hidden be quite the same as others. For example, I
address@hidden think that some systems will tend to create a branch
address@hidden in the case where CVS prints "up-to-date check failed".
address@hidden It isn't clear to me whether we should try to
address@hidden explore these subtleties; it could easily just
address@hidden confuse people.
+The default model with @sc{cvs} is known as
address@hidden checkouts}. In this model, developers
+can edit their own @dfn{working copy} of a file
+simultaneously. The first person that commits his
+changes has no automatic way of knowing that another
+has started to edit it. Others will get an error
+message when they try to commit the file. They must
+then use @sc{cvs} commands to bring their working copy
+up to date with the repository revision. This process
+is almost automatic.
+
address@hidden FIXME? should probably use the word "watch" here, to
address@hidden tie this into the text below and above.
address@hidden also supports mechanisms which facilitate
+various kinds of communication, without actually
+enforcing rules like reserved checkouts do.
+
+The rest of this chapter describes how these various
+models work, and some of the issues involved in
+choosing between them.
+
+
address@hidden
+* File status:: A file can be in several states
+* Updating a file:: Bringing a file up-to-date
+* Conflicts example:: An informative example
+* Informing others:: To cooperate you must inform
+* Concurrency:: Simultaneous repository access
+* Watches:: Mechanisms to track who is editing files
+* Choosing a model:: Reserved or unreserved checkouts?
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden File status
address@hidden File status
address@hidden File status
address@hidden Status of a file
+
address@hidden Shouldn't this start with an example or something,
address@hidden introducing the unreserved checkout model? Before we
address@hidden dive into listing states?
+Based on what operations you have performed on a
+checked out file, and what operations others have
+performed to that file in the repository, one can
+classify a file in a number of states. The states, as
+reported by the @code{status} command, are:
+
address@hidden The order of items is chosen to group logically
address@hidden similar outputs together.
address@hidden People who want alphabetical can use the index...
address@hidden @asis
address@hidden Up-to-date
address@hidden Up-to-date
+The file is identical with the latest revision in the
+repository for the branch in use.
address@hidden FIXME: should we clarify "in use"? The answer is
address@hidden sticky tags, and trying to distinguish branch sticky
address@hidden tags from non-branch sticky tags seems rather awkward
address@hidden here.
address@hidden FIXME: What happens with non-branch sticky tags? Is
address@hidden a stuck file "Up-to-date" or "Needs checkout" or what?
+
address@hidden Locally Modified
address@hidden Locally Modified
+You have edited the file, and not yet committed your changes.
+
address@hidden Locally Added
address@hidden Locally Added
+You have added the file with @code{add}, and not yet
+committed your changes.
address@hidden There are many cases involving the file being
address@hidden added/removed/modified in the working directory, and
address@hidden added/removed/modified in the repository, which we
address@hidden don't try to describe here. I'm not sure that "cvs
address@hidden status" produces a non-confusing output in most of
address@hidden those cases.
+
address@hidden Locally Removed
address@hidden Locally Removed
+You have removed the file with @code{remove}, and not yet
+committed your changes.
+
address@hidden Needs Checkout
address@hidden Needs Checkout
+Someone else has committed a newer revision to the
+repository. The name is slightly misleading; you will
+ordinarily use @code{update} rather than
address@hidden to get that newer revision.
+
address@hidden Needs Patch
address@hidden Needs Patch
address@hidden See also newb-123j0 in sanity.sh (although that case
address@hidden should probably be changed rather than documented).
+Like Needs Checkout, but the @sc{cvs} server will send
+a patch rather than the entire file. Sending a patch or
+sending an entire file accomplishes the same thing.
+
address@hidden Needs Merge
address@hidden Needs Merge
+Someone else has committed a newer revision to the repository, and you
+have also made modifications to the file.
+
address@hidden Unresolved Conflict
address@hidden Unresolved Conflict
address@hidden FIXCVS - This file status needs to be changed to some more
informative
address@hidden text that distinguishes it more clearly from each of the Locally
Added,
address@hidden File had conflicts on merge, and Unknown status types, but an
exact and
address@hidden succinct wording escapes me at the moment.
+A file with the same name as this new file has been added to the repository
+from a second workspace. This file will need to be moved out of the way
+to allow an @code{update} to complete.
+
address@hidden File had conflicts on merge
address@hidden File had conflicts on merge
address@hidden is it worth saying that this message was "Unresolved
address@hidden Conflict" in CVS 1.9 and earlier? I'm inclined to
address@hidden think that is unnecessarily confusing to new users.
+This is like Locally Modified, except that a previous
address@hidden command gave a conflict. If you have not
+already done so, you need to
+resolve the conflict as described in @ref{Conflicts example}.
+
address@hidden Unknown
address@hidden Unknown
address@hidden doesn't know anything about this file. For
+example, you have created a new file and have not run
address@hidden
address@hidden
address@hidden "Entry Invalid" and "Classify Error" are also in the
address@hidden status.c. The latter definitely indicates a CVS bug
address@hidden (should it be worded more like "internal error" so
address@hidden people submit bug reports if they see it?). The former
address@hidden I'm not as sure; I haven't tracked down whether/when it
address@hidden appears in "cvs status" output.
+
address@hidden table
+
+To help clarify the file status, @code{status} also
+reports the @code{Working revision} which is the
+revision that the file in the working directory derives
+from, and the @code{Repository revision} which is the
+latest revision in the repository for the branch in
+use.
address@hidden FIXME: should we clarify "in use"? The answer is
address@hidden sticky tags, and trying to distinguish branch sticky
address@hidden tags from non-branch sticky tags seems rather awkward
address@hidden here.
address@hidden FIXME: What happens with non-branch sticky tags?
address@hidden What is the Repository Revision there? See the
address@hidden comment at vn_rcs in cvs.h, which is kind of
address@hidden confused--we really need to document better what this
address@hidden field contains.
address@hidden Q: Should we document "New file!" and other such
address@hidden outputs or are they self-explanatory?
address@hidden FIXME: what about the date to the right of "Working
address@hidden revision"? It doesn't appear with client/server and
address@hidden seems unnecessary (redundant with "ls -l") so
address@hidden perhaps it should be removed for non-client/server too?
address@hidden FIXME: Need some examples.
address@hidden FIXME: Working revision can also be something like
address@hidden "-1.3" for a locally removed file. Not at all
address@hidden self-explanatory (and it is possible that CVS should
address@hidden be changed rather than documenting this).
+
address@hidden Would be nice to have an @example showing output
address@hidden from cvs status, with comments showing the xref
address@hidden where each part of the output is described. This
address@hidden might fit in nicely if it is desirable to split this
address@hidden node in two; one to introduce "cvs status" and one
address@hidden to list each of the states.
+The options to @code{status} are listed in
address@hidden CVS}. For information on its @code{Sticky tag}
+and @code{Sticky date} output, see @ref{Sticky tags}.
+For information on its @code{Sticky options} output,
+see the @samp{-k} option in @ref{update options}.
+
+You can think of the @code{status} and @code{update}
+commands as somewhat complementary. You use
address@hidden to bring your files up to date, and you
+can use @code{status} to give you some idea of what an
address@hidden would do (of course, the state of the
+repository might change before you actually run
address@hidden). In fact, if you want a command to
+display file status in a more brief format than is
+displayed by the @code{status} command, you can invoke
+
address@hidden update, to display file status
address@hidden
+$ cvs -n -q update
address@hidden example
+
+The @samp{-n} option means to not actually do the
+update, but merely to display statuses; the @samp{-q}
+option avoids printing the name of each directory. For
+more information on the @code{update} command, and
+these options, see @ref{Invoking CVS}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Updating a file
address@hidden Bringing a file up to date
address@hidden Bringing a file up to date
address@hidden Updating a file
address@hidden Merging a file
address@hidden Update, introduction
+
+When you want to update or merge a file, use the @code{update}
+command. For files that are not up to date this is roughly equivalent
+to a @code{checkout} command: the newest revision of the file is
+extracted from the repository and put in your working directory.
+
+Your modifications to a file are never lost when you
+use @code{update}. If no newer revision exists,
+running @code{update} has no effect. If you have
+edited the file, and a newer revision is available,
address@hidden will merge all changes into your working copy.
+
+For instance, imagine that you checked out revision 1.4 and started
+editing it. In the meantime someone else committed revision 1.5, and
+shortly after that revision 1.6. If you run @code{update} on the file
+now, @sc{cvs} will incorporate all changes between revision 1.4 and 1.6 into
+your file.
+
address@hidden Overlap
+If any of the changes between 1.4 and 1.6 were made too
+close to any of the changes you have made, an
address@hidden occurs. In such cases a warning is
+printed, and the resulting file includes both
+versions of the lines that overlap, delimited by
+special markers.
address@hidden, for a complete description of the
address@hidden command.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Conflicts example
address@hidden Conflicts example
address@hidden Merge, an example
address@hidden Example of merge
address@hidden driver.c (merge example)
+
+Suppose revision 1.4 of @file{driver.c} contains this:
+
address@hidden
+#include <stdio.h>
+
+void main()
address@hidden
+ parse();
+ if (nerr == 0)
+ gencode();
+ else
+ fprintf(stderr, "No code generated.\n");
+ exit(nerr == 0 ? 0 : 1);
address@hidden
address@hidden example
+
address@hidden
+Revision 1.6 of @file{driver.c} contains this:
+
address@hidden
+#include <stdio.h>
+
+int main(int argc,
+ char **argv)
address@hidden
+ parse();
+ if (argc != 1)
+ @{
+ fprintf(stderr, "tc: No args expected.\n");
+ exit(1);
+ @}
+ if (nerr == 0)
+ gencode();
+ else
+ fprintf(stderr, "No code generated.\n");
+ exit(!!nerr);
address@hidden
address@hidden example
+
address@hidden
+Your working copy of @file{driver.c}, based on revision
+1.4, contains this before you run @samp{cvs update}:
address@hidden -- Really include "cvs"?
+
address@hidden
+#include <stdlib.h>
+#include <stdio.h>
+
+void main()
address@hidden
+ init_scanner();
+ parse();
+ if (nerr == 0)
+ gencode();
+ else
+ fprintf(stderr, "No code generated.\n");
+ exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
address@hidden
address@hidden example
+
address@hidden
+You run @samp{cvs update}:
address@hidden -- Really include "cvs"?
+
address@hidden
+$ cvs update driver.c
+RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v
+retrieving revision 1.4
+retrieving revision 1.6
+Merging differences between 1.4 and 1.6 into driver.c
+rcsmerge warning: overlaps during merge
+cvs update: conflicts found in driver.c
+C driver.c
address@hidden example
+
address@hidden
address@hidden Conflicts (merge example)
address@hidden tells you that there were some conflicts.
+Your original working file is saved unmodified in
address@hidden The new version of
address@hidden contains this:
+
address@hidden
+#include <stdlib.h>
+#include <stdio.h>
+
+int main(int argc,
+ char **argv)
address@hidden
+ init_scanner();
+ parse();
+ if (argc != 1)
+ @{
+ fprintf(stderr, "tc: No args expected.\n");
+ exit(1);
+ @}
+ if (nerr == 0)
+ gencode();
+ else
+ fprintf(stderr, "No code generated.\n");
address@hidden<<<<<<< driver.c
+ exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
address@hidden
+ exit(!!nerr);
address@hidden>>>>>>> 1.6
address@hidden
address@hidden example
+
address@hidden
address@hidden Markers, conflict
address@hidden Conflict markers
address@hidden <<<<<<<
address@hidden >>>>>>>
address@hidden =======
+
+Note how all non-overlapping modifications are incorporated in your working
+copy, and that the overlapping section is clearly marked with
address@hidden<<<<<<<}, @samp{=======} and @samp{>>>>>>>}.
+
address@hidden Resolving a conflict
address@hidden Conflict resolution
+You resolve the conflict by editing the file, removing the markers and
+the erroneous line. Suppose you end up with this file:
address@hidden -- Add xref to the pcl-cvs manual when it talks
address@hidden -- about this.
address@hidden
+#include <stdlib.h>
+#include <stdio.h>
+
+int main(int argc,
+ char **argv)
address@hidden
+ init_scanner();
+ parse();
+ if (argc != 1)
+ @{
+ fprintf(stderr, "tc: No args expected.\n");
+ exit(1);
+ @}
+ if (nerr == 0)
+ gencode();
+ else
+ fprintf(stderr, "No code generated.\n");
+ exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
address@hidden
address@hidden example
+
address@hidden
+You can now go ahead and commit this as revision 1.7.
+
address@hidden
+$ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c
+Checking in driver.c;
+/usr/local/cvsroot/yoyodyne/tc/driver.c,v <-- driver.c
+new revision: 1.7; previous revision: 1.6
+done
address@hidden example
+
+For your protection, @sc{cvs} will refuse to check in a
+file if a conflict occurred and you have not resolved
+the conflict. Currently to resolve a conflict, you
+must change the timestamp on the file. In previous
+versions of @sc{cvs}, you also needed to
+insure that the file contains no conflict markers.
+Because
+your file may legitimately contain conflict markers (that
+is, occurrences of @samp{>>>>>>> } at the start of a
+line that don't mark a conflict), the current
+version of @sc{cvs} will print a warning and proceed to
+check in the file.
address@hidden The old behavior was really icky; the only way out
address@hidden was to start hacking on
address@hidden the @code{CVS/Entries} file or other such workarounds.
address@hidden
address@hidden If the timestamp thing isn't considered nice enough,
address@hidden maybe there should be a "cvs resolved" command
address@hidden which clears the conflict indication. For a nice user
address@hidden interface, this should be invoked by an interactive
address@hidden merge tool like emerge rather than by the user
address@hidden directly--such a tool can verify that the user has
address@hidden really dealt with each conflict.
+
address@hidden emerge
+If you use release 1.04 or later of pcl-cvs (a @sc{gnu}
+Emacs front-end for @sc{cvs}) you can use an Emacs
+package called emerge to help you resolve conflicts.
+See the documentation for pcl-cvs.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Informing others
address@hidden Informing others about commits
address@hidden Informing others
address@hidden Spreading information
address@hidden Mail, automatic mail on commit
+
+It is often useful to inform others when you commit a
+new revision of a file. The @samp{-i} option of the
address@hidden file, or the @file{loginfo} file, can be
+used to automate this process. @xref{modules}.
address@hidden You can use these features of @sc{cvs}
+to, for instance, instruct @sc{cvs} to mail a
+message to all developers, or post a message to a local
+newsgroup.
address@hidden -- More text would be nice here.
+
address@hidden Concurrency
address@hidden Several developers simultaneously attempting to run CVS
+
address@hidden Locks, cvs, introduction
address@hidden For a discussion of *why* CVS creates locks, see
address@hidden the comment at the start of src/lock.c
+If several developers try to run @sc{cvs} at the same
+time, one may get the following message:
+
address@hidden
+[11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo
address@hidden example
+
address@hidden #cvs.rfl, removing
address@hidden #cvs.wfl, removing
address@hidden #cvs.lock, removing
address@hidden will try again every 30 seconds, and either
+continue with the operation or print the message again,
+if it still needs to wait. If a lock seems to stick
+around for an undue amount of time, find the person
+holding the lock and ask them about the cvs command
+they are running. If they aren't running a cvs
+command, look in the repository directory mentioned in
+the message and remove files which they own whose names
+start with @file{#cvs.rfl},
address@hidden, or @file{#cvs.lock}.
+
+Note that these locks are to protect @sc{cvs}'s
+internal data structures and have no relationship to
+the word @dfn{lock} in the sense used by
address@hidden refers to reserved checkouts
+(@pxref{Multiple developers}).
+
+Any number of people can be reading from a given
+repository at a time; only when someone is writing do
+the locks prevent other people from reading or writing.
+
address@hidden Atomic transactions, lack of
address@hidden Transactions, atomic, lack of
address@hidden the following talks about what one might call commit/update
address@hidden atomicity.
address@hidden Probably also should say something about
address@hidden commit/commit atomicity, that is, "An update will
address@hidden not get partial versions of more than one commit".
address@hidden CVS currently has this property and I guess we can
address@hidden make it a documented feature.
address@hidden For example one person commits
address@hidden a/one.c and b/four.c and another commits a/two.c and
address@hidden b/three.c. Then an update cannot get the new a/one.c
address@hidden and a/two.c and the old b/four.c and b/three.c.
+One might hope for the following property:
+
address@hidden
+If someone commits some changes in one cvs command,
+then an update by someone else will either get all the
+changes, or none of them.
address@hidden quotation
+
address@hidden
+but @sc{cvs} does @emph{not} have this property. For
+example, given the files
+
address@hidden
+a/one.c
+a/two.c
+b/three.c
+b/four.c
address@hidden example
+
address@hidden
+if someone runs
+
address@hidden
+cvs ci a/two.c b/three.c
address@hidden example
+
address@hidden
+and someone else runs @code{cvs update} at the same
+time, the person running @code{update} might get only
+the change to @file{b/three.c} and not the change to
address@hidden/two.c}.
+
address@hidden Watches
address@hidden Mechanisms to track who is editing files
address@hidden Watches
+
+For many groups, use of @sc{cvs} in its default mode is
+perfectly satisfactory. Users may sometimes go to
+check in a modification only to find that another
+modification has intervened, but they deal with it and
+proceed with their check in. Other groups prefer to be
+able to know who is editing what files, so that if two
+people try to edit the same file they can choose to
+talk about who is doing what when rather than be
+surprised at check in time. The features in this
+section allow such coordination, while retaining the
+ability of two developers to edit the same file at the
+same time.
+
address@hidden Some people might ask why CVS does not enforce the
address@hidden rule on chmod, by requiring a cvs edit before a cvs
address@hidden commit. The main reason is that it could always be
address@hidden circumvented--one could edit the file, and
address@hidden then when ready to check it in, do the cvs edit and put
address@hidden in the new contents and do the cvs commit. One
address@hidden implementation note: if we _do_ want to have cvs commit
address@hidden require a cvs edit, we should store the state on
address@hidden whether the cvs edit has occurred in the working
address@hidden directory, rather than having the server try to keep
address@hidden track of what working directories exist.
address@hidden FIXME: should the above discussion be part of the
address@hidden manual proper, somewhere, not just in a comment?
+For maximum benefit developers should use @code{cvs
+edit} (not @code{chmod}) to make files read-write to
+edit them, and @code{cvs release} (not @code{rm}) to
+discard a working directory which is no longer in use,
+but @sc{cvs} is not able to enforce this behavior.
+
address@hidden I'm a little dissatisfied with this presentation,
address@hidden because "watch on"/"edit"/"editors" are one set of
address@hidden functionality, and "watch add"/"watchers" is another
address@hidden which is somewhat orthogonal even though they interact in
address@hidden various ways. But I think it might be
address@hidden confusing to describe them separately (e.g. "watch
address@hidden add" with loginfo). I don't know.
+
address@hidden
+* Setting a watch:: Telling CVS to watch certain files
+* Getting Notified:: Telling CVS to notify you
+* Editing files:: How to edit a file which is being watched
+* Watch information:: Information about who is watching and editing
+* Watches Compatibility:: Watches interact poorly with CVS 1.6 or earlier
address@hidden menu
+
address@hidden Setting a watch
address@hidden Telling CVS to watch certain files
+
+To enable the watch features, you first specify that
+certain files are to be watched.
+
address@hidden watch on (subcommand)
address@hidden Command {cvs watch on} address@hidden address@hidden@dots{}
+
address@hidden Read-only files, and watches
+Specify that developers should run @code{cvs edit}
+before editing @var{files}. @sc{cvs} will create working
+copies of @var{files} read-only, to remind developers
+to run the @code{cvs edit} command before working on
+them.
+
+If @var{files} includes the name of a directory, @sc{cvs}
+arranges to watch all files added to the corresponding
+repository directory, and sets a default for files
+added in the future; this allows the user to set
+notification policies on a per-directory basis. The
+contents of the directory are processed recursively,
+unless the @code{-l} option is given.
+The @code{-R} option can be used to force recursion if the @code{-l}
+option is set in @file{~/.cvsrc} (@pxref{~/.cvsrc}).
+
+If @var{files} is omitted, it defaults to the current directory.
+
address@hidden watch off (subcommand)
address@hidden deffn
+
address@hidden Command {cvs watch off} address@hidden address@hidden@dots{}
+
+Do not create @var{files} read-only on checkout; thus,
+developers will not be reminded to use @code{cvs edit}
+and @code{cvs unedit}.
+
+The @var{files} and options are processed as for @code{cvs
+watch on}.
+
address@hidden deffn
+
address@hidden Getting Notified
address@hidden Telling CVS to notify you
+
+You can tell @sc{cvs} that you want to receive
+notifications about various actions taken on a file.
+You can do this without using @code{cvs watch on} for
+the file, but generally you will want to use @code{cvs
+watch on}, to remind developers to use the @code{cvs edit}
+command.
+
address@hidden watch add (subcommand)
address@hidden Command {cvs watch add} address@hidden address@hidden
@address@hidden address@hidden@dots{}
+
+Add the current user to the list of people to receive notification of
+work done on @var{files}.
+
+The @code{-a} option specifies what kinds of events @sc{cvs} should notify
+the user about. @var{action} is one of the following:
+
address@hidden @code
+
address@hidden edit
+Another user has applied the @code{cvs edit} command (described
+below) to a watched file.
+
address@hidden commit
+Another user has committed changes to one of the named @var{files}.
+
address@hidden unedit
+Another user has abandoned editing a file (other than by committing changes).
+They can do this in several ways, by:
+
address@hidden @bullet
+
address@hidden
+applying the @code{cvs unedit} command (described below) to the file
+
address@hidden
+applying the @code{cvs release} command (@pxref{release}) to the file's parent
directory
+(or recursively to a directory more than one level up)
+
address@hidden
+deleting the file and allowing @code{cvs update} to recreate it
+
address@hidden itemize
+
address@hidden all
+All of the above.
+
address@hidden none
+None of the above. (This is useful with @code{cvs edit},
+described below.)
+
address@hidden table
+
+The @code{-a} option may appear more than once, or not at all. If
+omitted, the action defaults to @code{all}.
+
+The @var{files} and options are processed as for
address@hidden watch on}.
+
address@hidden deffn
+
+
address@hidden watch remove (subcommand)
address@hidden Command {cvs watch remove} address@hidden address@hidden
@address@hidden address@hidden@dots{}
+
+Remove a notification request established using @code{cvs watch add};
+the arguments are the same. If the @code{-a} option is present, only
+watches for the specified actions are removed.
+
address@hidden deffn
+
address@hidden notify (admin file)
+When the conditions exist for notification, @sc{cvs}
+calls the @file{notify} administrative file. Edit
address@hidden as one edits the other administrative
+files (@pxref{Intro administrative files}). This
+file follows the usual conventions for administrative
+files (@pxref{syntax}), where each line is a regular
+expression followed by a command to execute. The
+command should contain a single occurrence of @samp{%s}
+which will be replaced by the user to notify; the rest
+of the information regarding the notification will be
+supplied to the command on standard input. The
+standard thing to put in the @code{notify} file is the
+single line:
+
address@hidden
+ALL mail %s -s "CVS notification"
address@hidden example
+
address@hidden
+This causes users to be notified by electronic mail.
address@hidden FIXME: should it be this hard to set up this
address@hidden behavior (and the result when one fails to do so,
address@hidden silent failure to notify, so non-obvious)? Should
address@hidden CVS give a warning if no line in notify matches (and
address@hidden document the use of "DEFAULT :" for the case where
address@hidden skipping the notification is indeed desired)?
+
address@hidden users (admin file)
+Note that if you set this up in the straightforward
+way, users receive notifications on the server machine.
+One could of course write a @file{notify} script which
+directed notifications elsewhere, but to make this
+easy, @sc{cvs} allows you to associate a notification
+address for each user. To do so create a file
address@hidden in @file{CVSROOT} with a line for each
+user in the format @var{user}:@var{value}. Then
+instead of passing the name of the user to be notified
+to @file{notify}, @sc{cvs} will pass the @var{value}
+(normally an email address on some other machine).
+
address@hidden does not notify you for your own changes.
+Currently this check is done based on whether the user
+name of the person taking the action which triggers
+notification matches the user name of the person
+getting notification. In fact, in general, the watches
+features only track one edit by each user. It probably
+would be more useful if watches tracked each working
+directory separately, so this behavior might be worth
+changing.
address@hidden "behavior might be worth changing" is an effort to
address@hidden point to future directions while also not promising
address@hidden that "they" (as in "why don't they fix CVS to....")
address@hidden will do this.
address@hidden one implementation issue is identifying whether a
address@hidden working directory is same or different. Comparing
address@hidden pathnames/hostnames is hopeless, but having the server
address@hidden supply a serial number which the client stores in the
address@hidden CVS directory as a magic cookie should work.
+
address@hidden Editing files
address@hidden How to edit a file which is being watched
+
address@hidden Checkout, as term for getting ready to edit
+Since a file which is being watched is checked out
+read-only, you cannot simply edit it. To make it
+read-write, and inform others that you are planning to
+edit it, use the @code{cvs edit} command. Some systems
+call this a @dfn{checkout}, but @sc{cvs} uses that term
+for obtaining a copy of the sources (@pxref{Getting the
+source}), an operation which those systems call a
address@hidden or a @dfn{fetch}.
address@hidden Issue to think about: should we transition CVS
address@hidden towards the "get" terminology? "cvs get" is already a
address@hidden synonym for "cvs checkout" and that section of the
address@hidden manual refers to "Getting the source". If this is
address@hidden done, needs to be done gingerly (for example, we should
address@hidden still accept "checkout" in .cvsrc files indefinitely
address@hidden even if the CVS's messages are changed from "cvs checkout: "
address@hidden to "cvs get: ").
address@hidden There is a concern about whether "get" is not as
address@hidden good for novices because it is a more general term
address@hidden than "checkout" (and thus arguably harder to assign
address@hidden a technical meaning for).
+
address@hidden edit (subcommand)
address@hidden Command {cvs edit} address@hidden address@hidden @address@hidden
address@hidden@dots{}
+
+Prepare to edit the working files @var{files}. @sc{cvs} makes the
address@hidden read-write, and notifies users who have requested
address@hidden notification for any of @var{files}.
+
+The @code{cvs edit} command accepts the same options as the
address@hidden watch add} command, and establishes a temporary watch for the
+user on @var{files}; @sc{cvs} will remove the watch when @var{files} are
address@hidden or @code{commit}ted. If the user does not wish to
+receive notifications, she should specify @code{-a none}.
+
+The @var{files} and the options are processed as for the @code{cvs
+watch} commands.
+
+
address@hidden deffn
+
+Normally when you are done with a set of changes, you
+use the @code{cvs commit} command, which checks in your
+changes and returns the watched files to their usual
+read-only state. But if you instead decide to abandon
+your changes, or not to make any changes, you can use
+the @code{cvs unedit} command.
+
address@hidden unedit (subcommand)
address@hidden Abandoning work
address@hidden Reverting to repository version
address@hidden Command {cvs unedit} address@hidden address@hidden@dots{}
+
+Abandon work on the working files @var{files}, and revert them to the
+repository versions on which they are based. @sc{cvs} makes those
address@hidden read-only for which users have requested notification using
address@hidden watch on}. @sc{cvs} notifies users who have requested
@code{unedit}
+notification for any of @var{files}.
+
+The @var{files} and options are processed as for the
address@hidden watch} commands.
+
+If watches are not in use, the @code{unedit} command
+probably does not work, and the way to revert to the
+repository version is with the command @code{cvs update -C file}
+(@pxref{update}).
+The meaning is
+not precisely the same; the latter may also
+bring in some changes which have been made in the
+repository since the last time you updated.
address@hidden It would be a useful enhancement to CVS to make
address@hidden unedit work in the non-watch case as well.
address@hidden deffn
+
+When using client/server @sc{cvs}, you can use the
address@hidden edit} and @code{cvs unedit} commands even if
address@hidden is unable to successfully communicate with the
+server; the notifications will be sent upon the next
+successful @sc{cvs} command.
+
address@hidden Watch information
address@hidden Information about who is watching and editing
+
address@hidden watchers (subcommand)
address@hidden Command {cvs watchers} address@hidden address@hidden@dots{}
+
+List the users currently watching changes to @var{files}. The report
+includes the files being watched, and the mail address of each watcher.
+
+The @var{files} and options are processed as for the
address@hidden watch} commands.
+
address@hidden deffn
+
+
address@hidden editors (subcommand)
address@hidden Command {cvs editors} address@hidden address@hidden@dots{}
+
+List the users currently working on @var{files}. The report
+includes the mail address of each user, the time when the user began
+working with the file, and the host and path of the working directory
+containing the file.
+
+The @var{files} and options are processed as for the
address@hidden watch} commands.
+
address@hidden deffn
+
address@hidden Watches Compatibility
address@hidden Using watches with old versions of CVS
+
address@hidden CVS 1.6, and watches
+If you use the watch features on a repository, it
+creates @file{CVS} directories in the repository and
+stores the information about watches in that directory.
+If you attempt to use @sc{cvs} 1.6 or earlier with the
+repository, you get an error message such as the
+following (all on one line):
+
address@hidden
+cvs update: cannot open CVS/Entries for reading:
+No such file or directory
address@hidden example
+
address@hidden
+and your operation will likely be aborted. To use the
+watch features, you must upgrade all copies of @sc{cvs}
+which use that repository in local or server mode. If
+you cannot upgrade, use the @code{watch off} and
address@hidden remove} commands to remove all watches, and
+that will restore the repository to a state which
address@hidden 1.6 can cope with.
+
address@hidden Choosing a model
address@hidden Choosing between reserved or unreserved checkouts
address@hidden Choosing, reserved or unreserved checkouts
+
+Reserved and unreserved checkouts each have pros and
+cons. Let it be said that a lot of this is a matter of
+opinion or what works given different groups' working
+styles, but here is a brief description of some of the
+issues. There are many ways to organize a team of
+developers. @sc{cvs} does not try to enforce a certain
+organization. It is a tool that can be used in several
+ways.
+
+Reserved checkouts can be very counter-productive. If
+two persons want to edit different parts of a file,
+there may be no reason to prevent either of them from
+doing so. Also, it is common for someone to take out a
+lock on a file, because they are planning to edit it,
+but then forget to release the lock.
+
address@hidden "many groups"? specifics? cites to papers on this?
address@hidden some way to weasel-word it a bit more so we don't
address@hidden need facts :-)?
+People, especially people who are familiar with
+reserved checkouts, often wonder how often conflicts
+occur if unreserved checkouts are used, and how
+difficult they are to resolve. The experience with
+many groups is that they occur rarely and usually are
+relatively straightforward to resolve.
+
+The rarity of serious conflicts may be surprising, until one realizes
+that they occur only when two developers disagree on the proper design
+for a given section of code; such a disagreement suggests that the
+team has not been communicating properly in the first place. In order
+to collaborate under @emph{any} source management regimen, developers
+must agree on the general design of the system; given this agreement,
+overlapping changes are usually straightforward to merge.
+
+In some cases unreserved checkouts are clearly
+inappropriate. If no merge tool exists for the kind of
+file you are managing (for example word processor files
+or files edited by Computer Aided Design programs), and
+it is not desirable to change to a program which uses a
+mergeable data format, then resolving conflicts is
+going to be unpleasant enough that you generally will
+be better off to simply avoid the conflicts instead, by
+using reserved checkouts.
+
+The watches features described above in @ref{Watches}
+can be considered to be an intermediate model between
+reserved checkouts and unreserved checkouts. When you
+go to edit a file, it is possible to find out who else
+is editing it. And rather than having the system
+simply forbid both people editing the file, it can tell
+you what the situation is and let you figure out
+whether it is a problem in that particular case or not.
+Therefore, for some groups it can be considered the
+best of both the reserved checkout and unreserved
+checkout worlds.
+
address@hidden
---------------------------------------------------------------------
address@hidden Revision management
address@hidden Revision management
address@hidden Revision management
+
address@hidden -- This chapter could be expanded a lot.
address@hidden -- Experiences are very welcome!
+
+If you have read this far, you probably have a pretty
+good grasp on what @sc{cvs} can do for you. This
+chapter talks a little about things that you still have
+to decide.
+
+If you are doing development on your own using @sc{cvs}
+you could probably skip this chapter. The questions
+this chapter takes up become more important when more
+than one person is working in a repository.
+
address@hidden
+* When to commit:: Some discussion on the subject
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden When to commit
address@hidden When to commit?
address@hidden When to commit
address@hidden Committing, when to
address@hidden Policy
+
+Your group should decide which policy to use regarding
+commits. Several policies are possible, and as your
+experience with @sc{cvs} grows you will probably find
+out what works for you.
+
+If you commit files too quickly you might commit files
+that do not even compile. If your partner updates his
+working sources to include your buggy file, he will be
+unable to compile the code. On the other hand, other
+persons will not be able to benefit from the
+improvements you make to the code if you commit very
+seldom, and conflicts will probably be more common.
+
+It is common to only commit files after making sure
+that they can be compiled. Some sites require that the
+files pass a test suite. Policies like this can be
+enforced using the commitinfo file
+(@pxref{commitinfo}), but you should think twice before
+you enforce such a convention. By making the
+development environment too controlled it might become
+too regimented and thus counter-productive to the real
+goal, which is to get software written.
+
address@hidden
---------------------------------------------------------------------
address@hidden Keyword substitution
address@hidden Keyword substitution
address@hidden Keyword substitution
address@hidden Keyword expansion
address@hidden Identifying files
+
address@hidden Be careful when editing this chapter.
address@hidden Remember that this file is kept under
address@hidden version control, so we must not accidentally
address@hidden include a valid keyword in the running text.
+
+As long as you edit source files inside a working
+directory you can always find out the state of
+your files via @samp{cvs status} and @samp{cvs log}.
+But as soon as you export the files from your
+development environment it becomes harder to identify
+which revisions they are.
+
address@hidden can use a mechanism known as @dfn{keyword
+substitution} (or @dfn{keyword expansion}) to help
+identifying the files. Embedded strings of the form
address@hidden@var{keyword}$} and
address@hidden@var{keyword}:@dots{}$} in a file are replaced
+with strings of the form
address@hidden@var{keyword}:@var{value}$} whenever you obtain
+a new revision of the file.
+
address@hidden
+* Keyword list:: Keywords
+* Using keywords:: Using keywords
+* Avoiding substitution:: Avoiding substitution
+* Substitution modes:: Substitution modes
+* Configuring keyword expansion:: Configuring keyword expansion
+* Log keyword:: Problems with the $ Log$ keyword.
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Keyword list
address@hidden Keyword List
address@hidden Keyword List
+
address@hidden FIXME: need some kind of example here I think,
address@hidden perhaps in a
address@hidden "Keyword intro" node. The intro in the "Keyword
address@hidden substitution" node itself seems OK, but to launch
address@hidden into a list of the keywords somehow seems too abrupt.
+
+This is a list of the keywords:
+
address@hidden @code
address@hidden Author keyword
address@hidden $ Author$
+The login name of the user who checked in the revision.
+
address@hidden CVSHeader keyword
address@hidden $ CVSHeader
+A standard header (similar to $ Header$, but with
+the CVS root stripped off). It contains the relative
+pathname of the @sc{rcs} file to the CVS root, the
+revision number, the date (UTC), the author, the state,
+and the locker (if locked). Files will normally never
+be locked when you use @sc{cvs}.
+
+Note that this keyword has only been recently
+introduced to @sc{cvs} and may cause problems with
+existing installations if $ CVSHeader$ is already
+in the files for a different purpose. This keyword may
+be excluded using the @code{KeywordExpansion=eCVSHeader}
+in the @file{CVSROOT/config} file.
+See @ref{Configuring keyword expansion} for more details.
+
address@hidden Date keyword
address@hidden $ Date$
+The date and time (UTC) the revision was checked in.
+
address@hidden Header keyword
address@hidden $ Header$
+A standard header containing the full pathname of the
address@hidden file, the revision number, the date (UTC), the
+author, the state, and the locker (if locked). Files
+will normally never be locked when you use @sc{cvs}.
+
address@hidden Id keyword
address@hidden $ Id$
+Same as @code{$ Header$}, except that the @sc{rcs}
+filename is without a path.
+
address@hidden Name keyword
address@hidden $ Name$
+Tag name used to check out this file. The keyword is
+expanded only if one checks out with an explicit tag
+name. For example, when running the command @code{cvs
+co -r first}, the keyword expands to @samp{Name: first}.
+
address@hidden Locker keyword
address@hidden $ Locker$
+The login name of the user who locked the revision
+(empty if not locked, which is the normal case unless
address@hidden admin -l} is in use).
+
address@hidden Log keyword
address@hidden $ Log$
+The log message supplied during commit, preceded by a
+header containing the @sc{rcs} filename, the revision
+number, the author, and the date (UTC). Existing log
+messages are @emph{not} replaced. Instead, the new log
+message is inserted after @code{$ Log:@dots{}$}.
+Each new line is prefixed with the same string which
+precedes the @code{$Log} keyword. For example, if the
+file contains:
+
address@hidden
+ /* Here is what people have been up to:
+ *
+ * $ Log: frob.c,v $
+ * Revision 1.1 1997/01/03 14:23:51 joe
+ * Add the superfrobnicate option
+ *
+ */
address@hidden example
+
address@hidden
+then additional lines which are added when expanding
+the @code{$Log} keyword will be preceded by @samp{ * }.
+Unlike previous versions of @sc{cvs} and @sc{rcs}, the
address@hidden leader} from the @sc{rcs} file is not used.
+The @code{$Log} keyword is useful for
+accumulating a complete change log in a source file,
+but for several reasons it can be problematic.
address@hidden keyword}.
+
address@hidden RCSfile keyword
address@hidden $ RCSfile$
+The name of the RCS file without a path.
+
address@hidden Revision keyword
address@hidden $ Revision$
+The revision number assigned to the revision.
+
address@hidden Source keyword
address@hidden $ Source$
+The full pathname of the RCS file.
+
address@hidden State keyword
address@hidden $ State$
+The state assigned to the revision. States can be
+assigned with @code{cvs admin -s}---see @ref{admin options}.
+
address@hidden Local keyword
address@hidden Local keyword
+The @code{LocalKeyword} option in the @file{CVSROOT/config} file
+may be used to specify a local keyword which is to be
+used as an alias for one of the other keywords. For
+example, if the @file{CVSROOT/config} file contains
+a line with @code{LocalKeyword=MYBSD=CVSHeader}, then a
+file with the local keyword $ MYBSD$ will be
+expanded as if it were a $ CVSHeader$ keyword. If
+the src/frob.c file contained this keyword, it might
+look something like this:
+
address@hidden
+ /*
+ * $ MYBSD: src/frob.c,v 1.1 2003/05/04 09:27:45 john Exp $
+ */
address@hidden example
+
+Many repositories make use of a such a ``local
+keyword'' feature. An old patch to @sc{cvs} provided
+the @code{LocalKeyword} feature using a @code{tag=}
+option and called this the ``custom tag'' or ``local
+tag'' feature. It was used in conjunction with the
+what they called the @code{tagexpand=} option. In
address@hidden this other option is known as the
address@hidden option.
+See @ref{Configuring keyword expansion} for more
+details.
+
+Examples from popular projects include:
+$ FreeBSD$, $ NetBSD$,
+$ OpenBSD$, $ XFree86$,
+$ Xorg$.
+
+The advantage of this is that you can include your
+local version information in a file using this local
+keyword without disrupting the upstream version
+information (which may be a different local keyword or
+a standard keyword). Allowing bug reports and the like
+to more properly identify the source of the original
+bug to the third-party and reducing the number of
+conflicts that arise during an import of a new version.
+
+All keyword expansion except the local keyword may be
+disabled using the @code{KeywordExpansion} option in
+the @file{CVSROOT/config} file---see
address@hidden keyword expansion} for more details.
+
address@hidden table
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Using keywords
address@hidden Using keywords
+
+To include a keyword string you simply include the
+relevant text string, such as @code{$ Id$}, inside the
+file, and commit the file. @sc{cvs} will automatically
+expand the string as part of the commit operation.
+
+It is common to embed the @code{$ Id$} string in
+the source files so that it gets passed through to
+generated files. For example, if you are managing
+computer program source code, you might include a
+variable which is initialized to contain that string.
+Or some C compilers may provide a @code{#pragma ident}
+directive. Or a document management system might
+provide a way to pass a string through to generated
+files.
+
address@hidden Would be nice to give an example, but doing this in
address@hidden portable C is not possible and the problem with
address@hidden picking any one language (VMS HELP files, Ada,
address@hidden troff, whatever) is that people use CVS for all
address@hidden kinds of files.
+
address@hidden Ident (shell command)
+The @code{ident} command (which is part of the @sc{rcs}
+package) can be used to extract keywords and their
+values from a file. This can be handy for text files,
+but it is even more useful for extracting keywords from
+binary files.
+
address@hidden
+$ ident samp.c
+samp.c:
+ $ Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
+$ gcc samp.c
+$ ident a.out
+a.out:
+ $ Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
address@hidden example
+
address@hidden What (shell command)
address@hidden is another popular revision control system.
+It has a command, @code{what}, which is very similar to
address@hidden and used for the same purpose. Many sites
+without @sc{rcs} have @sc{sccs}. Since @code{what}
+looks for the character sequence @code{@@(#)} it is
+easy to include keywords that are detected by either
+command. Simply prefix the keyword with the
+magic @sc{sccs} phrase, like this:
+
address@hidden
+static char *id="@@(#) $ Id: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $";
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Avoiding substitution
address@hidden Avoiding substitution
+
+Keyword substitution has its disadvantages. Sometimes
+you might want the literal text string
address@hidden Author$} to appear inside a file without
address@hidden interpreting it as a keyword and expanding it
+into something like @samp{$ Author: ceder $}.
+
+There is unfortunately no way to selectively turn off
+keyword substitution. You can use @samp{-ko}
+(@pxref{Substitution modes}) to turn off keyword
+substitution entirely.
+
+In many cases you can avoid using keywords in
+the source, even though they appear in the final
+product. For example, the source for this manual
+contains @samp{$@@address@hidden@}Author$} whenever the text
address@hidden Author$} should appear. In @code{nroff}
+and @code{troff} you can embed the null-character
address@hidden&} inside the keyword for a similar effect.
+
+It is also possible to specify an explicit list of
+keywords to include or exclude using the
address@hidden option in the
address@hidden/config} file--see @ref{Configuring keyword expansion}
+for more details. This feature is intended primarily
+for use with the @code{LocalKeyword} option--see
address@hidden list}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Substitution modes
address@hidden Substitution modes
address@hidden Keyword substitution, changing modes
address@hidden -k (keyword substitution)
address@hidden Kflag
+
address@hidden FIXME: This could be made more coherent, by expanding it
address@hidden with more examples or something.
+Each file has a stored default substitution mode, and
+each working directory copy of a file also has a
+substitution mode. The former is set by the @samp{-k}
+option to @code{cvs add} and @code{cvs admin}; the
+latter is set by the @samp{-k} or @samp{-A} options to @code{cvs
+checkout} or @code{cvs update}. @code{cvs diff} also
+has a @samp{-k} option. For some examples,
+see @ref{Binary files}, and @ref{Merging and keywords}.
address@hidden The fact that -A is overloaded to mean both reset
address@hidden sticky options and reset sticky tags/dates is
address@hidden somewhat questionable. Perhaps there should be
address@hidden separate options to reset sticky options (e.g. -k
address@hidden A") and tags/dates (someone suggested -r HEAD could
address@hidden do this instead of setting a sticky tag of "HEAD"
address@hidden as in the status quo but I haven't thought much
address@hidden about that idea. Of course -r .reset or something
address@hidden could be coined if this needs to be a new option).
address@hidden On the other hand, having -A mean "get things back
address@hidden into the state after a fresh checkout" has a certain
address@hidden appeal, and maybe there is no sufficient reason for
address@hidden creeping featurism in this area.
+
+The modes available are:
+
address@hidden @samp
address@hidden -kkv
+Generate keyword strings using the default form, e.g.
address@hidden Revision: 5.7 $} for the @code{Revision}
+keyword.
+
address@hidden -kkvl
+Like @samp{-kkv}, except that a locker's name is always
+inserted if the given revision is currently locked.
+The locker's name is only relevant if @code{cvs admin
+-l} is in use.
+
address@hidden -kk
+Generate only keyword names in keyword strings; omit
+their values. For example, for the @code{Revision}
+keyword, generate the string @code{$ Revision$}
+instead of @code{$ Revision: 5.7 $}. This option
+is useful to ignore differences due to keyword
+substitution when comparing different revisions of a
+file (@pxref{Merging and keywords}).
+
address@hidden -ko
+Generate the old keyword string, present in the working
+file just before it was checked in. For example, for
+the @code{Revision} keyword, generate the string
address@hidden Revision: 1.1 $} instead of
address@hidden Revision: 5.7 $} if that is how the
+string appeared when the file was checked in.
+
address@hidden -kb
+Like @samp{-ko}, but also inhibit conversion of line
+endings between the canonical form in which they are
+stored in the repository (linefeed only), and the form
+appropriate to the operating system in use on the
+client. For systems, like unix, which use linefeed
+only to terminate lines, this is very similar to
address@hidden For more information on binary files, see
address@hidden files}. In @sc{cvs} version 1.12.2 and later
address@hidden, as set by @code{cvs add}, @code{cvs admin}, or
address@hidden import} may not be overridden by a @samp{-k} option
+specified on the command line.
+
address@hidden -kv
+Generate only keyword values for keyword strings. For
+example, for the @code{Revision} keyword, generate the string
address@hidden instead of @code{$ Revision: 5.7 $}.
+This can help generate files in programming languages
+where it is hard to strip keyword delimiters like
address@hidden Revision: $} from a string. However,
+further keyword substitution cannot be performed once
+the keyword names are removed, so this option should be
+used with care.
+
+One often would like to use @samp{-kv} with @code{cvs
address@hidden But be aware that doesn't
+handle an export containing binary files correctly.
+
address@hidden table
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Configuring keyword expansion
address@hidden Configuring Keyord Expansion
address@hidden Configuring keyword expansion
+
+In a repository that includes third-party software on
+vendor branches, it is sometimes helpful to configure
+CVS to use a local keyword instead of the standard
+$ Id$ or $ Header$ keywords. Examples from
+real projects includ, $ Xorg$, $ XFree86$,
+$ FreeBSD$, $ NetBSD$,
+$ OpenBSD$, and even $ dotat$.
+The advantage of this is that
+you can include your local version information in a
+file using this local keyword (sometimes called a
+``custom tag'' or a ``local tag'') without disrupting
+the upstream version information (which may be a
+different local keyword or a standard keyword). In
+these cases, it is typically desirable to disable the
+expansion of all keywords except the configured local
+keyword.
+
+The @code{KeywordExpansion} option in the
address@hidden/config} file is intended to allow for the
+either the explicit exclusion of a keyword or list of
+keywords, or for the explicit inclusion of a keyword or
+a list of keywords. This list may include the
address@hidden that has been configured.
+
+The @code{KeywordExpansion} option is followed by
address@hidden and the next character may either be @code{i}
+to start an inclusion list or @code{e} to start an
+exclusion list. If the following lines were added to
+the @file{CVSROOT/config} file:
+
address@hidden
+ # Add a "MyBSD" keyword and restrict keyword
+ # expansion
+ LocalKeyword=MyBSD=CVSHeader
+ KeywordExpand=iMyBSD
address@hidden example
+
+then only the $ MyBSD$ keyword would be expanded.
+A list may be used. The this example:
+
address@hidden
+ # Add a "MyBSD" keyword and restrict keyword
+ # expansion to the MyBSD, Name and Date keywords.
+ LocalKeyword=MyBSD=CVSHeader
+ KeywordExpand=iMyBSD,Name,Date
address@hidden example
+
+would allow $ MyBSD$, $ Name$, and
+$ Date$ to be expanded.
+
+It is also possible to configure an exclusion list
+using the following:
+
address@hidden
+ # Do not expand the non-RCS keyword CVSHeader
+ KeywordExpand=eCVSHeader
address@hidden example
+
+This allows @sc{cvs} to ignore the recently introduced
+$ CVSHeader$ keyword and retain all of the
+others. The exclusion entry could also contain the
+standard RCS keyword list, but this could be confusing
+to users that expect RCS keywords to be expanded, so
+ycare should be taken to properly set user expectations
+for a repository that is configured in that manner.
+
+If there is a desire to not have any RCS keywords
+expanded and not use the @code{-ko} flags everywhere,
+an administrator may disable all keyword expansion
+using the @file{CVSROOT/config} line:
+
address@hidden
+ # Do not expand any RCS keywords
+ KeywordExpand=i
address@hidden example
+
+this could be confusing to users that expect RCS
+keywords like $ Id$ to be expanded properly,
+so care should be taken to properly set user
+expectations for a repository so configured.
+
+It should be noted that a patch to provide both the
address@hidden and @code{LocalKeyword} features
+has been around a long time. However, that patch
+implemented these features using @code{tag=} and
address@hidden keywords and those keywords are NOT
+recognized.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Log keyword
address@hidden Problems with the $ Log$ keyword.
+
+The @code{$ Log$} keyword is somewhat
+controversial. As long as you are working on your
+development system the information is easily accessible
+even if you do not use the @code{$ Log$}
+keyword---just do a @code{cvs log}. Once you export
+the file the history information might be useless
+anyhow.
+
+A more serious concern is that @sc{cvs} is not good at
+handling @code{$ Log$} entries when a branch is
+merged onto the main trunk. Conflicts often result
+from the merging operation.
address@hidden Might want to check whether the CVS implementation
address@hidden of RCS_merge has this problem the same way rcsmerge
address@hidden does. I would assume so....
+
+People also tend to "fix" the log entries in the file
+(correcting spelling mistakes and maybe even factual
+errors). If that is done the information from
address@hidden log} will not be consistent with the
+information inside the file. This may or may not be a
+problem in real life.
+
+It has been suggested that the @code{$ Log$}
+keyword should be inserted @emph{last} in the file, and
+not in the files header, if it is to be used at all.
+That way the long list of change messages will not
+interfere with everyday source file browsing.
+
address@hidden
---------------------------------------------------------------------
address@hidden Tracking sources
address@hidden Tracking third-party sources
address@hidden Third-party sources
address@hidden Tracking sources
+
address@hidden FIXME: Need discussion of added and removed files.
address@hidden FIXME: This doesn't really adequately introduce the
address@hidden concepts of "vendor" and "you". They don't *have*
address@hidden to be separate organizations or separate people.
address@hidden We want a description which is somewhat more based on
address@hidden the technical issues of which sources go where, but
address@hidden also with enough examples of how this relates to
address@hidden relationships like customer-supplier, developer-QA,
address@hidden maintainer-contributor, or whatever, to make it
address@hidden seem concrete.
+If you modify a program to better fit your site, you
+probably want to include your modifications when the next
+release of the program arrives. @sc{cvs} can help you with
+this task.
+
address@hidden Vendor
address@hidden Vendor branch
address@hidden Branch, vendor-
+In the terminology used in @sc{cvs}, the supplier of the
+program is called a @dfn{vendor}. The unmodified
+distribution from the vendor is checked in on its own
+branch, the @dfn{vendor branch}. @sc{cvs} reserves branch
+1.1.1 for this use.
+
+When you modify the source and commit it, your revision
+will end up on the main trunk. When a new release is
+made by the vendor, you commit it on the vendor branch
+and copy the modifications onto the main trunk.
+
+Use the @code{import} command to create and update
+the vendor branch. When you import a new file,
+the vendor branch is made the `head' revision, so
+anyone that checks out a copy of the file gets that
+revision. When a local modification is committed it is
+placed on the main trunk, and made the `head'
+revision.
+
address@hidden
+* First import:: Importing for the first time
+* Update imports:: Updating with the import command
+* Reverting local changes:: Reverting to the latest vendor release
+* Binary files in imports:: Binary files require special handling
+* Keywords in imports:: Keyword substitution might be undesirable
+* Multiple vendor branches:: What if you get sources from several places?
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden First import
address@hidden Importing for the first time
address@hidden Importing modules
+
address@hidden Should mention naming conventions for vendor tags,
address@hidden release tags, and perhaps directory names.
+Use the @code{import} command to check in the sources
+for the first time. When you use the @code{import}
+command to track third-party sources, the @dfn{vendor
+tag} and @dfn{release tags} are useful. The
address@hidden tag} is a symbolic name for the branch
+(which is always 1.1.1, unless you use the @samp{-b
address@hidden flag---see @ref{Multiple vendor branches}.). The
address@hidden tags} are symbolic names for a particular
+release, such as @samp{FSF_0_04}.
+
address@hidden I'm not completely sure this belongs here. But
address@hidden we need to say it _somewhere_ reasonably obvious; it
address@hidden is a common misconception among people first learning CVS
+Note that @code{import} does @emph{not} change the
+directory in which you invoke it. In particular, it
+does not set up that directory as a @sc{cvs} working
+directory; if you want to work with the sources import
+them first and then check them out into a different
+directory (@pxref{Getting the source}).
+
address@hidden wdiff (import example)
+Suppose you have the sources to a program called
address@hidden in a directory @file{wdiff-0.04},
+and are going to make private modifications that you
+want to be able to use even when new releases are made
+in the future. You start by importing the source to
+your repository:
+
address@hidden
+$ cd wdiff-0.04
+$ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04
address@hidden example
+
+The vendor tag is named @samp{FSF_DIST} in the above
+example, and the only release tag assigned is
address@hidden
address@hidden FIXME: Need to say where fsf/wdiff comes from.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Update imports
address@hidden Updating with the import command
+
+When a new release of the source arrives, you import it into the
+repository with the same @code{import} command that you used to set up
+the repository in the first place. The only difference is that you
+specify a different release tag this time:
+
address@hidden
+$ tar xfz wdiff-0.05.tar.gz
+$ cd wdiff-0.05
+$ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05
address@hidden example
+
+For files that have not been modified locally, the newly created
+revision becomes the head revision. If you have made local
+changes, @code{import} will warn you that you must merge the changes
+into the main trunk, and tell you to use @samp{checkout -j} to do so:
+
address@hidden FIXME: why "wdiff" here and "fsf/wdiff" in the
address@hidden "import"? I think the assumption is that one has
address@hidden "wdiff fsf/wdiff" or some such in modules, but it
address@hidden would be better to not use modules in this example.
address@hidden
+$ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff
address@hidden example
+
address@hidden
+The above command will check out the latest revision of
address@hidden, merging the changes made on the vendor branch @samp{FSF_DIST}
+since yesterday into the working copy. If any conflicts arise during
+the merge they should be resolved in the normal way (@pxref{Conflicts
+example}). Then, the modified files may be committed.
+
+However, it is much better to use the two release tags rather than using
+a date on the branch as suggested above:
+
address@hidden
+$ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff
address@hidden example
+
address@hidden
+The reason this is better is that
+using a date, as suggested above, assumes that you do
+not import more than one release of a product per day.
+More importantly, using the release tags allows @sc{cvs} to detect files
+that were removed between the two vendor releases and mark them for
+removal. Since @code{import} has no way to detect removed files, you
+should do a merge like this even if @code{import} doesn't tell you to.
+
address@hidden Reverting local changes
address@hidden Reverting to the latest vendor release
+
+You can also revert local changes completely and return
+to the latest vendor release by changing the `head'
+revision back to the vendor branch on all files. For
+example, if you have a checked-out copy of the sources
+in @file{~/work.d/wdiff}, and you want to revert to the
+vendor's version for all the files in that directory,
+you would type:
+
address@hidden
+$ cd ~/work.d/wdiff
+$ cvs admin -bWDIFF .
address@hidden example
+
address@hidden
+You must specify the @samp{-bWDIFF} without any space
+after the @samp{-b}. @xref{admin options}.
+
address@hidden Binary files in imports
address@hidden How to handle binary files with cvs import
+
+Use the @samp{-k} wrapper option to tell import which
+files are binary. @xref{Wrappers}.
+
address@hidden Keywords in imports
address@hidden How to handle keyword substitution with cvs import
+
+The sources which you are importing may contain
+keywords (@pxref{Keyword substitution}). For example,
+the vendor may use @sc{cvs} or some other system
+which uses similar keyword expansion syntax. If you
+just import the files in the default fashion, then
+the keyword expansions supplied by the vendor will
+be replaced by keyword expansions supplied by your
+own copy of @sc{cvs}. It may be more convenient to
+maintain the expansions supplied by the vendor, so
+that this information can supply information about
+the sources that you imported from the vendor.
+
+To maintain the keyword expansions supplied by the
+vendor, supply the @samp{-ko} option to @code{cvs
+import} the first time you import the file.
+This will turn off keyword expansion
+for that file entirely, so if you want to be more
+selective you'll have to think about what you want
+and use the @samp{-k} option to @code{cvs update} or
address@hidden admin} as appropriate.
address@hidden Supplying -ko to import if the file already existed
address@hidden has no effect. Not clear to me whether it should
address@hidden or not.
+
address@hidden Multiple vendor branches
address@hidden Multiple vendor branches
+
+All the examples so far assume that there is only one
+vendor from which you are getting sources. In some
+situations you might get sources from a variety of
+places. For example, suppose that you are dealing with
+a project where many different people and teams are
+modifying the software. There are a variety of ways to
+handle this, but in some cases you have a bunch of
+source trees lying around and what you want to do more
+than anything else is just to all put them in @sc{cvs} so
+that you at least have them in one place.
+
+For handling situations in which there may be more than
+one vendor, you may specify the @samp{-b} option to
address@hidden import}. It takes as an argument the vendor
+branch to import to. The default is @samp{-b 1.1.1}.
+
+For example, suppose that there are two teams, the red
+team and the blue team, that are sending you sources.
+You want to import the red team's efforts to branch
+1.1.1 and use the vendor tag RED. You want to import
+the blue team's efforts to branch 1.1.3 and use the
+vendor tag BLUE. So the commands you might use are:
+
address@hidden
+$ cvs import dir RED RED_1-0
+$ cvs import -b 1.1.3 dir BLUE BLUE_1-5
address@hidden example
+
+Note that if your vendor tag does not match your
address@hidden option, @sc{cvs} will not detect this case! For
+example,
+
address@hidden
+$ cvs import -b 1.1.3 dir RED RED_1-0
address@hidden example
+
address@hidden
+Be careful; this kind of mismatch is sure to sow
+confusion or worse. I can't think of a useful purpose
+for the ability to specify a mismatch here, but if you
+discover such a use, don't. @sc{cvs} is likely to make this
+an error in some future release.
+
address@hidden Probably should say more about the semantics of
address@hidden multiple branches. What about the default branch?
address@hidden What about joining (perhaps not as useful with
address@hidden multiple branches, or perhaps it is. Either way
address@hidden should be mentioned).
+
address@hidden I'm not sure about the best location for this. In
address@hidden one sense, it might belong right after we've introduced
address@hidden CVS's basic version control model, because people need
address@hidden to figure out builds right away. The current location
address@hidden is based on the theory that it kind of akin to the
address@hidden "Revision management" section.
address@hidden Builds
address@hidden How your build system interacts with CVS
address@hidden Builds
address@hidden make
+
+As mentioned in the introduction, @sc{cvs} does not
+contain software for building your software from source
+code. This section describes how various aspects of
+your build system might interact with @sc{cvs}.
+
address@hidden Is there a way to discuss this without reference to
address@hidden tools other than CVS? I'm not sure there is; I
address@hidden wouldn't think that people who learn CVS first would
address@hidden even have this concern.
+One common question, especially from people who are
+accustomed to @sc{rcs}, is how to make their build get
+an up to date copy of the sources. The answer to this
+with @sc{cvs} is two-fold. First of all, since
address@hidden itself can recurse through directories, there
+is no need to modify your @file{Makefile} (or whatever
+configuration file your build tool uses) to make sure
+each file is up to date. Instead, just use two
+commands, first @code{cvs -q update} and then
address@hidden or whatever the command is to invoke your
+build tool. Secondly, you do not necessarily
address@hidden to get a copy of a change someone else made
+until you have finished your own work. One suggested
+approach is to first update your sources, then
+implement, build and
+test the change you were thinking of, and then commit
+your sources (updating first if necessary). By
+periodically (in between changes, using the approach
+just described) updating your entire tree, you ensure
+that your sources are sufficiently up to date.
+
address@hidden Bill of materials
+One common need is to record which versions of which
+source files went into a particular build. This kind
+of functionality is sometimes called @dfn{bill of
+materials} or something similar. The best way to do
+this with @sc{cvs} is to use the @code{tag} command to
+record which versions went into a given build
+(@pxref{Tags}).
+
+Using @sc{cvs} in the most straightforward manner
+possible, each developer will have a copy of the entire
+source tree which is used in a particular build. If
+the source tree is small, or if developers are
+geographically dispersed, this is the preferred
+solution. In fact one approach for larger projects is
+to break a project down into smaller
address@hidden I say subsystem instead of module because they may or
address@hidden may not use the modules file.
+separately-compiled subsystems, and arrange a way of
+releasing them internally so that each developer need
+check out only those subsystems which they are
+actively working on.
+
+Another approach is to set up a structure which allows
+developers to have their own copies of some files, and
+for other files to access source files from a central
+location. Many people have come up with some such a
address@hidden two such people are address@hidden (for
address@hidden a previous employer)
address@hidden and address@hidden (spicm and related tools),
address@hidden but as far as I know
address@hidden no one has nicely packaged or released such a system (or
address@hidden instructions for constructing one).
+system using features such as the symbolic link feature
+found in many operating systems, or the @code{VPATH}
+feature found in many versions of @code{make}. One build
+tool which is designed to help with this kind of thing
+is Odin (see
address@hidden://ftp.cs.colorado.edu/pub/distribs/odin}).
address@hidden Should we be saying more about Odin? Or how you use
address@hidden it with CVS? Also, the Prime Time Freeware for Unix
address@hidden disk (see http://www.ptf.com/) has Odin (with a nice
address@hidden paragraph summarizing it on the web), so that might be a
address@hidden semi-"official" place to point people.
address@hidden
address@hidden Of course, many non-CVS systems have this kind of
address@hidden functionality, for example OSF's ODE
address@hidden (http://www.osf.org/ode/) or mk
address@hidden (http://www.grin.net/~pzi/mk-3.18.4.docs/mk_toc.html
address@hidden He has changed providers in the past; a search engine search
address@hidden for "Peter Ziobrzynski" probably won't get too many
address@hidden spurious hits :-). A more stable URL might be
address@hidden ftp://ftp.uu.net/pub/cmvc/mk). But I'm not sure
address@hidden there is any point in mentioning them here unless they
address@hidden can work with CVS.
+
address@hidden
---------------------------------------------------------------------
address@hidden Special Files
address@hidden Special Files
+
address@hidden Special files
address@hidden Device nodes
address@hidden Ownership, saving in CVS
address@hidden Permissions, saving in CVS
address@hidden Hard links
address@hidden Symbolic links
+
+In normal circumstances, @sc{cvs} works only with regular
+files. Every file in a project is assumed to be
+persistent; it must be possible to open, read and close
+them; and so on. @sc{cvs} also ignores file permissions and
+ownerships, leaving such issues to be resolved by the
+developer at installation time. In other words, it is
+not possible to "check in" a device into a repository;
+if the device file cannot be opened, @sc{cvs} will refuse to
+handle it. Files also lose their ownerships and
+permissions during repository transactions.
+
+
address@hidden
---------------------------------------------------------------------
address@hidden CVS commands
address@hidden Guide to CVS commands
+
+This appendix describes the overall structure of
address@hidden commands, and describes some commands in
+detail (others are described elsewhere; for a quick
+reference to @sc{cvs} commands, @pxref{Invoking CVS}).
address@hidden The idea is that we want to move the commands which
address@hidden are described here into the main body of the manual,
address@hidden in the process reorganizing the manual to be
address@hidden organized around what the user wants to do, not
address@hidden organized around CVS commands.
address@hidden
address@hidden Note that many users do expect a manual which is
address@hidden organized by command. At least some users do.
address@hidden One good addition to the "organized by command"
address@hidden section (if any) would be "see also" links.
address@hidden The awk manual might be a good example; it has a
address@hidden reference manual which is more verbose than Invoking
address@hidden CVS but probably somewhat less verbose than CVS
address@hidden Commands.
+
address@hidden
+* Structure:: Overall structure of CVS commands
+* Exit status:: Indicating CVS's success or failure
+* ~/.cvsrc:: Default options with the ~/.csvrc file
+* Global options:: Options you give to the left of cvs_command
+* Common options:: Options you give to the right of cvs_command
+* admin:: Administration
+* checkout:: Checkout sources for editing
+* commit:: Check files into the repository
+* diff:: Show differences between revisions
+* export:: Export sources from CVS, similar to checkout
+* history:: Show status of files and users
+* import:: Import sources into CVS, using vendor branches
+* log:: Show log messages for files
+* rdiff:: 'patch' format diffs between releases
+* release:: Indicate that a directory is no longer in use
+* update:: Bring work tree in sync with repository
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Structure
address@hidden Overall structure of CVS commands
address@hidden Structure
address@hidden CVS command structure
address@hidden Command structure
address@hidden Format of CVS commands
+
+The overall format of all @sc{cvs} commands is:
+
address@hidden
+cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ]
address@hidden example
+
address@hidden @code
address@hidden cvs
+The name of the @sc{cvs} program.
+
address@hidden cvs_options
+Some options that affect all sub-commands of @sc{cvs}. These are
+described below.
+
address@hidden cvs_command
+One of several different sub-commands. Some of the commands have
+aliases that can be used instead; those aliases are noted in the
+reference manual for that command. There are only two situations
+where you may omit @samp{cvs_command}: @samp{cvs -H} elicits a
+list of available commands, and @samp{cvs -v} displays version
+information on @sc{cvs} itself.
+
address@hidden command_options
+Options that are specific for the command.
+
address@hidden command_args
+Arguments to the commands.
address@hidden table
+
+There is unfortunately some confusion between
address@hidden and @code{command_options}.
address@hidden, when given as a @code{cvs_option}, only
+affects some of the commands. When it is given as a
address@hidden is has a different meaning, and
+is accepted by more commands. In other words, do not
+take the above categorization too seriously. Look at
+the documentation instead.
+
address@hidden Exit status
address@hidden CVS's exit status
address@hidden Exit status, of CVS
+
address@hidden can indicate to the calling environment whether it
+succeeded or failed by setting its @dfn{exit status}.
+The exact way of testing the exit status will vary from
+one operating system to another. For example in a unix
+shell script the @samp{$?} variable will be 0 if the
+last command returned a successful exit status, or
+greater than 0 if the exit status indicated failure.
+
+If @sc{cvs} is successful, it returns a successful status;
+if there is an error, it prints an error message and
+returns a failure status. The one exception to this is
+the @code{cvs diff} command. It will return a
+successful status if it found no differences, or a
+failure status if there were differences or if there
+was an error. Because this behavior provides no good
+way to detect errors, in the future it is possible that
address@hidden diff} will be changed to behave like the
+other @sc{cvs} commands.
address@hidden It might seem like checking whether cvs -q diff
address@hidden produces empty or non-empty output can tell whether
address@hidden there were differences or not. But it seems like
address@hidden there are cases with output but no differences
address@hidden (testsuite basica-8b). It is not clear to me how
address@hidden useful it is for a script to be able to check
address@hidden whether there were differences.
address@hidden FIXCVS? In previous versions of CVS, cvs diff
address@hidden returned 0 for no differences, 1 for differences, or
address@hidden 2 for errors. Is this behavior worth trying to
address@hidden bring back (but what does it mean for VMS?)?
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden ~/.cvsrc
address@hidden Default options and the ~/.cvsrc file
address@hidden .cvsrc file
address@hidden Option defaults
+
+There are some @code{command_options} that are used so
+often that you might have set up an alias or some other
+means to make sure you always specify that option. One
+example (the one that drove the implementation of the
address@hidden support, actually) is that many people find the
+default output of the @samp{diff} command to be very
+hard to read, and that either context diffs or unidiffs
+are much easier to understand.
+
+The @file{~/.cvsrc} file is a way that you can add
+default options to @code{cvs_commands} within cvs,
+instead of relying on aliases or other shell scripts.
+
+The format of the @file{~/.cvsrc} file is simple. The
+file is searched for a line that begins with the same
+name as the @code{cvs_command} being executed. If a
+match is found, then the remainder of the line is split
+up (at whitespace characters) into separate options and
+added to the command arguments @emph{before} any
+options from the command line.
+
+If a command has two names (e.g., @code{checkout} and
address@hidden), the official name, not necessarily the one
+used on the command line, will be used to match against
+the file. So if this is the contents of the user's
address@hidden/.cvsrc} file:
+
address@hidden
+log -N
+diff -uN
+rdiff -u
+update -Pd
+checkout -P
+release -d
address@hidden example
+
address@hidden
+the command @samp{cvs checkout foo} would have the
address@hidden option added to the arguments, as well as
address@hidden co foo}.
+
+With the example file above, the output from @samp{cvs
+diff foobar} will be in unidiff format. @samp{cvs diff
+-c foobar} will provide context diffs, as usual.
+Getting "old" format diffs would be slightly more
+complicated, because @code{diff} doesn't have an option
+to specify use of the "old" format, so you would need
address@hidden -f diff foobar}.
+
+In place of the command name you can use @code{cvs} to
+specify global options (@pxref{Global options}). For
+example the following line in @file{.cvsrc}
+
address@hidden
+cvs -z6
address@hidden example
+
address@hidden
+causes @sc{cvs} to use compression level 6.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Global options
address@hidden Global options
address@hidden Options, global
address@hidden Global options
address@hidden Left-hand options
+
+The available @samp{cvs_options} (that are given to the
+left of @samp{cvs_command}) are:
+
address@hidden @code
address@hidden address@hidden
+Specify legal @sc{cvsroot} directory. See
address@hidden authentication server}.
+
address@hidden Authentication, stream
address@hidden Stream authentication
address@hidden -a
+Authenticate all communication between the client and
+the server. Only has an effect on the @sc{cvs} client.
+As of this writing, this is only implemented when using
+a GSSAPI connection (@pxref{GSSAPI authenticated}).
+Authentication prevents certain sorts of attacks
+involving hijacking the active @sc{tcp} connection.
+Enabling authentication does not enable encryption.
+
address@hidden RCSBIN, overriding
address@hidden Overriding RCSBIN
address@hidden -b @var{bindir}
+In @sc{cvs} 1.9.18 and older, this specified that
address@hidden programs are in the @var{bindir} directory.
+Current versions of @sc{cvs} do not run @sc{rcs}
+programs; for compatibility this option is accepted,
+but it does nothing.
+
address@hidden TMPDIR, overriding
address@hidden Overriding TMPDIR
address@hidden -T @var{tempdir}
+Use @var{tempdir} as the directory where temporary files are
+located. Overrides the setting of the @code{$TMPDIR} environment
+variable and any precompiled directory. This parameter should be
+specified as an absolute pathname.
+(When running client/server, @samp{-T} affects only the local process;
+specifying @samp{-T} for the client has no effect on the server and
+vice versa.)
+
address@hidden CVSROOT, overriding
address@hidden Overriding CVSROOT
address@hidden -d @var{cvs_root_directory}
+Use @var{cvs_root_directory} as the root directory
+pathname of the repository. Overrides the setting of
+the @code{$CVSROOT} environment variable. @xref{Repository}.
+
address@hidden EDITOR, overriding
address@hidden Overriding EDITOR
address@hidden -e @var{editor}
+Use @var{editor} to enter revision log information. Overrides the
+setting of the @code{$CVSEDITOR} and @code{$EDITOR}
+environment variables. For more information, see
address@hidden your changes}.
+
address@hidden -f
+Do not read the @file{~/.cvsrc} file. This
+option is most often used because of the
+non-orthogonality of the @sc{cvs} option set. For
+example, the @samp{cvs log} option @samp{-N} (turn off
+display of tag names) does not have a corresponding
+option to turn the display on. So if you have
address@hidden in the @file{~/.cvsrc} entry for @samp{log},
+you may need to use @samp{-f} to show the tag names.
+
address@hidden -H
address@hidden --help
+Display usage information about the specified @samp{cvs_command}
+(but do not actually execute the command). If you don't specify
+a command name, @samp{cvs -H} displays overall help for
address@hidden, including a list of other help options.
address@hidden It seems to me it is better to document it this way
address@hidden rather than trying to update this documentation
address@hidden every time that we add a --help-foo option. But
address@hidden perhaps that is confusing...
+
address@hidden -l
+Do not log the @samp{cvs_command} in the command history (but execute it
+anyway). @xref{history}, for information on command history.
+
address@hidden Read-only repository mode
address@hidden -R
+Turns on read-only repository mode. This allows one to check out from a
+read-only repository, such as within an anoncvs server, or from a CDROM
+repository.
+
+Same effect as if the @code{CVSREADONLYFS} environment
+variable is set. Using @samp{-R} can also considerably
+speed up checkout's over NFS.
+
address@hidden Read-only mode
address@hidden -n
+Do not change any files. Attempt to execute the
address@hidden, but only to issue reports; do not remove,
+update, or merge any existing files, or create any new files.
+
+Note that @sc{cvs} will not necessarily produce exactly
+the same output as without @samp{-n}. In some cases
+the output will be the same, but in other cases
address@hidden will skip some of the processing that would
+have been required to produce the exact same output.
+
address@hidden -Q
+Cause the command to be really quiet; the command will only
+generate output for serious problems.
+
address@hidden -q
+Cause the command to be somewhat quiet; informational messages,
+such as reports of recursion through subdirectories, are
+suppressed.
+
address@hidden Read-only files, and -r
address@hidden -r
+Make new working files read-only. Same effect
+as if the @code{$CVSREAD} environment variable is set
+(@pxref{Environment variables}). The default is to
+make working files writable, unless watches are on
+(@pxref{Watches}).
+
address@hidden -s @address@hidden
+Set a user variable (@pxref{Variables}).
+
address@hidden Trace
address@hidden -t
+Trace program execution; display messages showing the steps of
address@hidden activity. Particularly useful with @samp{-n} to explore the
+potential impact of an unfamiliar command.
+
address@hidden -v
address@hidden --version
+Display version and copyright information for @sc{cvs}.
+
address@hidden CVSREAD, overriding
address@hidden Overriding CVSREAD
address@hidden -w
+Make new working files read-write. Overrides the
+setting of the @code{$CVSREAD} environment variable.
+Files are created read-write by default, unless @code{$CVSREAD} is
+set or @samp{-r} is given.
address@hidden Note that -w only overrides -r and CVSREAD; it has
address@hidden no effect on files which are readonly because of
address@hidden "cvs watch on". My guess is that is the way it
address@hidden should be (or should "cvs -w get" on a watched file
address@hidden be the same as a get and a cvs edit?), but I'm not
address@hidden completely sure whether to document it this way.
+
address@hidden -x
address@hidden Encryption
+Encrypt all communication between the client and the
+server. Only has an effect on the @sc{cvs} client. As
+of this writing, this is only implemented when using a
+GSSAPI connection (@pxref{GSSAPI authenticated}) or a
+Kerberos connection (@pxref{Kerberos authenticated}).
+Enabling encryption implies that message traffic is
+also authenticated. Encryption support is not
+available by default; it must be enabled using a
+special configure option, @file{--enable-encryption},
+when you build @sc{cvs}.
+
address@hidden -z @var{gzip-level}
address@hidden Compression
address@hidden Gzip
+Set the compression level.
+Valid levels are 1 (high speed, low compression) to
+9 (low speed, high compression), or 0 to disable
+compression (the default).
+Only has an effect on the @sc{cvs} client.
+
address@hidden table
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Common options
address@hidden Common command options
address@hidden Common options
address@hidden Right-hand options
+
+This section describes the @samp{command_options} that
+are available across several @sc{cvs} commands. These
+options are always given to the right of
address@hidden Not all
+commands support all of these options; each option is
+only supported for commands where it makes sense.
+However, when a command has one of these options you
+can almost always count on the same behavior of the
+option as in other commands. (Other command options,
+which are listed with the individual commands, may have
+different behavior from one @sc{cvs} command to the other).
+
address@hidden: the @samp{history} command is an exception; it supports
+many options that conflict even with these standard options.}
+
address@hidden @code
address@hidden Dates
address@hidden Time
address@hidden Specifying dates
address@hidden -D @var{date_spec}
+Use the most recent revision no later than @var{date_spec}.
address@hidden is a single argument, a date description
+specifying a date in the past.
+
+The specification is @dfn{sticky} when you use it to make a
+private copy of a source file; that is, when you get a working
+file using @samp{-D}, @sc{cvs} records the date you specified, so that
+further updates in the same directory will use the same date
+(for more information on sticky tags/dates, @pxref{Sticky tags}).
+
address@hidden is available with the @code{annotate}, @code{checkout},
address@hidden, @code{export}, @code{history},
address@hidden, @code{rtag}, @code{tag}, and @code{update} commands.
+(The @code{history} command uses this option in a
+slightly different way; @pxref{history options}).
+
address@hidden What other formats should we accept? I don't want
address@hidden to start accepting a whole mess of non-standard
address@hidden new formats (there are a lot which are in wide use in
address@hidden one context or another), but practicality does
address@hidden dictate some level of flexibility.
address@hidden * POSIX.2 (e.g. touch, ls output, date) and other
address@hidden POSIX and/or de facto unix standards (e.g. at). The
address@hidden practice here is too inconsistent to be of any use.
address@hidden * VMS dates. This is not a formal standard, but
address@hidden there is a published specification (see SYS$ASCTIM
address@hidden and SYS$BINTIM in the _VMS System Services Reference
address@hidden Manual_), it is implemented consistently in VMS
address@hidden utilities, and VMS users will expect CVS running on
address@hidden VMS to support this format (and if we're going to do
address@hidden that, better to make CVS support it on all
address@hidden platforms. Maybe).
address@hidden
address@hidden NOTE: The tar manual has some documentation for
address@hidden getdate.y (just for our info; we don't want to
address@hidden attempt to document all the formats accepted by
address@hidden getdate.y).
address@hidden
address@hidden One more note: In output, CVS should consistently
address@hidden use one date format, and that format should be one that
address@hidden it accepts in input as well. The former isn't
address@hidden really true (see survey below), and I'm not
address@hidden sure that either of those formats is accepted in
address@hidden input.
address@hidden
address@hidden cvs log
address@hidden current 1996/01/02 13:45:31
address@hidden Internet 02 Jan 1996 13:45:31 UT
address@hidden ISO 1996-01-02 13:45:31
address@hidden cvs ann
address@hidden current 02-Jan-96
address@hidden Internet-like 02 Jan 96
address@hidden ISO 96-01-02
address@hidden cvs status
address@hidden current Tue Jun 11 02:54:53 1996
address@hidden Internet [Tue,] 11 Jun 1996 02:54:53
address@hidden ISO 1996-06-11 02:54:53
address@hidden note: date possibly should be omitted entirely for
address@hidden other reasons.
address@hidden cvs editors
address@hidden current Tue Jun 11 02:54:53 1996 GMT
address@hidden cvs history
address@hidden current 06/11 02:54 +0000
address@hidden any others?
address@hidden There is a good chance the proper solution has to
address@hidden involve at least some level of letting the user
address@hidden decide which format (with the default being the
address@hidden formats CVS has always used; changing these might be
address@hidden _very_ disruptive since scripts may very well be
address@hidden parsing them).
address@hidden
address@hidden Another random bit of prior art concerning dates is
address@hidden the strptime function which takes templates such as
address@hidden "%m/%d/%y", and apparent a variant of getdate()
address@hidden which also honors them. See
address@hidden X/Open CAE Specification, System Interfaces and
address@hidden Headers Issue 4, Version 2 (September 1994), in the
address@hidden entry for getdate() on page 231
+
address@hidden Timezone, in input
address@hidden Zone, time, in input
+A wide variety of date formats are supported by
address@hidden The most standard ones are ISO8601 (from the
+International Standards Organization) and the Internet
+e-mail standard (specified in RFC822 as amended by
+RFC1123).
+
address@hidden Probably should be doing more to spell out just what
address@hidden the rules are, rather than just giving examples.
address@hidden But I want to keep this simple too.
address@hidden So I don't know....
address@hidden A few specific issues: (1) Maybe should reassure
address@hidden people that years after 2000
address@hidden work (they are in the testsuite, so they do indeed
address@hidden work). (2) What do two digit years
address@hidden mean? Where do we accept them? (3) Local times can
address@hidden be ambiguous or nonexistent if they fall during the
address@hidden hour when daylight savings time goes into or out of
address@hidden effect. Pretty obscure, so I'm not at all sure we
address@hidden should be documenting the behavior in that case.
+ISO8601 dates have many variants but a few examples
+are:
+
address@hidden
+1972-09-24
+1972-09-24 20:05
address@hidden example
address@hidden I doubt we really accept all ISO8601 format dates
address@hidden (for example, decimal hours like 1972-09-24 20,2)
address@hidden I'm not sure we should, many of them are pretty
address@hidden bizarre and it has lots of gratuitous multiple ways
address@hidden to specify the same thing.
+
+There are a lot more ISO8601 date formats, and @sc{cvs}
+accepts many of them, but you probably don't want to
+hear the @emph{whole} long story :-).
+
address@hidden Citing a URL here is kind of problematic given how
address@hidden much they change and people who have old versions of
address@hidden this manual, but in case we want to reinstate an
address@hidden ISO8601 URL, a few are:
address@hidden http://www.saqqara.demon.co.uk/datefmt.htm
address@hidden http://www.cl.cam.ac.uk/~mgk25/iso-time.html
address@hidden Citing some other ISO8601 source is probably even
address@hidden worse :-).
+
+In addition to the dates allowed in Internet e-mail
+itself, @sc{cvs} also allows some of the fields to be
+omitted. For example:
address@hidden FIXME: Need to figure out better, and document,
address@hidden what we want to allow the user to omit.
address@hidden NOTE: "omit" does not imply "reorder".
address@hidden FIXME: Need to cite a web page describing how to get
address@hidden RFC's.
+
address@hidden
+24 Sep 1972 20:05
+24 Sep
address@hidden example
+
+The date is interpreted as being in the
+local timezone, unless a specific timezone is
+specified.
+
+These two date formats are preferred. However,
address@hidden currently accepts a wide variety of other date
+formats. They are intentionally not documented here in
+any detail, and future versions of @sc{cvs} might not
+accept all of them.
address@hidden We should document and testsuite "now" and
address@hidden "yesterday". "now" is mentioned in the FAQ and
address@hidden "yesterday" is mentioned in this document (and the
address@hidden message from "cvs import" suggesting a merge
address@hidden command). What else? Probably some/all of the "3
address@hidden weeks ago" family.
address@hidden
address@hidden Maybe at
address@hidden some point have CVS start give warnings on "unofficial"
address@hidden formats (many of which might be typos or user
address@hidden misunderstandings, and/or formats people never/rarely
address@hidden use to specify dates)?
+
+One such format is
address@hidden@var{month}/@var{day}/@var{year}}. This may
+confuse people who are accustomed to having the month
+and day in the other order; @samp{1/4/96} is January 4,
+not April 1.
+
+Remember to quote the argument to the @samp{-D}
+flag so that your shell doesn't interpret spaces as
+argument separators. A command using the @samp{-D}
+flag can look like this:
+
address@hidden
+$ cvs diff -D "1 hour ago" cvs.texinfo
address@hidden example
+
address@hidden Forcing a tag match
address@hidden -f
+When you specify a particular date or tag to @sc{cvs} commands, they
+normally ignore files that do not contain the tag (or did not
+exist prior to the date) that you specified. Use the @samp{-f} option
+if you want files retrieved even when there is no match for the
+tag or date. (The most recent revision of the file
+will be used).
+
+Note that even with @samp{-f}, a tag that you specify
+must exist (that is, in some file, not necessary in
+every file). This is so that @sc{cvs} will continue to
+give an error if you mistype a tag name.
+
address@hidden 800
address@hidden is available with these commands:
address@hidden, @code{checkout}, @code{export},
address@hidden, @code{rtag}, and @code{update}.
+
address@hidden: The @code{commit} and @code{remove}
+commands also have a
address@hidden option, but it has a different behavior for
+those commands. See @ref{commit options}, and
address@hidden files}.}
+
address@hidden -k @var{kflag}
+Override the default processing of RCS keywords other than
address@hidden @xref{Keyword substitution}, for the meaning of
address@hidden Used with the @code{checkout} and @code{update}
+commands, your @var{kflag} specification is
address@hidden; that is, when you use this option
+with a @code{checkout} or @code{update} command,
address@hidden associates your selected @var{kflag} with any files
+it operates on, and continues to use that @var{kflag} with future
+commands on the same files until you specify otherwise.
+
+The @samp{-k} option is available with the @code{add},
address@hidden, @code{diff}, @code{export}, @code{import} and
address@hidden commands.
+
address@hidden: Prior to CVS version 1.12.2, the @samp{-k} flag
+overrode the @samp{-kb} indication for a binary file. This could
+sometimes corrupt binary files. @xref{Merging and keywords}, for
+more.}
+
address@hidden -l
+Local; run only in current working directory, rather than
+recursing through subdirectories.
+
+Available with the following commands: @code{annotate}, @code{checkout},
address@hidden, @code{diff}, @code{edit}, @code{editors}, @code{export},
address@hidden, @code{rdiff}, @code{remove}, @code{rtag},
address@hidden, @code{tag}, @code{unedit}, @code{update}, @code{watch},
+and @code{watchers}.
+
address@hidden Editor, avoiding invocation of
address@hidden Avoiding editor invocation
address@hidden -m @var{message}
+Use @var{message} as log information, instead of
+invoking an editor.
+
+Available with the following commands: @code{add},
address@hidden and @code{import}.
+
address@hidden -n
+Do not run any tag program. (A program can be
+specified to run in the modules
+database (@pxref{modules}); this option bypasses it).
+
address@hidden: this is not the same as the @samp{cvs -n}
+program option, which you can specify to the left of a cvs command!}
+
+Available with the @code{checkout}, @code{commit}, @code{export},
+and @code{rtag} commands.
+
address@hidden -P
+Prune empty directories. See @ref{Removing directories}.
+
address@hidden -p
+Pipe the files retrieved from the repository to standard output,
+rather than writing them in the current directory. Available
+with the @code{checkout} and @code{update} commands.
+
address@hidden -R
+Process directories recursively. This is on by default.
+
+Available with the following commands: @code{annotate}, @code{checkout},
address@hidden, @code{diff}, @code{edit}, @code{editors}, @code{export},
address@hidden, @code{remove}, @code{rtag},
address@hidden, @code{tag}, @code{unedit}, @code{update}, @code{watch},
+and @code{watchers}.
+
address@hidden -r @var{tag}
address@hidden HEAD, special tag
address@hidden BASE, special tag
+Use the revision specified by the @var{tag} argument instead of the
+default @dfn{head} revision. As well as arbitrary tags defined
+with the @code{tag} or @code{rtag} command, two special tags are
+always available: @samp{HEAD} refers to the most recent version
+available in the repository, and @samp{BASE} refers to the
+revision you last checked out into the current working directory.
+
address@hidden FIXME: What does HEAD really mean? I believe that
address@hidden the current answer is the head of the default branch
address@hidden for all cvs commands except diff. For diff, it
address@hidden seems to be (a) the head of the trunk (or the default
address@hidden branch?) if there is no sticky tag, (b) the head of the
address@hidden branch for the sticky tag, if there is a sticky tag.
address@hidden (b) is ugly as it differs
address@hidden from what HEAD means for other commands, but people
address@hidden and/or scripts are quite possibly used to it.
address@hidden See "head" tests in sanity.sh.
address@hidden Probably the best fix is to introduce two new
address@hidden special tags, ".thead" for the head of the trunk,
address@hidden and ".bhead" for the head of the current branch.
address@hidden Then deprecate HEAD. This has the advantage of
address@hidden not surprising people with a change to HEAD, and a
address@hidden side benefit of also phasing out the poorly-named
address@hidden HEAD (see discussion of reserved tag names in node
address@hidden "Tags"). Of course, .thead and .bhead should be
address@hidden carefully implemented (with the implementation the
address@hidden same for "diff" as for everyone else), test cases
address@hidden written (similar to the ones in "head"), new tests
address@hidden cases written for things like default branches, &c.
+
+The tag specification is sticky when you use this
address@hidden option
+with @code{checkout} or @code{update} to make your own
+copy of a file: @sc{cvs} remembers the tag and continues to use it on
+future update commands, until you specify otherwise (for more information
+on sticky tags/dates, @pxref{Sticky tags}).
+
+The tag can be either a symbolic or numeric tag, as
+described in @ref{Tags}, or the name of a branch, as
+described in @ref{Branching and merging}.
+
+Specifying the @samp{-q} global option along with the
address@hidden command option is often useful, to suppress
+the warning messages when the @sc{rcs} file
+does not contain the specified tag.
+
address@hidden: this is not the same as the overall @samp{cvs -r} option,
+which you can specify to the left of a @sc{cvs} command!}
+
address@hidden is available with the @code{checkout}, @code{commit},
address@hidden, @code{history}, @code{export}, @code{rdiff},
address@hidden, and @code{update} commands.
+
address@hidden -W
+Specify file names that should be filtered. You can
+use this option repeatedly. The spec can be a file
+name pattern of the same type that you can specify in
+the @file{.cvswrappers} file.
+Available with the following commands: @code{import},
+and @code{update}.
+
address@hidden table
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden admin
address@hidden admin---Administration
address@hidden Admin (subcommand)
+
address@hidden @bullet
address@hidden
+Requires: repository, working directory.
address@hidden
+Changes: repository.
address@hidden
+Synonym: rcs
address@hidden itemize
+
+This is the @sc{cvs} interface to assorted
+administrative facilities. Some of them have
+questionable usefulness for @sc{cvs} but exist for
+historical purposes. Some of the questionable options
+are likely to disappear in the future. This command
address@hidden work recursively, so extreme care should be
+used.
+
address@hidden cvsadmin
address@hidden UserAdminOptions, in CVSROOT/config
+On unix, if there is a group named @code{cvsadmin},
+only members of that group can run @code{cvs admin}
+commands, except for those specified using the
address@hidden configuration option in the
address@hidden/config} file. Options specified using
address@hidden can be run by any user. See
address@hidden for more on @code{UserAdminOptions}.
+
+The @code{cvsadmin} group should exist on the server,
+or any system running the non-client/server @sc{cvs}.
+To disallow @code{cvs admin} for all users, create a
+group with no users in it. On NT, the @code{cvsadmin}
+feature does not exist and all users
+can run @code{cvs admin}.
+
address@hidden
+* admin options:: admin options
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden admin options
address@hidden admin options
+
+Some of these options have questionable usefulness for
address@hidden but exist for historical purposes. Some even
+make it impossible to use @sc{cvs} until you undo the
+effect!
+
address@hidden @code
address@hidden address@hidden
+Might not work together with @sc{cvs}. Append the
+access list of @var{oldfile} to the access list of the
address@hidden file.
+
address@hidden address@hidden
+Might not work together with @sc{cvs}. Append the
+login names appearing in the comma-separated list
address@hidden to the access list of the @sc{rcs} file.
+
address@hidden address@hidden
+Set the default branch to @var{rev}. In @sc{cvs}, you
+normally do not manipulate default branches; sticky
+tags (@pxref{Sticky tags}) are a better way to decide
+which branch you want to work on. There is one reason
+to run @code{cvs admin -b}: to revert to the vendor's
+version when using vendor branches (@pxref{Reverting
+local changes}).
+There can be no space between @samp{-b} and its argument.
address@hidden Hmm, we don't document the usage where rev is
address@hidden omitted. Maybe that usage can/should be deprecated
address@hidden (and replaced with -bHEAD or something?) (so we can toss
address@hidden the optional argument). Note that -bHEAD does not
address@hidden work, as of 17 Sep 1997, but probably will once "cvs
address@hidden admin" is internal to CVS.
+
address@hidden Comment leader
address@hidden address@hidden
+Sets the comment leader to @var{string}. The comment
+leader is not used by current versions of @sc{cvs} or
address@hidden 5.7. Therefore, you can almost surely not
+worry about it. @xref{Keyword substitution}.
+
address@hidden address@hidden
+Might not work together with @sc{cvs}. Erase the login
+names appearing in the comma-separated list
address@hidden from the access list of the RCS file. If
address@hidden is omitted, erase the entire access list.
+There can be no space between @samp{-e} and its argument.
+
address@hidden -I
+Run interactively, even if the standard input is not a
+terminal. This option does not work with the
+client/server @sc{cvs} and is likely to disappear in
+a future release of @sc{cvs}.
+
address@hidden -i
+Useless with @sc{cvs}. This creates and initializes a
+new @sc{rcs} file, without depositing a revision. With
address@hidden, add files with the @code{cvs add} command
+(@pxref{Adding files}).
+
address@hidden address@hidden
+Set the default keyword
+substitution to @var{subst}. @xref{Keyword
+substitution}. Giving an explicit @samp{-k} option to
address@hidden update}, @code{cvs export}, or @code{cvs
+checkout} overrides this default.
+
address@hidden address@hidden
+Lock the revision with number @var{rev}. If a branch
+is given, lock the latest revision on that branch. If
address@hidden is omitted, lock the latest revision on the
+default branch. There can be no space between
address@hidden and its argument.
+
+This can be used in conjunction with the
address@hidden script in the @file{contrib}
+directory of the @sc{cvs} source distribution to
+provide reserved checkouts (where only one user can be
+editing a given file at a time). See the comments in
+that file for details (and see the @file{README} file
+in that directory for disclaimers about the unsupported
+nature of contrib). According to comments in that
+file, locking must set to strict (which is the default).
+
address@hidden -L
+Set locking to strict. Strict locking means that the
+owner of an RCS file is not exempt from locking for
+checkin. For use with @sc{cvs}, strict locking must be
+set; see the discussion under the @samp{-l} option above.
+
address@hidden Changing a log message
address@hidden Replacing a log message
address@hidden Correcting a log message
address@hidden Fixing a log message
address@hidden Log message, correcting
address@hidden address@hidden:@var{msg}
+Replace the log message of revision @var{rev} with
address@hidden
+
address@hidden The rcs -M option, to suppress sending mail, has never been
address@hidden documented as a cvs admin option.
+
address@hidden address@hidden:address@hidden
+Act like @samp{-n}, except override any previous
+assignment of @var{name}. For use with magic branches,
+see @ref{Magic branch numbers}.
+
address@hidden address@hidden:address@hidden
+Associate the symbolic name @var{name} with the branch
+or revision @var{rev}. It is normally better to use
address@hidden tag} or @samp{cvs rtag} instead. Delete the
+symbolic name if both @samp{:} and @var{rev} are
+omitted; otherwise, print an error message if
address@hidden is already associated with another number.
+If @var{rev} is symbolic, it is expanded before
+association. A @var{rev} consisting of a branch number
+followed by a @samp{.} stands for the current latest
+revision in the branch. A @samp{:} with an empty
address@hidden stands for the current latest revision on the
+default branch, normally the trunk. For example,
address@hidden admin address@hidden:} associates @var{name} with the
+current latest revision of all the RCS files;
+this contrasts with @samp{cvs admin address@hidden:$} which
+associates @var{name} with the revision numbers
+extracted from keyword strings in the corresponding
+working files.
+
address@hidden Deleting revisions
address@hidden Outdating revisions
address@hidden Saving space
address@hidden address@hidden
+Deletes (@dfn{outdates}) the revisions given by
address@hidden
+
+Note that this command can be quite dangerous unless
+you know @emph{exactly} what you are doing (for example
+see the warnings below about how the
address@hidden:@var{rev2} syntax is confusing).
+
+If you are short on disc this option might help you.
+But think twice before using it---there is no way short
+of restoring the latest backup to undo this command!
+If you delete different revisions than you planned,
+either due to carelessness or (heaven forbid) a @sc{cvs}
+bug, there is no opportunity to correct the error
+before the revisions are deleted. It probably would be
+a good idea to experiment on a copy of the repository
+first.
+
+Specify @var{range} in one of the following ways:
+
address@hidden @code
address@hidden @var{rev1}::@var{rev2}
+Collapse all revisions between rev1 and rev2, so that
address@hidden only stores the differences associated with going
+from rev1 to rev2, not intermediate steps. For
+example, after @samp{-o 1.3::1.5} one can retrieve
+revision 1.3, revision 1.5, or the differences to get
+from 1.3 to 1.5, but not the revision 1.4, or the
+differences between 1.3 and 1.4. Other examples:
address@hidden 1.3::1.4} and @samp{-o 1.3::1.3} have no
+effect, because there are no intermediate revisions to
+remove.
+
address@hidden ::@var{rev}
+Collapse revisions between the beginning of the branch
+containing @var{rev} and @var{rev} itself. The
+branchpoint and @var{rev} are left intact. For
+example, @samp{-o ::1.3.2.6} deletes revision 1.3.2.1,
+revision 1.3.2.5, and everything in between, but leaves
+1.3 and 1.3.2.6 intact.
+
address@hidden @var{rev}::
+Collapse revisions between @var{rev} and the end of the
+branch containing @var{rev}. Revision @var{rev} is
+left intact but the head revision is deleted.
+
address@hidden @var{rev}
+Delete the revision @var{rev}. For example, @samp{-o
+1.3} is equivalent to @samp{-o 1.2::1.4}.
+
address@hidden @var{rev1}:@var{rev2}
+Delete the revisions from @var{rev1} to @var{rev2},
+inclusive, on the same branch. One will not be able to
+retrieve @var{rev1} or @var{rev2} or any of the
+revisions in between. For example, the command
address@hidden admin -oR_1_01:R_1_02 .} is rarely useful.
+It means to delete revisions up to, and including, the
+tag R_1_02. But beware! If there are files that have not
+changed between R_1_02 and R_1_03 the file will have
address@hidden same} numerical revision number assigned to
+the tags R_1_02 and R_1_03. So not only will it be
+impossible to retrieve R_1_02; R_1_03 will also have to
+be restored from the tapes! In most cases you want to
+specify @var{rev1}::@var{rev2} instead.
+
address@hidden :@var{rev}
+Delete revisions from the beginning of the
+branch containing @var{rev} up to and including
address@hidden
+
address@hidden @var{rev}:
+Delete revisions from revision @var{rev}, including
address@hidden itself, to the end of the branch containing
address@hidden
address@hidden table
+
+None of the revisions to be deleted may have
+branches or locks.
+
+If any of the revisions to be deleted have symbolic
+names, and one specifies one of the @samp{::} syntaxes,
+then @sc{cvs} will give an error and not delete any
+revisions. If you really want to delete both the
+symbolic names and the revisions, first delete the
+symbolic names with @code{cvs tag -d}, then run
address@hidden admin -o}. If one specifies the
address@hidden::} syntaxes, then @sc{cvs} will delete the
+revisions but leave the symbolic names pointing to
+nonexistent revisions. This behavior is preserved for
+compatibility with previous versions of @sc{cvs}, but
+because it isn't very useful, in the future it may
+change to be like the @samp{::} case.
+
+Due to the way @sc{cvs} handles branches @var{rev}
+cannot be specified symbolically if it is a branch.
address@hidden branch numbers}, for an explanation.
address@hidden FIXME: is this still true? I suspect not.
+
+Make sure that no-one has checked out a copy of the
+revision you outdate. Strange things will happen if he
+starts to edit it and tries to check it back in. For
+this reason, this option is not a good way to take back
+a bogus commit; commit a new revision undoing the bogus
+change instead (@pxref{Merging two revisions}).
+
address@hidden -q
+Run quietly; do not print diagnostics.
+
address@hidden address@hidden:@var{rev}]
+Useful with @sc{cvs}. Set the state attribute of the
+revision @var{rev} to @var{state}. If @var{rev} is a
+branch number, assume the latest revision on that
+branch. If @var{rev} is omitted, assume the latest
+revision on the default branch. Any identifier is
+acceptable for @var{state}. A useful set of states is
address@hidden (for experimental), @samp{Stab} (for
+stable), and @samp{Rel} (for released). By default,
+the state of a new revision is set to @samp{Exp} when
+it is created. The state is visible in the output from
address@hidden log} (@pxref{log}), and in the
address@hidden Log$} and @samp{$ State$} keywords
+(@pxref{Keyword substitution}). Note that @sc{cvs}
+uses the @code{dead} state for its own purposes; to
+take a file to or from the @code{dead} state use
+commands like @code{cvs remove} and @code{cvs add}, not
address@hidden admin -s}.
+
address@hidden address@hidden
+Useful with @sc{cvs}. Write descriptive text from the
+contents of the named @var{file} into the RCS file,
+deleting the existing text. The @var{file} pathname
+may not begin with @samp{-}. The descriptive text can be seen in the
+output from @samp{cvs log} (@pxref{log}).
+There can be no space between @samp{-t} and its argument.
+
+If @var{file} is omitted,
+obtain the text from standard input, terminated by
+end-of-file or by a line containing @samp{.} by itself.
+Prompt for the text if interaction is possible; see
address@hidden
+
address@hidden address@hidden
+Similar to @address@hidden Write descriptive text
+from the @var{string} into the @sc{rcs} file, deleting
+the existing text.
+There can be no space between @samp{-t} and its argument.
+
address@hidden The rcs -T option, do not update last-mod time for
address@hidden minor changes, has never been documented as a
address@hidden cvs admin option.
+
address@hidden -U
+Set locking to non-strict. Non-strict locking means
+that the owner of a file need not lock a revision for
+checkin. For use with @sc{cvs}, strict locking must be
+set; see the discussion under the @samp{-l} option
+above.
+
address@hidden address@hidden
+See the option @samp{-l} above, for a discussion of
+using this option with @sc{cvs}. Unlock the revision
+with number @var{rev}. If a branch is given, unlock
+the latest revision on that branch. If @var{rev} is
+omitted, remove the latest lock held by the caller.
+Normally, only the locker of a revision may unlock it;
+somebody else unlocking a revision breaks the lock.
+This causes the original locker to be sent a @code{commit}
+notification (@pxref{Getting Notified}).
+There can be no space between @samp{-u} and its argument.
+
address@hidden address@hidden
+In previous versions of @sc{cvs}, this option meant to
+write an @sc{rcs} file which would be acceptable to
address@hidden version @var{n}, but it is now obsolete and
+specifying it will produce an error.
address@hidden Note that -V without an argument has never been
address@hidden documented as a cvs admin option.
+
address@hidden address@hidden
+In previous versions of @sc{cvs}, this was documented
+as a way of specifying the names of the @sc{rcs}
+files. However, @sc{cvs} has always required that the
address@hidden files used by @sc{cvs} end in @samp{,v}, so
+this option has never done anything useful.
+
address@hidden The rcs -z option, to specify the timezone, has
address@hidden never been documented as a cvs admin option.
address@hidden table
+
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden checkout
address@hidden checkout---Check out sources for editing
address@hidden checkout (subcommand)
address@hidden co (subcommand)
+
address@hidden @bullet
address@hidden
+Synopsis: checkout [options] address@hidden
address@hidden
+Requires: repository.
address@hidden
+Changes: working directory.
address@hidden
+Synonyms: co, get
address@hidden itemize
+
+Create or update a working directory containing copies of the
+source files specified by @var{modules}. You must execute
address@hidden before using most of the other @sc{cvs}
+commands, since most of them operate on your working
+directory.
+
+The @var{modules} are either
+symbolic names for some
+collection of source directories and files, or paths to
+directories or files in the repository. The symbolic
+names are defined in the @samp{modules} file.
address@hidden
address@hidden Needs an example, particularly of the non-"modules"
address@hidden case but probably of both.
+
address@hidden FIXME: this seems like a very odd place to introduce
address@hidden people to how CVS works. The bit about unreserved
address@hidden checkouts is also misleading as it depends on how
address@hidden things are set up.
+Depending on the modules you specify, @code{checkout} may
+recursively create directories and populate them with
+the appropriate source files. You can then edit these
+source files at any time (regardless of whether other
+software developers are editing their own copies of the
+sources); update them to include new changes applied by
+others to the source repository; or commit your work as
+a permanent change to the source repository.
+
+Note that @code{checkout} is used to create
+directories. The top-level directory created is always
+added to the directory where @code{checkout} is
+invoked, and usually has the same name as the specified
+module. In the case of a module alias, the created
+sub-directory may have a different name, but you can be
+sure that it will be a sub-directory, and that
address@hidden will show the relative path leading to
+each file as it is extracted into your private work
+area (unless you specify the @samp{-Q} global option).
+
+The files created by @code{checkout} are created
+read-write, unless the @samp{-r} option to @sc{cvs}
+(@pxref{Global options}) is specified, the
address@hidden environment variable is specified
+(@pxref{Environment variables}), or a watch is in
+effect for that file (@pxref{Watches}).
+
+Note that running @code{checkout} on a directory that was already
+built by a prior @code{checkout} is also permitted.
+This is similar to specifying the @samp{-d} option
+to the @code{update} command in the sense that new
+directories that have been created in the repository
+will appear in your work area.
+However, @code{checkout} takes a module name whereas
address@hidden takes a directory name. Also
+to use @code{checkout} this way it must be run from the
+top level directory (where you originally ran
address@hidden from), so before you run
address@hidden to update an existing directory, don't
+forget to change your directory to the top level
+directory.
+
+For the output produced by the @code{checkout} command
+see @ref{update output}.
+
address@hidden
+* checkout options:: checkout options
+* checkout examples:: checkout examples
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden checkout options
address@hidden checkout options
+
+These standard options are supported by @code{checkout}
+(@pxref{Common options}, for a complete description of
+them):
+
address@hidden @code
address@hidden -D @var{date}
+Use the most recent revision no later than @var{date}.
+This option is sticky, and implies @samp{-P}. See
address@hidden tags}, for more information on sticky tags/dates.
+
address@hidden -f
+Only useful with the @samp{-D @var{date}} or @samp{-r
address@hidden flags. If no matching revision is found,
+retrieve the most recent revision (instead of ignoring
+the file).
+
address@hidden -k @var{kflag}
+Process keywords according to @var{kflag}. See
address@hidden substitution}.
+This option is sticky; future updates of
+this file in this working directory will use the same
address@hidden The @code{status} command can be viewed
+to see the sticky options. See @ref{Invoking CVS}, for
+more information on the @code{status} command.
+
address@hidden -l
+Local; run only in current working directory.
+
address@hidden -n
+Do not run any checkout program (as specified
+with the @samp{-o} option in the modules file;
address@hidden).
+
address@hidden -P
+Prune empty directories. See @ref{Moving directories}.
+
address@hidden -p
+Pipe files to the standard output.
+
address@hidden -R
+Checkout directories recursively. This option is on by default.
+
address@hidden -r @var{tag}
+Use revision @var{tag}. This option is sticky, and implies @samp{-P}.
+See @ref{Sticky tags}, for more information on sticky tags/dates.
address@hidden table
+
+In addition to those, you can use these special command
+options with @code{checkout}:
+
address@hidden @code
address@hidden -A
+Reset any sticky tags, dates, or @samp{-k} options.
+See @ref{Sticky tags}, for more information on sticky tags/dates.
+
address@hidden -c
+Copy the module file, sorted, to the standard output,
+instead of creating or modifying any files or
+directories in your working directory.
+
address@hidden -d @var{dir}
+Create a directory called @var{dir} for the working
+files, instead of using the module name. In general,
+using this flag is equivalent to using @samp{mkdir
address@hidden; cd @var{dir}} followed by the checkout
+command without the @samp{-d} flag.
+
+There is an important exception, however. It is very
+convenient when checking out a single item to have the
+output appear in a directory that doesn't contain empty
+intermediate directories. In this case @emph{only},
address@hidden tries to ``shorten'' pathnames to avoid those empty
+directories.
+
+For example, given a module @samp{foo} that contains
+the file @samp{bar.c}, the command @samp{cvs co -d dir
+foo} will create directory @samp{dir} and place
address@hidden inside. Similarly, given a module
address@hidden which has subdirectory @samp{baz} wherein
+there is a file @samp{quux.c}, the command @samp{cvs co
+-d dir bar/baz} will create directory @samp{dir} and
+place @samp{quux.c} inside.
+
+Using the @samp{-N} flag will defeat this behavior.
+Given the same module definitions above, @samp{cvs co
+-N -d dir foo} will create directories @samp{dir/foo}
+and place @samp{bar.c} inside, while @samp{cvs co -N -d
+dir bar/baz} will create directories @samp{dir/bar/baz}
+and place @samp{quux.c} inside.
+
address@hidden -j @var{tag}
+With two @samp{-j} options, merge changes from the
+revision specified with the first @samp{-j} option to
+the revision specified with the second @samp{j} option,
+into the working directory.
+
+With one @samp{-j} option, merge changes from the
+ancestor revision to the revision specified with the
address@hidden option, into the working directory. The
+ancestor revision is the common ancestor of the
+revision which the working directory is based on, and
+the revision specified in the @samp{-j} option.
+
+In addition, each -j option can contain an optional
+date specification which, when used with branches, can
+limit the chosen revision to one within a specific
+date. An optional date is specified by adding a colon
+(:) to the tag:
address@hidden@var{Symbolic_Tag}:@var{Date_Specifier}}.
+
address@hidden and merging}.
+
address@hidden -N
+Only useful together with @samp{-d @var{dir}}. With
+this option, @sc{cvs} will not ``shorten'' module paths
+in your working directory when you check out a single
+module. See the @samp{-d} flag for examples and a
+discussion.
+
address@hidden -s
+Like @samp{-c}, but include the status of all modules,
+and sort it by the status string. @xref{modules}, for
+info about the @samp{-s} option that is used inside the
+modules file to set the module status.
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden checkout examples
address@hidden checkout examples
+
+Get a copy of the module @samp{tc}:
+
address@hidden
+$ cvs checkout tc
address@hidden example
+
+Get a copy of the module @samp{tc} as it looked one day
+ago:
+
address@hidden
+$ cvs checkout -D yesterday tc
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden commit
address@hidden commit---Check files into the repository
address@hidden commit (subcommand)
+
address@hidden @bullet
address@hidden
+Synopsis: commit [-lnRf] [-m 'log_message' |
+-F file] [-r revision] address@hidden
address@hidden
+Requires: working directory, repository.
address@hidden
+Changes: repository.
address@hidden
+Synonym: ci
address@hidden itemize
+
+Use @code{commit} when you want to incorporate changes
+from your working source files into the source
+repository.
+
+If you don't specify particular files to commit, all of
+the files in your working current directory are
+examined. @code{commit} is careful to change in the
+repository only those files that you have really
+changed. By default (or if you explicitly specify the
address@hidden option), files in subdirectories are also
+examined and committed if they have changed; you can
+use the @samp{-l} option to limit @code{commit} to the
+current directory only.
+
address@hidden verifies that the selected files are up
+to date with the current revisions in the source
+repository; it will notify you, and exit without
+committing, if any of the specified files must be made
+current first with @code{update} (@pxref{update}).
address@hidden does not call the @code{update} command
+for you, but rather leaves that for you to do when the
+time is right.
+
+When all is well, an editor is invoked to allow you to
+enter a log message that will be written to one or more
+logging programs (@pxref{modules}, and @pxref{loginfo})
+and placed in the @sc{rcs} file inside the
+repository. This log message can be retrieved with the
address@hidden command; see @ref{log}. You can specify the
+log message on the command line with the @samp{-m
address@hidden option, and thus avoid the editor invocation,
+or use the @samp{-F @var{file}} option to specify
+that the argument file contains the log message.
+
address@hidden
+* commit options:: commit options
+* commit examples:: commit examples
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden commit options
address@hidden commit options
+
+These standard options are supported by @code{commit}
+(@pxref{Common options}, for a complete description of
+them):
+
address@hidden @code
address@hidden -l
+Local; run only in current working directory.
+
address@hidden -R
+Commit directories recursively. This is on by default.
+
address@hidden -r @var{revision}
+Commit to @var{revision}. @var{revision} must be
+either a branch, or a revision on the main trunk that
+is higher than any existing revision number
+(@pxref{Assigning revisions}). You
+cannot commit to a specific revision on a branch.
address@hidden FIXME: Need xref for branch case.
address@hidden table
+
address@hidden also supports these options:
+
address@hidden @code
address@hidden -F @var{file}
+Read the log message from @var{file}, instead
+of invoking an editor.
+
address@hidden -f
+Note that this is not the standard behavior of
+the @samp{-f} option as defined in @ref{Common options}.
+
+Force @sc{cvs} to commit a new revision even if you haven't
+made any changes to the file. If the current revision
+of @var{file} is 1.7, then the following two commands
+are equivalent:
+
address@hidden
+$ cvs commit -f @var{file}
+$ cvs commit -r 1.8 @var{file}
address@hidden example
+
address@hidden This is odd, but it's how CVS has worked for some
address@hidden time.
+The @samp{-f} option disables recursion (i.e., it
+implies @samp{-l}). To force @sc{cvs} to commit a new
+revision for all files in all subdirectories, you must
+use @samp{-f -R}.
+
address@hidden -m @var{message}
+Use @var{message} as the log message, instead of
+invoking an editor.
address@hidden table
+
address@hidden 2000
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden commit examples
address@hidden commit examples
+
address@hidden FIXME: this material wants to be somewhere
address@hidden in "Branching and merging".
+
address@hidden Committing to a branch
+
+You can commit to a branch revision (one that has an
+even number of dots) with the @samp{-r} option. To
+create a branch revision, use the @samp{-b} option
+of the @code{rtag} or @code{tag} commands
+(@pxref{Branching and merging}). Then, either @code{checkout} or
address@hidden can be used to base your sources on the
+newly created branch. From that point on, all
address@hidden changes made within these working sources
+will be automatically added to a branch revision,
+thereby not disturbing main-line development in any
+way. For example, if you had to create a patch to the
+1.2 version of the product, even though the 2.0 version
+is already under development, you might do:
+
address@hidden
+$ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module
+$ cvs checkout -r FCS1_2_Patch product_module
+$ cd product_module
+[[ hack away ]]
+$ cvs commit
address@hidden example
+
address@hidden
+This works automatically since the @samp{-r} option is
+sticky.
+
address@hidden Creating the branch after editing
+
+Say you have been working on some extremely
+experimental software, based on whatever revision you
+happened to checkout last week. If others in your
+group would like to work on this software with you, but
+without disturbing main-line development, you could
+commit your change to a new branch. Others can then
+checkout your experimental stuff and utilize the full
+benefit of @sc{cvs} conflict resolution. The scenario might
+look like:
+
address@hidden FIXME: Should we be recommending tagging the branchpoint?
address@hidden
+[[ hacked sources are present ]]
+$ cvs tag -b EXPR1
+$ cvs update -r EXPR1
+$ cvs commit
address@hidden example
+
+The @code{update} command will make the @samp{-r
+EXPR1} option sticky on all files. Note that your
+changes to the files will never be removed by the
address@hidden command. The @code{commit} will
+automatically commit to the correct branch, because the
address@hidden is sticky. You could also do like this:
+
address@hidden FIXME: Should we be recommending tagging the branchpoint?
address@hidden
+[[ hacked sources are present ]]
+$ cvs tag -b EXPR1
+$ cvs commit -r EXPR1
address@hidden example
+
address@hidden
+but then, only those files that were changed by you
+will have the @samp{-r EXPR1} sticky flag. If you hack
+away, and commit without specifying the @samp{-r EXPR1}
+flag, some files may accidentally end up on the main
+trunk.
+
+To work with you on the experimental change, others
+would simply do
+
address@hidden
+$ cvs checkout -r EXPR1 whatever_module
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden diff
address@hidden diff---Show differences between revisions
address@hidden diff (subcommand)
+
address@hidden @bullet
address@hidden
+Synopsis: diff [-lR] [-k kflag] [format_options] [[-r rev1 | -D date1] [-r
rev2 | -D date2]] address@hidden
address@hidden
+Requires: working directory, repository.
address@hidden
+Changes: nothing.
address@hidden itemize
+
+The @code{diff} command is used to compare different
+revisions of files. The default action is to compare
+your working files with the revisions they were based
+on, and report any differences that are found.
+
+If any file names are given, only those files are
+compared. If any directories are given, all files
+under them will be compared.
+
+The exit status for diff is different than for other
address@hidden commands; for details @ref{Exit status}.
+
address@hidden
+* diff options:: diff options
+* diff examples:: diff examples
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden diff options
address@hidden diff options
+
+These standard options are supported by @code{diff}
+(@pxref{Common options}, for a complete description of
+them):
+
address@hidden @code
address@hidden -D @var{date}
+Use the most recent revision no later than @var{date}.
+See @samp{-r} for how this affects the comparison.
+
address@hidden -k @var{kflag}
+Process keywords according to @var{kflag}. See
address@hidden substitution}.
+
address@hidden -l
+Local; run only in current working directory.
+
address@hidden -R
+Examine directories recursively. This option is on by
+default.
+
address@hidden -r @var{tag}
+Compare with revision @var{tag}. Zero, one or two
address@hidden options can be present. With no @samp{-r}
+option, the working file will be compared with the
+revision it was based on. With one @samp{-r}, that
+revision will be compared to your current working file.
+With two @samp{-r} options those two revisions will be
+compared (and your working file will not affect the
+outcome in any way).
address@hidden We should be a lot more explicit, with examples,
address@hidden about the difference between "cvs diff" and "cvs
address@hidden diff -r HEAD". This often confuses new users.
+
+One or both @samp{-r} options can be replaced by a
address@hidden @var{date}} option, described above.
address@hidden table
+
address@hidden Conceptually, this is a disaster. There are 3
address@hidden zillion diff formats that we support via the diff
address@hidden library. It is not obvious to me that we should
address@hidden document them all. Maybe just the most common ones
address@hidden like -c and -u, and think about phasing out the
address@hidden obscure ones.
address@hidden FIXCVS: also should be a way to specify an external
address@hidden diff program (which can be different for different
address@hidden file types) and pass through
address@hidden arbitrary options, so that the user can do
address@hidden "--pass=-Z --pass=foo" or something even if CVS
address@hidden doesn't know about the "-Z foo" option to diff.
address@hidden This would fit nicely with deprecating/eliminating
address@hidden the obscure options of the diff library, because it
address@hidden would let people specify an external GNU diff if
address@hidden they are into that sort of thing.
+The following options specify the format of the
+output. They have the same meaning as in GNU diff.
+Most options have two equivalent names, one of which is a single letter
+preceded by @samp{-}, and the other of which is a long name preceded by
address@hidden
+
address@hidden @samp
address@hidden address@hidden
+Show @var{lines} (an integer) lines of context. This option does not
+specify an output format by itself; it has no effect unless it is
+combined with @samp{-c} or @samp{-u}. This option is obsolete. For proper
+operation, @code{patch} typically needs at least two lines of context.
+
address@hidden -a
+Treat all files as text and compare them line-by-line, even if they
+do not seem to be text.
+
address@hidden -b
+Ignore trailing white space and consider all other sequences of one or
+more white space characters to be equivalent.
+
address@hidden -B
+Ignore changes that just insert or delete blank lines.
+
address@hidden --binary
+Read and write data in binary mode.
+
address@hidden --brief
+Report only whether the files differ, not the details of the
+differences.
+
address@hidden -c
+Use the context output format.
+
address@hidden -C @var{lines}
address@hidden address@hidden@address@hidden
+Use the context output format, showing @var{lines} (an integer) lines of
+context, or three if @var{lines} is not given.
+For proper operation, @code{patch} typically needs at least two lines of
+context.
+
address@hidden address@hidden
+Use @var{format} to output a line group containing differing lines from
+both files in if-then-else format. @xref{Line group formats}.
+
address@hidden -d
+Change the algorithm to perhaps find a smaller set of changes. This makes
address@hidden slower (sometimes much slower).
+
address@hidden -e
address@hidden --ed
+Make output that is a valid @code{ed} script.
+
address@hidden --expand-tabs
+Expand tabs to spaces in the output, to preserve the alignment of tabs
+in the input files.
+
address@hidden -f
+Make output that looks vaguely like an @code{ed} script but has changes
+in the order they appear in the file.
+
address@hidden -F @var{regexp}
+In context and unified format, for each hunk of differences, show some
+of the last preceding line that matches @var{regexp}.
+
address@hidden --forward-ed
+Make output that looks vaguely like an @code{ed} script but has changes
+in the order they appear in the file.
+
address@hidden -H
+Use heuristics to speed handling of large files that have numerous
+scattered small changes.
+
address@hidden address@hidden
+Do not discard the last @var{lines} lines of the common prefix
+and the first @var{lines} lines of the common suffix.
+
address@hidden -i
+Ignore changes in case; consider upper- and lower-case letters
+equivalent.
+
address@hidden -I @var{regexp}
+Ignore changes that just insert or delete lines that match @var{regexp}.
+
address@hidden address@hidden
+Make merged if-then-else output using @var{name}.
+
address@hidden --ignore-all-space
+Ignore white space when comparing lines.
+
address@hidden --ignore-blank-lines
+Ignore changes that just insert or delete blank lines.
+
address@hidden --ignore-case
+Ignore changes in case; consider upper- and lower-case to be the same.
+
address@hidden address@hidden
+Ignore changes that just insert or delete lines that match @var{regexp}.
+
address@hidden --ignore-space-change
+Ignore trailing white space and consider all other sequences of one or
+more white space characters to be equivalent.
+
address@hidden --initial-tab
+Output a tab rather than a space before the text of a line in normal or
+context format. This causes the alignment of tabs in the line to look
+normal.
+
address@hidden -L @var{label}
+Use @var{label} instead of the file name in the context format
+and unified format headers.
+
address@hidden address@hidden
+Use @var{label} instead of the file name in the context format
+and unified format headers.
+
address@hidden --left-column
+Print only the left column of two common lines in side by side format.
+
address@hidden address@hidden
+Use @var{format} to output all input lines in if-then-else format.
address@hidden formats}.
+
address@hidden --minimal
+Change the algorithm to perhaps find a smaller set of changes. This
+makes @code{diff} slower (sometimes much slower).
+
address@hidden -n
+Output RCS-format diffs; like @samp{-f} except that each command
+specifies the number of lines affected.
+
address@hidden -N
address@hidden --new-file
+In directory comparison, if a file is found in only one directory,
+treat it as present but empty in the other directory.
+
address@hidden address@hidden
+Use @var{format} to output a group of lines taken from just the second
+file in if-then-else format. @xref{Line group formats}.
+
address@hidden address@hidden
+Use @var{format} to output a line taken from just the second file in
+if-then-else format. @xref{Line formats}.
+
address@hidden address@hidden
+Use @var{format} to output a group of lines taken from just the first
+file in if-then-else format. @xref{Line group formats}.
+
address@hidden address@hidden
+Use @var{format} to output a line taken from just the first file in
+if-then-else format. @xref{Line formats}.
+
address@hidden -p
+Show which C function each change is in.
+
address@hidden --rcs
+Output RCS-format diffs; like @samp{-f} except that each command
+specifies the number of lines affected.
+
address@hidden --report-identical-files
address@hidden -s
+Report when two files are the same.
+
address@hidden --show-c-function
+Show which C function each change is in.
+
address@hidden address@hidden
+In context and unified format, for each hunk of differences, show some
+of the last preceding line that matches @var{regexp}.
+
address@hidden --side-by-side
+Use the side by side output format.
+
address@hidden --speed-large-files
+Use heuristics to speed handling of large files that have numerous
+scattered small changes.
+
address@hidden --suppress-common-lines
+Do not print common lines in side by side format.
+
address@hidden -t
+Expand tabs to spaces in the output, to preserve the alignment of tabs
+in the input files.
+
address@hidden -T
+Output a tab rather than a space before the text of a line in normal or
+context format. This causes the alignment of tabs in the line to look
+normal.
+
address@hidden --text
+Treat all files as text and compare them line-by-line, even if they
+do not appear to be text.
+
address@hidden -u
+Use the unified output format.
+
address@hidden address@hidden
+Use @var{format} to output a group of common lines taken from both files
+in if-then-else format. @xref{Line group formats}.
+
address@hidden address@hidden
+Use @var{format} to output a line common to both files in if-then-else
+format. @xref{Line formats}.
+
address@hidden -U @var{lines}
address@hidden address@hidden@address@hidden
+Use the unified output format, showing @var{lines} (an integer) lines of
+context, or three if @var{lines} is not given.
+For proper operation, @code{patch} typically needs at least two lines of
+context.
+
address@hidden -w
+Ignore white space when comparing lines.
+
address@hidden -W @var{columns}
address@hidden address@hidden
+Use an output width of @var{columns} in side by side format.
+
address@hidden -y
+Use the side by side output format.
address@hidden table
+
address@hidden
+* Line group formats:: Line group formats
+* Line formats:: Line formats
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden Line group formats
address@hidden Line group formats
+
+Line group formats let you specify formats suitable for many
+applications that allow if-then-else input, including programming
+languages and text formatting languages. A line group format specifies
+the output format for a contiguous group of similar lines.
+
+For example, the following command compares the TeX file @file{myfile}
+with the original version from the repository,
+and outputs a merged file in which old regions are
+surrounded by @address@hidden@address@hidden@address@hidden lines, and new
+regions are surrounded by @address@hidden@address@hidden@address@hidden lines.
+
address@hidden
+cvs diff \
+ --old-group-format='address@hidden@}
+%<address@hidden@}
+' \
+ --new-group-format='address@hidden@}
+%>address@hidden@}
+' \
+ myfile
address@hidden example
+
+The following command is equivalent to the above example, but it is a
+little more verbose, because it spells out the default line group formats.
+
address@hidden
+cvs diff \
+ --old-group-format='address@hidden@}
+%<address@hidden@}
+' \
+ --new-group-format='address@hidden@}
+%>address@hidden@}
+' \
+ --unchanged-group-format='%=' \
+ --changed-group-format='address@hidden@}
+%<address@hidden@}
address@hidden@}
+%>address@hidden@}
+' \
+ myfile
address@hidden example
+
+Here is a more advanced example, which outputs a diff listing with
+headers containing line numbers in a ``plain English'' style.
+
address@hidden
+cvs diff \
+ --unchanged-group-format='' \
+ --old-group-format='-------- %dn line%(n=1?:s) deleted at %df:
+%<' \
+ --new-group-format='-------- %dN line%(N=1?:s) added after %de:
+%>' \
+ --changed-group-format='-------- %dn line%(n=1?:s) changed at %df:
+%<-------- to:
+%>' \
+ myfile
address@hidden example
+
+To specify a line group format, use one of the options
+listed below. You can specify up to four line group formats, one for
+each kind of line group. You should quote @var{format}, because it
+typically contains shell metacharacters.
+
address@hidden @samp
address@hidden address@hidden
+These line groups are hunks containing only lines from the first file.
+The default old group format is the same as the changed group format if
+it is specified; otherwise it is a format that outputs the line group as-is.
+
address@hidden address@hidden
+These line groups are hunks containing only lines from the second
+file. The default new group format is same as the changed group
+format if it is specified; otherwise it is a format that outputs the
+line group as-is.
+
address@hidden address@hidden
+These line groups are hunks containing lines from both files. The
+default changed group format is the concatenation of the old and new
+group formats.
+
address@hidden address@hidden
+These line groups contain lines common to both files. The default
+unchanged group format is a format that outputs the line group as-is.
address@hidden table
+
+In a line group format, ordinary characters represent themselves;
+conversion specifications start with @samp{%} and have one of the
+following forms.
+
address@hidden @samp
address@hidden %<
+stands for the lines from the first file, including the trailing newline.
+Each line is formatted according to the old line format (@pxref{Line formats}).
+
address@hidden %>
+stands for the lines from the second file, including the trailing newline.
+Each line is formatted according to the new line format.
+
address@hidden %=
+stands for the lines common to both files, including the trailing newline.
+Each line is formatted according to the unchanged line format.
+
address@hidden %%
+stands for @samp{%}.
+
address@hidden %c'@var{C}'
+where @var{C} is a single character, stands for @var{C}.
address@hidden may not be a backslash or an apostrophe.
+For example, @samp{%c':'} stands for a colon, even inside
+the then-part of an if-then-else format, which a colon would
+normally terminate.
+
address@hidden %c'address@hidden'
+where @var{O} is a string of 1, 2, or 3 octal digits,
+stands for the character with octal code @var{O}.
+For example, @samp{%c'\0'} stands for a null character.
+
address@hidden @address@hidden
+where @var{F} is a @code{printf} conversion specification and @var{n} is one
+of the following letters, stands for @var{n}'s value formatted with @var{F}.
+
address@hidden @samp
address@hidden e
+The line number of the line just before the group in the old file.
+
address@hidden f
+The line number of the first line in the group in the old file;
+equals @var{e} + 1.
+
address@hidden l
+The line number of the last line in the group in the old file.
+
address@hidden m
+The line number of the line just after the group in the old file;
+equals @var{l} + 1.
+
address@hidden n
+The number of lines in the group in the old file; equals @var{l} - @var{f} + 1.
+
address@hidden E, F, L, M, N
+Likewise, for lines in the new file.
+
address@hidden table
+
+The @code{printf} conversion specification can be @samp{%d},
address@hidden, @samp{%x}, or @samp{%X}, specifying decimal, octal,
+lower case hexadecimal, or upper case hexadecimal output
+respectively. After the @samp{%} the following options can appear in
+sequence: a @samp{-} specifying left-justification; an integer
+specifying the minimum field width; and a period followed by an
+optional integer specifying the minimum number of digits.
+For example, @samp{%5dN} prints the number of new lines in the group
+in a field of width 5 characters, using the @code{printf} format @code{"%5d"}.
+
address@hidden (@address@hidden@var{T}:@var{E})
+If @var{A} equals @var{B} then @var{T} else @var{E}.
address@hidden and @var{B} are each either a decimal constant
+or a single letter interpreted as above.
+This format spec is equivalent to @var{T} if
address@hidden's value equals @var{B}'s; otherwise it is equivalent to @var{E}.
+
+For example, @samp{%(N=0?no:%dN) line%(N=1?:s)} is equivalent to
address@hidden lines} if @var{N} (the number of lines in the group in the
+new file) is 0, to @samp{1 line} if @var{N} is 1, and to @samp{%dN lines}
+otherwise.
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden Line formats
address@hidden Line formats
+
+Line formats control how each line taken from an input file is
+output as part of a line group in if-then-else format.
+
+For example, the following command outputs text with a one-column
+change indicator to the left of the text. The first column of output
+is @samp{-} for deleted lines, @samp{|} for added lines, and a space
+for unchanged lines. The formats contain newline characters where
+newlines are desired on output.
+
address@hidden
+cvs diff \
+ --old-line-format='-%l
+' \
+ --new-line-format='|%l
+' \
+ --unchanged-line-format=' %l
+' \
+ myfile
address@hidden example
+
+To specify a line format, use one of the following options. You should
+quote @var{format}, since it often contains shell metacharacters.
+
address@hidden @samp
address@hidden address@hidden
+formats lines just from the first file.
+
address@hidden address@hidden
+formats lines just from the second file.
+
address@hidden address@hidden
+formats lines common to both files.
+
address@hidden address@hidden
+formats all lines; in effect, it sets all three above options simultaneously.
address@hidden table
+
+In a line format, ordinary characters represent themselves;
+conversion specifications start with @samp{%} and have one of the
+following forms.
+
address@hidden @samp
address@hidden %l
+stands for the contents of the line, not counting its trailing
+newline (if any). This format ignores whether the line is incomplete.
+
address@hidden %L
+stands for the contents of the line, including its trailing newline
+(if any). If a line is incomplete, this format preserves its
+incompleteness.
+
address@hidden %%
+stands for @samp{%}.
+
address@hidden %c'@var{C}'
+where @var{C} is a single character, stands for @var{C}.
address@hidden may not be a backslash or an apostrophe.
+For example, @samp{%c':'} stands for a colon.
+
address@hidden %c'address@hidden'
+where @var{O} is a string of 1, 2, or 3 octal digits,
+stands for the character with octal code @var{O}.
+For example, @samp{%c'\0'} stands for a null character.
+
address@hidden @var{F}n
+where @var{F} is a @code{printf} conversion specification,
+stands for the line number formatted with @var{F}.
+For example, @samp{%.5dn} prints the line number using the
address@hidden format @code{"%.5d"}. @xref{Line group formats}, for
+more about printf conversion specifications.
+
address@hidden table
+
+The default line format is @samp{%l} followed by a newline character.
+
+If the input contains tab characters and it is important that they line
+up on output, you should ensure that @samp{%l} or @samp{%L} in a line
+format is just after a tab stop (e.g.@: by preceding @samp{%l} or
address@hidden with a tab character), or you should use the @samp{-t} or
address@hidden option.
+
+Taken together, the line and line group formats let you specify many
+different formats. For example, the following command uses a format
+similar to @code{diff}'s normal format. You can tailor this command
+to get fine control over @code{diff}'s output.
+
address@hidden
+cvs diff \
+ --old-line-format='< %l
+' \
+ --new-line-format='> %l
+' \
+ --old-group-format='%df%(f=l?:,%dl)d%dE
+%<' \
+ --new-group-format='%dea%dF%(F=L?:,%dL)
+%>' \
+ --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL)
+%<---
+%>' \
+ --unchanged-group-format='' \
+ myfile
address@hidden example
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden diff examples
address@hidden diff examples
+
+The following line produces a Unidiff (@samp{-u} flag)
+between revision 1.14 and 1.19 of
address@hidden Due to the @samp{-kk} flag no
+keywords are substituted, so differences that only depend
+on keyword substitution are ignored.
+
address@hidden
+$ cvs diff -kk -u -r 1.14 -r 1.19 backend.c
address@hidden example
+
+Suppose the experimental branch EXPR1 was based on a
+set of files tagged RELEASE_1_0. To see what has
+happened on that branch, the following can be used:
+
address@hidden
+$ cvs diff -r RELEASE_1_0 -r EXPR1
address@hidden example
+
+A command like this can be used to produce a context
+diff between two releases:
+
address@hidden
+$ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs
address@hidden example
+
+If you are maintaining ChangeLogs, a command like the following
+just before you commit your changes may help you write
+the ChangeLog entry. All local modifications that have
+not yet been committed will be printed.
+
address@hidden
+$ cvs diff -u | less
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden export
address@hidden export---Export sources from CVS, similar to checkout
address@hidden export (subcommand)
+
address@hidden @bullet
address@hidden
+Synopsis: export [-flNnR] [-r rev|-D date] [-k subst] [-d dir] address@hidden
address@hidden
+Requires: repository.
address@hidden
+Changes: current directory.
address@hidden itemize
+
+This command is a variant of @code{checkout}; use it
+when you want a copy of the source for module without
+the @sc{cvs} administrative directories. For example, you
+might use @code{export} to prepare source for shipment
+off-site. This command requires that you specify a
+date or tag (with @samp{-D} or @samp{-r}), so that you
+can count on reproducing the source you ship to others
+(and thus it always prunes empty directories).
+
+One often would like to use @samp{-kv} with @code{cvs
+export}. This causes any keywords to be
+expanded such that an import done at some other site
+will not lose the keyword revision information. But be
+aware that doesn't handle an export containing binary
+files correctly. Also be aware that after having used
address@hidden, one can no longer use the @code{ident}
+command (which is part of the @sc{rcs} suite---see
+ident(1)) which looks for keyword strings. If
+you want to be able to use @code{ident} you must not
+use @samp{-kv}.
+
address@hidden
+* export options:: export options
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden export options
address@hidden export options
+
+These standard options are supported by @code{export}
+(@pxref{Common options}, for a complete description of
+them):
+
address@hidden @code
address@hidden -D @var{date}
+Use the most recent revision no later than @var{date}.
+
address@hidden -f
+If no matching revision is found, retrieve the most
+recent revision (instead of ignoring the file).
+
address@hidden -l
+Local; run only in current working directory.
+
address@hidden -n
+Do not run any checkout program.
+
address@hidden -R
+Export directories recursively. This is on by default.
+
address@hidden -r @var{tag}
+Use revision @var{tag}.
address@hidden table
+
+In addition, these options (that are common to
address@hidden and @code{export}) are also supported:
+
address@hidden @code
address@hidden -d @var{dir}
+Create a directory called @var{dir} for the working
+files, instead of using the module name.
address@hidden options}, for complete details on how
address@hidden handles this flag.
+
address@hidden -k @var{subst}
+Set keyword expansion mode (@pxref{Substitution modes}).
+
address@hidden -N
+Only useful together with @samp{-d @var{dir}}.
address@hidden options}, for complete details on how
address@hidden handles this flag.
address@hidden table
+
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden history
address@hidden history---Show status of files and users
address@hidden history (subcommand)
+
address@hidden @bullet
address@hidden
+Synopsis: history [-report] [-flags] [-options args] address@hidden
address@hidden
+Requires: the file @file{$CVSROOT/CVSROOT/history}
address@hidden
+Changes: nothing.
address@hidden itemize
+
address@hidden can keep a history file that tracks each use of the
address@hidden, @code{commit}, @code{rtag},
address@hidden, and @code{release} commands. You can
+use @code{history} to display this information in
+various formats.
+
+Logging must be enabled by creating the file
address@hidden/CVSROOT/history}.
+
address@hidden: @code{history} uses @samp{-f}, @samp{-l},
address@hidden, and @samp{-p} in ways that conflict with the
+normal use inside @sc{cvs} (@pxref{Common options}).}
+
address@hidden
+* history options:: history options
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden history options
address@hidden history options
+
+Several options (shown above as @samp{-report}) control what
+kind of report is generated:
+
address@hidden @code
address@hidden -c
+Report on each time commit was used (i.e., each time
+the repository was modified).
+
address@hidden -e
+Everything (all record types). Equivalent to
+specifying @samp{-x} with all record types. Of course,
address@hidden will also include record types which are
+added in a future version of @sc{cvs}; if you are
+writing a script which can only handle certain record
+types, you'll want to specify @samp{-x}.
+
address@hidden -m @var{module}
+Report on a particular module. (You can meaningfully
+use @samp{-m} more than once on the command line.)
+
address@hidden -o
+Report on checked-out modules. This is the default report type.
+
address@hidden -T
+Report on all tags.
+
address@hidden -x @var{type}
+Extract a particular set of record types @var{type} from the @sc{cvs}
+history. The types are indicated by single letters,
+which you may specify in combination.
+
+Certain commands have a single record type:
+
address@hidden @code
address@hidden F
+release
address@hidden O
+checkout
address@hidden E
+export
address@hidden T
+rtag
address@hidden table
+
address@hidden
+One of four record types may result from an update:
+
address@hidden @code
address@hidden C
+A merge was necessary but collisions were
+detected (requiring manual merging).
address@hidden G
+A merge was necessary and it succeeded.
address@hidden U
+A working file was copied from the repository.
address@hidden W
+The working copy of a file was deleted during
+update (because it was gone from the repository).
address@hidden table
+
address@hidden
+One of three record types results from commit:
+
address@hidden @code
address@hidden A
+A file was added for the first time.
address@hidden M
+A file was modified.
address@hidden R
+A file was removed.
address@hidden table
address@hidden table
+
+The options shown as @samp{-flags} constrain or expand
+the report without requiring option arguments:
+
address@hidden @code
address@hidden -a
+Show data for all users (the default is to show data
+only for the user executing @code{history}).
+
address@hidden -l
+Show last modification only.
+
address@hidden -w
+Show only the records for modifications done from the
+same working directory where @code{history} is
+executing.
address@hidden table
+
+The options shown as @samp{-options @var{args}} constrain the report
+based on an argument:
+
address@hidden @code
address@hidden -b @var{str}
+Show data back to a record containing the string
address@hidden in either the module name, the file name, or
+the repository path.
+
address@hidden -D @var{date}
+Show data since @var{date}. This is slightly different
+from the normal use of @samp{-D @var{date}}, which
+selects the newest revision older than @var{date}.
+
address@hidden -f @var{file}
+Show data for a particular file
+(you can specify several @samp{-f} options on the same command line).
+This is equivalent to specifying the file on the command line.
+
address@hidden -n @var{module}
+Show data for a particular module
+(you can specify several @samp{-n} options on the same command line).
+
address@hidden -p @var{repository}
+Show data for a particular source repository (you
+can specify several @samp{-p} options on the same command
+line).
+
address@hidden -r @var{rev}
+Show records referring to revisions since the revision
+or tag named @var{rev} appears in individual @sc{rcs}
+files. Each @sc{rcs} file is searched for the revision or
+tag.
+
address@hidden -t @var{tag}
+Show records since tag @var{tag} was last added to the
+history file. This differs from the @samp{-r} flag
+above in that it reads only the history file, not the
address@hidden files, and is much faster.
+
address@hidden -u @var{name}
+Show records for user @var{name}.
+
address@hidden -z @var{timezone}
+Show times in the selected records using the specified
+time zone instead of UTC.
address@hidden table
+
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden import
address@hidden import---Import sources into CVS, using vendor branches
address@hidden import (subcommand)
+
address@hidden FIXME: This node is way too long for one which has subnodes.
+
address@hidden @bullet
address@hidden
+Synopsis: import [-options] repository vendortag address@hidden
address@hidden
+Requires: Repository, source distribution directory.
address@hidden
+Changes: repository.
address@hidden itemize
+
+Use @code{import} to incorporate an entire source
+distribution from an outside source (e.g., a source
+vendor) into your source repository directory. You can
+use this command both for initial creation of a
+repository, and for wholesale updates to the module
+from the outside source. @xref{Tracking sources}, for
+a discussion on this subject.
+
+The @var{repository} argument gives a directory name
+(or a path to a directory) under the @sc{cvs} root directory
+for repositories; if the directory did not exist,
+import creates it.
+
+When you use import for updates to source that has been
+modified in your source repository (since a prior
+import), it will notify you of any files that conflict
+in the two branches of development; use @samp{checkout
+-j} to reconcile the differences, as import instructs
+you to do.
+
+If @sc{cvs} decides a file should be ignored
+(@pxref{cvsignore}), it does not import it and prints
address@hidden } followed by the filename (@pxref{import output}, for a
+complete description of the output).
+
+If the file @file{$CVSROOT/CVSROOT/cvswrappers} exists,
+any file whose names match the specifications in that
+file will be treated as packages and the appropriate
+filtering will be performed on the file/directory
+before being imported. @xref{Wrappers}.
+
+The outside source is saved in a first-level
+branch, by default 1.1.1. Updates are leaves of this
+branch; for example, files from the first imported
+collection of source will be revision 1.1.1.1, then
+files from the first imported update will be revision
+1.1.1.2, and so on.
+
+At least three arguments are required.
address@hidden is needed to identify the collection
+of source. @var{vendortag} is a tag for the entire
+branch (e.g., for 1.1.1). You must also specify at
+least one @var{releasetag} to identify the files at
+the leaves created each time you execute @code{import}.
+
address@hidden I'm not completely sure this belongs here. But
address@hidden we need to say it _somewhere_ reasonably obvious; it
address@hidden is a common misconception among people first learning CVS
+Note that @code{import} does @emph{not} change the
+directory in which you invoke it. In particular, it
+does not set up that directory as a @sc{cvs} working
+directory; if you want to work with the sources import
+them first and then check them out into a different
+directory (@pxref{Getting the source}).
+
address@hidden
+* import options:: import options
+* import output:: import output
+* import examples:: import examples
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden import options
address@hidden import options
+
+This standard option is supported by @code{import}
+(@pxref{Common options}, for a complete description):
+
address@hidden @code
address@hidden -m @var{message}
+Use @var{message} as log information, instead of
+invoking an editor.
address@hidden table
+
+There are the following additional special options.
+
address@hidden @code
address@hidden -b @var{branch}
+See @ref{Multiple vendor branches}.
+
address@hidden -k @var{subst}
+Indicate the keyword expansion mode desired. This
+setting will apply to all files created during the
+import, but not to any files that previously existed in
+the repository. See @ref{Substitution modes}, for a
+list of valid @samp{-k} settings.
+
address@hidden -I @var{name}
+Specify file names that should be ignored during
+import. You can use this option repeatedly. To avoid
+ignoring any files at all (even those ignored by
+default), specify `-I !'.
+
address@hidden can be a file name pattern of the same type
+that you can specify in the @file{.cvsignore} file.
address@hidden
address@hidden -- Is this really true?
+
address@hidden -W @var{spec}
+Specify file names that should be filtered during
+import. You can use this option repeatedly.
+
address@hidden can be a file name pattern of the same type
+that you can specify in the @file{.cvswrappers}
+file. @xref{Wrappers}.
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden import output
address@hidden import output
+
address@hidden keeps you informed of its progress by printing a line
+for each file, preceded by one character indicating the status of the file:
+
address@hidden @code
address@hidden U @var{file}
+The file already exists in the repository and has not been locally
+modified; a new revision has been created (if necessary).
+
address@hidden N @var{file}
+The file is a new file which has been added to the repository.
+
address@hidden C @var{file}
+The file already exists in the repository but has been locally modified;
+you will have to merge the changes.
+
address@hidden I @var{file}
+The file is being ignored (@pxref{cvsignore}).
+
address@hidden Symbolic link, importing
address@hidden Link, symbolic, importing
address@hidden FIXME: also (somewhere else) probably
address@hidden should be documenting what happens if you "cvs add"
address@hidden a symbolic link. Also maybe what happens if
address@hidden you manually create symbolic links within the
address@hidden repository (? - not sure why we'd want to suggest
address@hidden doing that).
address@hidden L @var{file}
+The file is a symbolic link; @code{cvs import} ignores symbolic links.
+People periodically suggest that this behavior should
+be changed, but if there is a consensus on what it
+should be changed to, it is not apparent.
+(Various options in the @file{modules} file can be used
+to recreate symbolic links on checkout, update, etc.;
address@hidden)
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden import examples
address@hidden import examples
+
+See @ref{Tracking sources}, and @ref{From files}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden log
address@hidden log---Print out log information for files
address@hidden log (subcommand)
+
address@hidden @bullet
address@hidden
+Synopsis: log [options] address@hidden
address@hidden
+Requires: repository, working directory.
address@hidden
+Changes: nothing.
address@hidden itemize
+
+Display log information for files. @code{log} used to
+call the @sc{rcs} utility @code{rlog}. Although this
+is no longer true in the current sources, this history
+determines the format of the output and the options,
+which are not quite in the style of the other @sc{cvs}
+commands.
+
address@hidden Timezone, in output
address@hidden Zone, time, in output
address@hidden Kind of a funny place to document the timezone used
address@hidden in output from commands other than @code{log}.
address@hidden There is also more we need to say about this,
address@hidden including what happens in a client/server environment.
+The output includes the location of the @sc{rcs} file,
+the @dfn{head} revision (the latest revision on the
+trunk), all symbolic names (tags) and some other
+things. For each revision, the revision number, the
+author, the number of lines added/deleted and the log
+message are printed. All times are displayed in
+Coordinated Universal Time (UTC). (Other parts of
address@hidden print times in the local timezone).
address@hidden FIXCVS: need a better way to control the timezone
address@hidden used in output. Previous/current versions of CVS did/do
address@hidden sometimes support -z in RCSINIT, and/or an
address@hidden undocumented (except by reference to 'rlog') -z option
address@hidden to cvs log, but this has not been a consistent,
address@hidden documented feature. Perhaps a new global option,
address@hidden where LT means the client's timezone, which the
address@hidden client then communicates to the server, is the
address@hidden right solution.
+
address@hidden: @code{log} uses @samp{-R} in a way that conflicts
+with the normal use inside @sc{cvs} (@pxref{Common options}).}
+
address@hidden
+* log options:: log options
+* log examples:: log examples
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden log options
address@hidden log options
+
+By default, @code{log} prints all information that is
+available. All other options restrict the output.
+
address@hidden @code
address@hidden -b
+Print information about the revisions on the default
+branch, normally the highest branch on the trunk.
+
address@hidden -d @var{dates}
+Print information about revisions with a checkin
+date/time in the range given by the
+semicolon-separated list of dates. The date formats
+accepted are those accepted by the @samp{-D} option to
+many other @sc{cvs} commands (@pxref{Common options}).
+Dates can be combined into ranges as follows:
+
address@hidden Should we be thinking about accepting ISO8601
address@hidden ranges? For example "1972-09-10/1972-09-12".
address@hidden @code
address@hidden @var{d1}<@var{d2}
address@hidden @var{d2}>@var{d1}
+Select the revisions that were deposited between
address@hidden and @var{d2}.
+
address@hidden <@var{d}
address@hidden @var{d}>
+Select all revisions dated @var{d} or earlier.
+
address@hidden @var{d}<
address@hidden >@var{d}
+Select all revisions dated @var{d} or later.
+
address@hidden @var{d}
+Select the single, latest revision dated @var{d} or
+earlier.
address@hidden table
+
+The @samp{>} or @samp{<} characters may be followed by
address@hidden to indicate an inclusive range rather than an
+exclusive one.
+
+Note that the separator is a semicolon (;).
+
address@hidden -h
+Print only the name of the @sc{rcs} file, name
+of the file in the working directory, head,
+default branch, access list, locks, symbolic names, and
+suffix.
+
address@hidden -l
+Local; run only in current working directory. (Default
+is to run recursively).
+
address@hidden -N
+Do not print the list of tags for this file. This
+option can be very useful when your site uses a lot of
+tags, so rather than "more"'ing over 3 pages of tag
+information, the log information is presented without
+tags at all.
+
address@hidden -R
+Print only the name of the @sc{rcs} file.
+
address@hidden Note that using a bare revision (in addition to not
address@hidden being explicitly documented here) is potentially
address@hidden confusing; it shows the log message to get from the
address@hidden previous revision to that revision. "-r1.3 -r1.6"
address@hidden (equivalent to "-r1.3,1.6") is even worse; it
address@hidden prints the messages to get from 1.2 to 1.3 and 1.5
address@hidden to 1.6. By analogy with "cvs diff", users might
address@hidden expect that it is more like specifying a range.
address@hidden It is not 100% clear to me how much of this should
address@hidden be documented (for example, multiple -r options
address@hidden perhaps could/should be deprecated given the false
address@hidden analogy with "cvs diff").
address@hidden In general, this section should be rewritten to talk
address@hidden about messages to get from revision rev1 to rev2,
address@hidden rather than messages for revision rev2 (that is, the
address@hidden messages are associated with a change not a static
address@hidden revision and failing to make this distinction causes
address@hidden much confusion).
address@hidden address@hidden
+Print information about revisions given in the
+comma-separated list @var{revisions} of revisions and
+ranges. The following table explains the available
+range formats:
+
address@hidden @code
address@hidden @var{rev1}:@var{rev2}
+Revisions @var{rev1} to @var{rev2} (which must be on
+the same branch).
+
address@hidden @var{rev1}::@var{rev2}
+The same, but excluding @var{rev1}.
+
address@hidden :@var{rev}
address@hidden ::@var{rev}
+Revisions from the beginning of the branch up to
+and including @var{rev}.
+
address@hidden @var{rev}:
+Revisions starting with @var{rev} to the end of the
+branch containing @var{rev}.
+
address@hidden @var{rev}::
+Revisions starting just after @var{rev} to the end of the
+branch containing @var{rev}.
+
address@hidden @var{branch}
+An argument that is a branch means all revisions on
+that branch.
+
address@hidden @var{branch1}:@var{branch2}
address@hidden @var{branch1}::@var{branch2}
+A range of branches means all revisions
+on the branches in that range.
+
address@hidden @var{branch}.
+The latest revision in @var{branch}.
address@hidden table
+
+A bare @samp{-r} with no revisions means the latest
+revision on the default branch, normally the trunk.
+There can be no space between the @samp{-r} option and
+its argument.
+
address@hidden -S
+Suppress the header if no revisions are selected.
+
address@hidden -s @var{states}
+Print information about revisions whose state
+attributes match one of the states given in the
+comma-separated list @var{states}.
+
address@hidden -t
+Print the same as @samp{-h}, plus the descriptive text.
+
address@hidden address@hidden
+Print information about revisions checked in by users
+with login names appearing in the comma-separated list
address@hidden If @var{logins} is omitted, the user's
+login is assumed. There can be no space between the
address@hidden option and its argument.
address@hidden table
+
address@hidden prints the intersection of the revisions
+selected with the options @samp{-d}, @samp{-s}, and
address@hidden, intersected with the union of the revisions
+selected by @samp{-b} and @samp{-r}.
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden log examples
address@hidden log examples
+
+Contributed examples are gratefully accepted.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden rdiff
address@hidden rdiff---'patch' format diffs between releases
address@hidden rdiff (subcommand)
+
address@hidden @bullet
address@hidden
+rdiff [-flags] [-V vn] [-r t|-D d [-r t2|-D d2]] address@hidden
address@hidden
+Requires: repository.
address@hidden
+Changes: nothing.
address@hidden
+Synonym: patch
address@hidden itemize
+
+Builds a Larry Wall format patch(1) file between two
+releases, that can be fed directly into the @code{patch}
+program to bring an old release up-to-date with the new
+release. (This is one of the few @sc{cvs} commands that
+operates directly from the repository, and doesn't
+require a prior checkout.) The diff output is sent to
+the standard output device.
+
+You can specify (using the standard @samp{-r} and
address@hidden options) any combination of one or two
+revisions or dates. If only one revision or date is
+specified, the patch file reflects differences between
+that revision or date and the current head revisions in
+the @sc{rcs} file.
+
+Note that if the software release affected is contained
+in more than one directory, then it may be necessary to
+specify the @samp{-p} option to the @code{patch} command when
+patching the old sources, so that @code{patch} is able to find
+the files that are located in other directories.
+
address@hidden
+* rdiff options:: rdiff options
+* rdiff examples:: rdiff examples
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden rdiff options
address@hidden rdiff options
+
+These standard options are supported by @code{rdiff}
+(@pxref{Common options}, for a complete description of
+them):
+
address@hidden @code
address@hidden -D @var{date}
+Use the most recent revision no later than @var{date}.
+
address@hidden -f
+If no matching revision is found, retrieve the most
+recent revision (instead of ignoring the file).
+
address@hidden -l
+Local; don't descend subdirectories.
+
address@hidden -R
+Examine directories recursively. This option is on by default.
+
address@hidden -r @var{tag}
+Use revision @var{tag}.
address@hidden table
+
+In addition to the above, these options are available:
+
address@hidden @code
address@hidden -c
+Use the context diff format. This is the default format.
+
address@hidden -s
+Create a summary change report instead of a patch. The
+summary includes information about files that were
+changed or added between the releases. It is sent to
+the standard output device. This is useful for finding
+out, for example, which files have changed between two
+dates or revisions.
+
address@hidden -t
+A diff of the top two revisions is sent to the standard
+output device. This is most useful for seeing what the
+last change to a file was.
+
address@hidden -u
+Use the unidiff format for the context diffs.
+Remember that old versions
+of the @code{patch} program can't handle the unidiff
+format, so if you plan to post this patch to the net
+you should probably not use @samp{-u}.
+
address@hidden -V @var{vn}
+Expand keywords according to the rules current in
address@hidden version @var{vn} (the expansion format changed with
address@hidden version 5). Note that this option is no
+longer accepted. @sc{cvs} will always expand keywords the
+way that @sc{rcs} version 5 does.
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden rdiff examples
address@hidden rdiff examples
+
+Suppose you receive mail from @t{foo@@example.net} asking for an
+update from release 1.2 to 1.4 of the tc compiler. You
+have no such patches on hand, but with @sc{cvs} that can
+easily be fixed with a command such as this:
+
address@hidden
+$ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \
+$$ Mail -s 'The patches you asked for' foo@@example.net
address@hidden example
+
+Suppose you have made release 1.3, and forked a branch
+called @samp{R_1_3fix} for bugfixes. @samp{R_1_3_1}
+corresponds to release 1.3.1, which was made some time
+ago. Now, you want to see how much development has been
+done on the branch. This command can be used:
+
address@hidden
+$ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name
+cvs rdiff: Diffing module-name
+File ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6
+File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4
+File bar.h,v changed from revision 1.29.2.1 to 1.2
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden release
address@hidden release---Indicate that a Module is no longer in use
address@hidden release (subcommand)
+
address@hidden @bullet
address@hidden
+release [-d] address@hidden
address@hidden
+Requires: Working directory.
address@hidden
+Changes: Working directory, history log.
address@hidden itemize
+
+This command is meant to safely cancel the effect of
address@hidden checkout}. Since @sc{cvs} doesn't lock files, it
+isn't strictly necessary to use this command. You can
+always simply delete your working directory, if you
+like; but you risk losing changes you may have
+forgotten, and you leave no trace in the @sc{cvs} history
+file (@pxref{history file}) that you've abandoned your
+checkout.
+
+Use @samp{cvs release} to avoid these problems. This
+command checks that no uncommitted changes are
+present; that you are executing it from immediately
+above a @sc{cvs} working directory; and that the repository
+recorded for your files is the same as the repository
+defined in the module database.
+
+If all these conditions are true, @samp{cvs release}
+leaves a record of its execution (attesting to your
+intentionally abandoning your checkout) in the @sc{cvs}
+history log.
+
address@hidden
+* release options:: release options
+* release output:: release output
+* release examples:: release examples
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden release options
address@hidden release options
+
+The @code{release} command supports one command option:
+
address@hidden @code
address@hidden -d
+Delete your working copy of the file if the release
+succeeds. If this flag is not given your files will
+remain in your working directory.
+
address@hidden: The @code{release} command deletes
+all directories and files recursively. This
+has the very serious side-effect that any directory
+that you have created inside your checked-out sources,
+and not added to the repository (using the @code{add}
+command; @pxref{Adding files}) will be silently deleted---even
+if it is non-empty!}
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden release output
address@hidden release output
+
+Before @code{release} releases your sources it will
+print a one-line message for any file that is not
+up-to-date.
+
address@hidden @code
address@hidden U @var{file}
address@hidden P @var{file}
+There exists a newer revision of this file in the
+repository, and you have not modified your local copy
+of the file (@samp{U} and @samp{P} mean the same thing).
+
address@hidden A @var{file}
+The file has been added to your private copy of the
+sources, but has not yet been committed to the
+repository. If you delete your copy of the sources
+this file will be lost.
+
address@hidden R @var{file}
+The file has been removed from your private copy of the
+sources, but has not yet been removed from the
+repository, since you have not yet committed the
+removal. @xref{commit}.
+
address@hidden M @var{file}
+The file is modified in your working directory. There
+might also be a newer revision inside the repository.
+
address@hidden ? @var{file}
address@hidden is in your working directory, but does not
+correspond to anything in the source repository, and is
+not in the list of files for @sc{cvs} to ignore (see the
+description of the @samp{-I} option, and
address@hidden). If you remove your working
+sources, this file will be lost.
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden release examples
address@hidden release examples
+
+Release the @file{tc} directory, and delete your local working copy
+of the files.
+
address@hidden
+$ cd .. # @r{You must stand immediately above the}
+ # @r{sources when you issue @samp{cvs release}.}
+$ cvs release -d tc
+You have [0] altered files in this repository.
+Are you sure you want to release (and delete) directory `tc': y
+$
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden update
address@hidden update---Bring work tree in sync with repository
address@hidden update (subcommand)
+
address@hidden @bullet
address@hidden
+update [-ACdflPpR] [-I name] [-j rev [-j rev]] [-k kflag] [-r tag|-D date] [-W
spec] address@hidden
address@hidden
+Requires: repository, working directory.
address@hidden
+Changes: working directory.
address@hidden itemize
+
+After you've run checkout to create your private copy
+of source from the common repository, other developers
+will continue changing the central source. From time
+to time, when it is convenient in your development
+process, you can use the @code{update} command from
+within your working directory to reconcile your work
+with any revisions applied to the source repository
+since your last checkout or update. Without the @code{-C}
+option, @code{update} will also merge any differences
+between the local copy of files and their base revisions
+into any destination revisions specified with @code{-r},
address@hidden, or @code{-A}.
+
address@hidden
+* update options:: update options
+* update output:: update output
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden update options
address@hidden update options
+
+These standard options are available with @code{update}
+(@pxref{Common options}, for a complete description of
+them):
+
address@hidden @code
address@hidden -D date
+Use the most recent revision no later than @var{date}.
+This option is sticky, and implies @samp{-P}.
+See @ref{Sticky tags}, for more information on sticky tags/dates.
+
address@hidden -f
+Only useful with the @samp{-D @var{date}} or @samp{-r
address@hidden flags. If no matching revision is found,
+retrieve the most recent revision (instead of ignoring
+the file).
+
address@hidden -k @var{kflag}
+Process keywords according to @var{kflag}. See
address@hidden substitution}.
+This option is sticky; future updates of
+this file in this working directory will use the same
address@hidden The @code{status} command can be viewed
+to see the sticky options. See @ref{Invoking CVS}, for
+more information on the @code{status} command.
+
address@hidden -l
+Local; run only in current working directory. @xref{Recursive behavior}.
+
address@hidden -P
+Prune empty directories. See @ref{Moving directories}.
+
address@hidden -p
+Pipe files to the standard output.
+
address@hidden -R
+Update directories recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r rev
+Retrieve revision/tag @var{rev}. This option is sticky,
+and implies @samp{-P}.
+See @ref{Sticky tags}, for more information on sticky tags/dates.
address@hidden table
+
address@hidden 800
+These special options are also available with
address@hidden
+
address@hidden @code
address@hidden -A
+Reset any sticky tags, dates, or @samp{-k} options.
+See @ref{Sticky tags}, for more information on sticky tags/dates.
+
address@hidden -C
+Overwrite locally modified files with clean copies from
+the repository (the modified file is saved in
address@hidden@address@hidden, however).
+
address@hidden -d
+Create any directories that exist in the repository if
+they're missing from the working directory. Normally,
address@hidden acts only on directories and files that
+were already enrolled in your working directory.
+
+This is useful for updating directories that were
+created in the repository since the initial checkout;
+but it has an unfortunate side effect. If you
+deliberately avoided certain directories in the
+repository when you created your working directory
+(either through use of a module name or by listing
+explicitly the files and directories you wanted on the
+command line), then updating with @samp{-d} will create
+those directories, which may not be what you want.
+
address@hidden -I @var{name}
+Ignore files whose names match @var{name} (in your
+working directory) during the update. You can specify
address@hidden more than once on the command line to specify
+several files to ignore. Use @samp{-I !} to avoid
+ignoring any files at all. @xref{cvsignore}, for other
+ways to make @sc{cvs} ignore some files.
+
address@hidden address@hidden
+Specify file names that should be filtered during
+update. You can use this option repeatedly.
+
address@hidden can be a file name pattern of the same type
+that you can specify in the @file{.cvswrappers}
+file. @xref{Wrappers}.
+
address@hidden address@hidden
+With two @samp{-j} options, merge changes from the
+revision specified with the first @samp{-j} option to
+the revision specified with the second @samp{j} option,
+into the working directory.
+
+With one @samp{-j} option, merge changes from the
+ancestor revision to the revision specified with the
address@hidden option, into the working directory. The
+ancestor revision is the common ancestor of the
+revision which the working directory is based on, and
+the revision specified in the @samp{-j} option.
+
+Note that using a single @samp{-j @var{tagname}} option rather than
address@hidden @var{branchname}} to merge changes from a branch will
+often not remove files which were removed on the branch.
address@hidden adds and removals}, for more.
+
+In addition, each @samp{-j} option can contain an optional
+date specification which, when used with branches, can
+limit the chosen revision to one within a specific
+date. An optional date is specified by adding a colon
+(:) to the tag:
address@hidden@var{Symbolic_Tag}:@var{Date_Specifier}}.
+
address@hidden and merging}.
+
address@hidden table
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden update output
address@hidden update output
+
address@hidden and @code{checkout} keep you informed of
+their progress by printing a line for each file, preceded
+by one character indicating the status of the file:
+
address@hidden @code
address@hidden U @var{file}
+The file was brought up to date with respect to the
+repository. This is done for any file that exists in
+the repository but not in your source, and for files
+that you haven't changed but are not the most recent
+versions available in the repository.
+
address@hidden P @var{file}
+Like @samp{U}, but the @sc{cvs} server sends a patch instead of an entire
+file. This accomplishes the same thing as @samp{U} using less bandwidth.
+
address@hidden A @var{file}
+The file has been added to your private copy of the
+sources, and will be added to the source repository
+when you run @code{commit} on the file. This is a
+reminder to you that the file needs to be committed.
+
address@hidden R @var{file}
+The file has been removed from your private copy of the
+sources, and will be removed from the source repository
+when you run @code{commit} on the file. This is a
+reminder to you that the file needs to be committed.
+
address@hidden M @var{file}
+The file is modified in your working directory.
+
address@hidden can indicate one of two states for a file
+you're working on: either there were no modifications
+to the same file in the repository, so that your file
+remains as you last saw it; or there were modifications
+in the repository as well as in your copy, but they
+were merged successfully, without conflict, in your
+working directory.
+
address@hidden will print some messages if it merges your work,
+and a backup copy of your working file (as it looked
+before you ran @code{update}) will be made. The exact
+name of that file is printed while @code{update} runs.
+
address@hidden C @var{file}
address@hidden .# files
address@hidden __ files (VMS)
+A conflict was detected while trying to merge your
+changes to @var{file} with changes from the source
+repository. @var{file} (the copy in your working
+directory) is now the result of attempting to merge
+the two revisions; an unmodified copy of your file
+is also in your working directory, with the name
address@hidden@address@hidden where @var{revision}
+is the revision that your modified file started
+from. Resolve the conflict as described in
address@hidden example}.
address@hidden "some systems" as in out-of-the-box OSes? Not as
address@hidden far as I know. We need to advise sysadmins as well
address@hidden as users how to set up this kind of purge, if that is
address@hidden what they want.
address@hidden We also might want to think about cleaner solutions,
address@hidden like having CVS remove the .# file once the conflict
address@hidden has been resolved or something like that.
+(Note that some systems automatically purge
+files that begin with @file{.#} if they have not been
+accessed for a few days. If you intend to keep a copy
+of your original file, it is a very good idea to rename
+it.) Under @sc{vms}, the file name starts with
address@hidden rather than @file{.#}.
+
address@hidden ? @var{file}
address@hidden is in your working directory, but does not
+correspond to anything in the source repository, and is
+not in the list of files for @sc{cvs} to ignore (see the
+description of the @samp{-I} option, and
address@hidden).
address@hidden table
+
address@hidden Invoking CVS
address@hidden Quick reference to CVS commands
address@hidden Command reference
address@hidden Reference, commands
address@hidden Invoking CVS
+
+This appendix describes how to invoke @sc{cvs}, with
+references to where each command or feature is
+described in detail. For other references run the
address@hidden --help} command, or see @ref{Index}.
+
+A @sc{cvs} command looks like:
+
address@hidden
+cvs [ @var{global_options} ] @var{command} [ @var{command_options} ] [
@var{command_args} ]
address@hidden example
+
+Global options:
+
address@hidden @code
address@hidden address@hidden
+Specify legal @sc{cvsroot} directory (server only) (not
+in @sc{cvs} 1.9 and older). See @ref{Password
+authentication server}.
+
address@hidden -a
+Authenticate all communication (client only) (not in @sc{cvs}
+1.9 and older). See @ref{Global options}.
+
address@hidden -b
+Specify RCS location (@sc{cvs} 1.9 and older). See
address@hidden options}.
+
address@hidden -d @var{root}
+Specify the @sc{cvsroot}. See @ref{Repository}.
+
address@hidden -e @var{editor}
+Edit messages with @var{editor}. See @ref{Committing
+your changes}.
+
address@hidden -f
+Do not read the @file{~/.cvsrc} file. See @ref{Global
+options}.
+
address@hidden -H
address@hidden --help
+Print a help message. See @ref{Global options}.
+
address@hidden -l
+Do not log in @file{$CVSROOT/CVSROOT/history} file. See @ref{Global
+options}.
+
address@hidden -n
+Do not change any files. See @ref{Global options}.
+
address@hidden -Q
+Be really quiet. See @ref{Global options}.
+
address@hidden -q
+Be somewhat quiet. See @ref{Global options}.
+
address@hidden -r
+Make new working files read-only. See @ref{Global options}.
+
address@hidden -s @address@hidden
+Set a user variable. See @ref{Variables}.
+
address@hidden -T @var{tempdir}
+Put temporary files in @var{tempdir}. See @ref{Global
+options}.
+
address@hidden -t
+Trace @sc{cvs} execution. See @ref{Global options}.
+
address@hidden -v
address@hidden --version
+Display version and copyright information for @sc{cvs}.
+
address@hidden -w
+Make new working files read-write. See @ref{Global
+options}.
+
address@hidden -x
+Encrypt all communication (client only).
+See @ref{Global options}.
+
address@hidden -z @var{gzip-level}
address@hidden Compression
address@hidden Gzip
+Set the compression level (client only).
+See @ref{Global options}.
address@hidden table
+
+Keyword expansion modes (@pxref{Substitution modes}):
+
address@hidden
+-kkv $ Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp $
+-kkvl $ Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
+-kk $ Id$
+-kv file1,v 1.1 1993/12/09 03:21:13 joe Exp
+-ko @i{no expansion}
+-kb @i{no expansion, file is binary}
address@hidden example
+
+Keywords (@pxref{Keyword list}):
+
address@hidden
+$ Author: joe $
+$ Date: 1993/12/09 03:21:13 $
+$ CVSHeader: files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
+$ Header: /home/files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
+$ Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
+$ Locker: harry $
+$ Name: snapshot_1_14 $
+$ RCSfile: file1,v $
+$ Revision: 1.1 $
+$ Source: /home/files/file1,v $
+$ State: Exp $
+$ Log: file1,v $
+Revision 1.1 1993/12/09 03:30:17 joe
+Initial revision
+
address@hidden example
+
address@hidden The idea behind this table is that we want each item
address@hidden to be a sentence or two at most. Preferably a
address@hidden single line.
address@hidden
address@hidden In some cases refs to "foo options" are just to get
address@hidden this thing written quickly, not because the "foo
address@hidden options" node is really the best place to point.
+Commands, command options, and command arguments:
+
address@hidden @code
address@hidden ------------------------------------------------------------
address@hidden add address@hidden address@hidden@dots{}]
+Add a new file/directory. See @ref{Adding files}.
+
address@hidden @code
address@hidden -k @var{kflag}
+Set keyword expansion.
+
address@hidden -m @var{msg}
+Set file description.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden admin address@hidden address@hidden@dots{}]
+Administration of history files in the repository. See
address@hidden
address@hidden This list omits those options which are not
address@hidden documented as being useful with CVS. That might be
address@hidden a mistake...
+
address@hidden @code
address@hidden address@hidden
+Set default branch. See @ref{Reverting local changes}.
+
address@hidden address@hidden
+Set comment leader.
+
address@hidden address@hidden
+Set keyword substitution. See @ref{Keyword
+substitution}.
+
address@hidden address@hidden
+Lock revision @var{rev}, or latest revision.
+
address@hidden address@hidden:@var{msg}
+Replace the log message of revision @var{rev} with
address@hidden
+
address@hidden address@hidden
+Delete revisions from the repository. See
address@hidden options}.
+
address@hidden -q
+Run quietly; do not print diagnostics.
+
address@hidden address@hidden:@var{rev}]
+Set the state.
+
address@hidden Does not work for client/server CVS
address@hidden -t
+Set file description from standard input.
+
address@hidden address@hidden
+Set file description from @var{file}.
+
address@hidden address@hidden
+Set file description to @var{string}.
+
address@hidden address@hidden
+Unlock revision @var{rev}, or latest revision.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden annotate address@hidden address@hidden@dots{}]
+Show last revision where each line was modified. See
address@hidden
+
address@hidden @code
address@hidden -D @var{date}
+Annotate the most recent revision no later than
address@hidden See @ref{Common options}.
+
address@hidden -F
+Force annotation of binary files. (Without this option,
+binary files are skipped with a message.)
+
address@hidden -f
+Use head revision if tag/date not found. See
address@hidden options}.
+
address@hidden -l
+Local; run only in current working directory. @xref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{tag}
+Annotate revision @var{tag}. See @ref{Common options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden checkout address@hidden @address@hidden
+Get a copy of the sources. See @ref{checkout}.
+
address@hidden @code
address@hidden -A
+Reset any sticky tags/date/options. See @ref{Sticky
+tags} and @ref{Keyword substitution}.
+
address@hidden -c
+Output the module database. See @ref{checkout options}.
+
address@hidden -D @var{date}
+Check out revisions as of @var{date} (is sticky). See
address@hidden options}.
+
address@hidden -d @var{dir}
+Check out into @var{dir}. See @ref{checkout options}.
+
address@hidden -f
+Use head revision if tag/date not found. See
address@hidden options}.
+
address@hidden Probably want to use rev1/rev2 style like for diff
address@hidden -r. Here and in on-line help.
address@hidden -j @var{rev}
+Merge in changes. See @ref{checkout options}.
+
address@hidden -k @var{kflag}
+Use @var{kflag} keyword expansion. See
address@hidden modes}.
+
address@hidden -l
+Local; run only in current working directory. @xref{Recursive behavior}.
+
address@hidden -N
+Don't ``shorten'' module paths if -d specified. See
address@hidden options}.
+
address@hidden -n
+Do not run module program (if any). See @ref{checkout options}.
+
address@hidden -P
+Prune empty directories. See @ref{Moving directories}.
+
address@hidden -p
+Check out files to standard output (avoids
+stickiness). See @ref{checkout options}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{tag}
+Checkout revision @var{tag} (is sticky). See @ref{Common options}.
+
address@hidden -s
+Like -c, but include module status. See @ref{checkout options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden commit address@hidden address@hidden@dots{}]
+Check changes into the repository. See @ref{commit}.
+
address@hidden @code
address@hidden -F @var{file}
+Read log message from @var{file}. See @ref{commit options}.
+
address@hidden -f
address@hidden What is this "disables recursion"? It is from the
address@hidden on-line help; is it documented in this manual?
+Force the file to be committed; disables recursion.
+See @ref{commit options}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -m @var{msg}
+Use @var{msg} as log message. See @ref{commit options}.
+
address@hidden -n
+Do not run module program (if any). See @ref{commit options}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{rev}
+Commit to @var{rev}. See @ref{commit options}.
address@hidden FIXME: should be dragging over text from
address@hidden commit options, especially if it can be cleaned up
address@hidden and made concise enough.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden diff address@hidden address@hidden@dots{}]
+Show differences between revisions. See @ref{diff}.
+In addition to the options shown below, accepts a wide
+variety of options to control output style, for example
address@hidden for context diffs.
+
address@hidden @code
address@hidden -D @var{date1}
+Diff revision for date against working file. See
address@hidden options}.
+
address@hidden -D @var{date2}
+Diff @var{rev1}/@var{date1} against @var{date2}. See
address@hidden options}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -N
+Include diffs for added and removed files. See
address@hidden options}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{rev1}
+Diff revision for @var{rev1} against working file. See
address@hidden options}.
+
address@hidden -r @var{rev2}
+Diff @var{rev1}/@var{date1} against @var{rev2}. See @ref{diff options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden edit address@hidden address@hidden@dots{}]
+Get ready to edit a watched file. See @ref{Editing files}.
+
address@hidden @code
address@hidden -a @var{actions}
+Specify actions for temporary watch, where
address@hidden is @code{edit}, @code{unedit},
address@hidden, @code{all}, or @code{none}. See
address@hidden files}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden editors address@hidden address@hidden@dots{}]
+See who is editing a watched file. See @ref{Watch information}.
+
address@hidden @code
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden export address@hidden @address@hidden
+Export files from @sc{cvs}. See @ref{export}.
+
address@hidden @code
address@hidden -D @var{date}
+Check out revisions as of @var{date}. See
address@hidden options}.
+
address@hidden -d @var{dir}
+Check out into @var{dir}. See @ref{export options}.
+
address@hidden -f
+Use head revision if tag/date not found. See
address@hidden options}.
+
address@hidden -k @var{kflag}
+Use @var{kflag} keyword expansion. See
address@hidden modes}.
+
address@hidden -l
+Local; run only in current working directory. @xref{Recursive behavior}.
+
address@hidden -N
+Don't ``shorten'' module paths if -d specified. See
address@hidden options}.
+
address@hidden -n
+Do not run module program (if any). See @ref{export options}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{tag}
+Checkout revision @var{tag}. See @ref{Common options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden history address@hidden address@hidden@dots{}]
+Show repository access history. See @ref{history}.
+
address@hidden @code
address@hidden -a
+All users (default is self). See @ref{history options}.
+
address@hidden -b @var{str}
+Back to record with @var{str} in module/file/repos
+field. See @ref{history options}.
+
address@hidden -c
+Report on committed (modified) files. See @ref{history options}.
+
address@hidden -D @var{date}
+Since @var{date}. See @ref{history options}.
+
address@hidden -e
+Report on all record types. See @ref{history options}.
+
address@hidden -l
+Last modified (committed or modified report). See @ref{history options}.
+
address@hidden -m @var{module}
+Report on @var{module} (repeatable). See @ref{history options}.
+
address@hidden -n @var{module}
+In @var{module}. See @ref{history options}.
+
address@hidden -o
+Report on checked out modules. See @ref{history options}.
+
address@hidden -p @var{repository}
+In @var{repository}. See @ref{history options}.
+
address@hidden -r @var{rev}
+Since revision @var{rev}. See @ref{history options}.
+
address@hidden -T
address@hidden What the @address@hidden is a TAG? Same as a tag? This
address@hidden wording is also in the online-line help.
+Produce report on all TAGs. See @ref{history options}.
+
address@hidden -t @var{tag}
+Since tag record placed in history file (by anyone).
+See @ref{history options}.
+
address@hidden -u @var{user}
+For user @var{user} (repeatable). See @ref{history options}.
+
address@hidden -w
+Working directory must match. See @ref{history options}.
+
address@hidden -x @var{types}
+Report on @var{types}, one or more of
address@hidden See @ref{history options}.
+
address@hidden -z @var{zone}
+Output for time zone @var{zone}. See @ref{history options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden import address@hidden @var{repository} @var{vendor-tag}
@address@hidden
+Import files into @sc{cvs}, using vendor branches. See
address@hidden
+
address@hidden @code
address@hidden -b @var{bra}
+Import to vendor branch @var{bra}. See
address@hidden vendor branches}.
+
address@hidden -d
+Use the file's modification time as the time of
+import. See @ref{import options}.
+
address@hidden -k @var{kflag}
+Set default keyword substitution mode. See
address@hidden options}.
+
address@hidden -m @var{msg}
+Use @var{msg} for log message. See
address@hidden options}.
+
address@hidden -I @var{ign}
+More files to ignore (! to reset). See
address@hidden options}.
+
address@hidden -W @var{spec}
+More wrappers. See @ref{import options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden init
+Create a @sc{cvs} repository if it doesn't exist. See
address@hidden a repository}.
+
address@hidden ------------------------------------------------------------
address@hidden kserver
+Kerberos authenticated server.
+See @ref{Kerberos authenticated}.
+
address@hidden ------------------------------------------------------------
address@hidden log address@hidden address@hidden@dots{}]
+Print out history information for files. See @ref{log}.
+
address@hidden @code
address@hidden -b
+Only list revisions on the default branch. See @ref{log options}.
+
address@hidden -d @var{dates}
+Specify dates (@var{d1}<@var{d2} for range, @var{d} for
+latest before). See @ref{log options}.
+
address@hidden -h
+Only print header. See @ref{log options}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -N
+Do not list tags. See @ref{log options}.
+
address@hidden -R
+Only print name of RCS file. See @ref{log options}.
+
address@hidden address@hidden
+Only list revisions @var{revs}. See @ref{log options}.
+
address@hidden -s @var{states}
+Only list revisions with specified states. See @ref{log options}.
+
address@hidden -t
+Only print header and descriptive text. See @ref{log
+options}.
+
address@hidden address@hidden
+Only list revisions checked in by specified logins. See @ref{log options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden login
+Prompt for password for authenticating server. See
address@hidden authentication client}.
+
address@hidden ------------------------------------------------------------
address@hidden logout
+Remove stored password for authenticating server. See
address@hidden authentication client}.
+
address@hidden ------------------------------------------------------------
address@hidden pserver
+Password authenticated server.
+See @ref{Password authentication server}.
+
address@hidden ------------------------------------------------------------
address@hidden rannotate address@hidden address@hidden@dots{}]
+Show last revision where each line was modified. See
address@hidden
+
address@hidden @code
address@hidden -D @var{date}
+Annotate the most recent revision no later than
address@hidden See @ref{Common options}.
+
address@hidden -F
+Force annotation of binary files. (Without this option,
+binary files are skipped with a message.)
+
address@hidden -f
+Use head revision if tag/date not found. See
address@hidden options}.
+
address@hidden -l
+Local; run only in current working directory. @xref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive behavior}.
+
address@hidden -r @var{tag}
+Annotate revision @var{tag}. See @ref{Common options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden rdiff address@hidden @address@hidden
+Show differences between releases. See @ref{rdiff}.
+
address@hidden @code
address@hidden -c
+Context diff output format (default). See @ref{rdiff options}.
+
address@hidden -D @var{date}
+Select revisions based on @var{date}. See @ref{Common options}.
+
address@hidden -f
+Use head revision if tag/date not found. See
address@hidden options}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{rev}
+Select revisions based on @var{rev}. See @ref{Common options}.
+
address@hidden -s
+Short patch - one liner per file. See @ref{rdiff options}.
+
address@hidden -t
+Top two diffs - last change made to the file. See
address@hidden options}.
+
address@hidden -u
+Unidiff output format. See @ref{rdiff options}.
+
address@hidden -V @var{vers}
+Use RCS Version @var{vers} for keyword expansion (obsolete). See
address@hidden options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden release address@hidden @var{directory}
+Indicate that a directory is no longer in use. See
address@hidden
+
address@hidden @code
address@hidden -d
+Delete the given directory. See @ref{release options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden remove address@hidden address@hidden@dots{}]
+Remove an entry from the repository. See @ref{Removing files}.
+
address@hidden @code
address@hidden -f
+Delete the file before removing it. See @ref{Removing files}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden rlog address@hidden address@hidden@dots{}]
+Print out history information for modules. See @ref{log}.
+
address@hidden @code
address@hidden -b
+Only list revisions on the default branch. See @ref{log options}.
+
address@hidden -d @var{dates}
+Specify dates (@var{d1}<@var{d2} for range, @var{d} for
+latest before). See @ref{log options}.
+
address@hidden -h
+Only print header. See @ref{log options}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -N
+Do not list tags. See @ref{log options}.
+
address@hidden -R
+Only print name of RCS file. See @ref{log options}.
+
address@hidden address@hidden
+Only list revisions @var{revs}. See @ref{log options}.
+
address@hidden -s @var{states}
+Only list revisions with specified states. See @ref{log options}.
+
address@hidden -t
+Only print header and descriptive text. See @ref{log options}.
+
address@hidden address@hidden
+Only list revisions checked in by specified logins. See @ref{log options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden rtag address@hidden @var{tag} @address@hidden
+Add a symbolic tag to a module.
+See @ref{Revisions} and @ref{Branching and merging}.
+
address@hidden @code
address@hidden -a
+Clear tag from removed files that would not otherwise
+be tagged. See @ref{Tagging add/remove}.
+
address@hidden -b
+Create a branch named @var{tag}. See @ref{Branching and merging}.
+
address@hidden -B
+Used in conjunction with -F or -d, enables movement and deletion of
+branch tags. Use with extreme caution.
+
address@hidden -D @var{date}
+Tag revisions as of @var{date}. See @ref{Tagging by date/tag}.
+
address@hidden -d
+Delete @var{tag}. See @ref{Modifying tags}.
+
address@hidden -F
+Move @var{tag} if it already exists. See @ref{Modifying tags}.
+
address@hidden -f
+Force a head revision match if tag/date not found.
+See @ref{Tagging by date/tag}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -n
+No execution of tag program. See @ref{Common options}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{rev}
+Tag existing tag @var{rev}. See @ref{Tagging by date/tag}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden server
+Rsh server. See @ref{Connecting via rsh}.
+
address@hidden ------------------------------------------------------------
address@hidden status address@hidden @address@hidden
+Display status information in a working directory. See
address@hidden status}.
+
address@hidden @code
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -v
+Include tag information for file. See @ref{Tags}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden tag address@hidden @var{tag} address@hidden@dots{}]
+Add a symbolic tag to checked out version of files.
+See @ref{Revisions} and @ref{Branching and merging}.
+
address@hidden @code
address@hidden -b
+Create a branch named @var{tag}. See @ref{Branching and merging}.
+
address@hidden -c
+Check that working files are unmodified. See
address@hidden the working directory}.
+
address@hidden -D @var{date}
+Tag revisions as of @var{date}. See @ref{Tagging by date/tag}.
+
address@hidden -d
+Delete @var{tag}. See @ref{Modifying tags}.
+
address@hidden -F
+Move @var{tag} if it already exists. See @ref{Modifying tags}.
+
address@hidden -f
+Force a head revision match if tag/date not found.
+See @ref{Tagging by date/tag}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{rev}
+Tag existing tag @var{rev}. See @ref{Tagging by date/tag}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden unedit address@hidden address@hidden@dots{}]
+Undo an edit command. See @ref{Editing files}.
+
address@hidden @code
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive behavior}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden update address@hidden address@hidden@dots{}]
+Bring work tree in sync with repository. See
address@hidden
+
address@hidden @code
address@hidden -A
+Reset any sticky tags/date/options. See @ref{Sticky
+tags} and @ref{Keyword substitution}.
+
address@hidden -C
+Overwrite locally modified files with clean copies from
+the repository (the modified file is saved in
address@hidden@address@hidden, however).
+
address@hidden -D @var{date}
+Check out revisions as of @var{date} (is sticky). See
address@hidden options}.
+
address@hidden -d
+Create directories. See @ref{update options}.
+
address@hidden -f
+Use head revision if tag/date not found. See
address@hidden options}.
+
address@hidden -I @var{ign}
+More files to ignore (! to reset). See
address@hidden options}.
+
address@hidden Probably want to use rev1/rev2 style like for diff
address@hidden -r. Here and in on-line help.
address@hidden -j @var{rev}
+Merge in changes. See @ref{update options}.
+
address@hidden -k @var{kflag}
+Use @var{kflag} keyword expansion. See
address@hidden modes}.
+
address@hidden -l
+Local; run only in current working directory. @xref{Recursive behavior}.
+
address@hidden -P
+Prune empty directories. See @ref{Moving directories}.
+
address@hidden -p
+Check out files to standard output (avoids
+stickiness). See @ref{update options}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
+
address@hidden -r @var{tag}
+Checkout revision @var{tag} (is sticky). See @ref{Common options}.
+
address@hidden -W @var{spec}
+More wrappers. See @ref{import options}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden version
address@hidden version (subcommand)
+
+Display the version of @sc{cvs} being used. If the repository
+is remote, display both the client and server versions.
+
address@hidden ------------------------------------------------------------
address@hidden watch [on|off|add|remove] address@hidden address@hidden@dots{}]
+
+on/off: turn on/off read-only checkouts of files. See
address@hidden a watch}.
+
+add/remove: add or remove notification on actions. See
address@hidden Notified}.
+
address@hidden @code
address@hidden -a @var{actions}
+Specify actions for temporary watch, where
address@hidden is @code{edit}, @code{unedit},
address@hidden, @code{all}, or @code{none}. See
address@hidden files}.
+
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
address@hidden table
+
address@hidden ------------------------------------------------------------
address@hidden watchers address@hidden address@hidden@dots{}]
+See who is watching a file. See @ref{Watch information}.
+
address@hidden @code
address@hidden -l
+Local; run only in current working directory. See @ref{Recursive behavior}.
+
address@hidden -R
+Operate recursively (default). @xref{Recursive
+behavior}.
address@hidden table
+
address@hidden table
+
address@hidden
---------------------------------------------------------------------
address@hidden Administrative files
address@hidden Reference manual for Administrative files
address@hidden Administrative files (reference)
address@hidden Files, reference manual
address@hidden Reference manual (files)
address@hidden CVSROOT (file)
+
address@hidden FIXME? Somewhere there needs to be a more "how-to"
address@hidden guide to writing these. I think the triggers
address@hidden (commitinfo, loginfo, taginfo, &c) are perhaps a
address@hidden different case than files like modules. One
address@hidden particular issue that people sometimes are
address@hidden (unnecessarily?) worried about is performance, and
address@hidden the impact of writing in perl or sh or ____.
+Inside the repository, in the directory
address@hidden/CVSROOT}, there are a number of
+supportive files for @sc{cvs}. You can use @sc{cvs} in a limited
+fashion without any of them, but if they are set up
+properly they can help make life easier. For a
+discussion of how to edit them, see @ref{Intro
+administrative files}.
+
+The most important of these files is the @file{modules}
+file, which defines the modules inside the repository.
+
address@hidden
+* modules:: Defining modules
+* Wrappers:: Specify binary-ness based on file name
+* commit files:: The commit support files (commitinfo,
+ verifymsg, editinfo, loginfo)
+* rcsinfo:: Templates for the log messages
+* cvsignore:: Ignoring files via cvsignore
+* checkoutlist:: Adding your own administrative files
+* history file:: History information
+* Variables:: Various variables are expanded
+* config:: Miscellaneous CVS configuration
address@hidden menu
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden modules
address@hidden The modules file
address@hidden Modules (admin file)
address@hidden Defining modules (reference manual)
+
+The @file{modules} file records your definitions of
+names for collections of source code. @sc{cvs} will
+use these definitions if you use @sc{cvs} to update the
+modules file (use normal commands like @code{add},
address@hidden, etc).
+
+The @file{modules} file may contain blank lines and
+comments (lines beginning with @samp{#}) as well as
+module definitions. Long lines can be continued on the
+next line by specifying a backslash (@samp{\}) as the
+last character on the line.
+
+There are three basic types of modules: alias modules,
+regular modules, and ampersand modules. The difference
+between them is the way that they map files in the
+repository to files in the working directory. In all
+of the following examples, the top-level repository
+contains a directory called @file{first-dir}, which
+contains two files, @file{file1} and @file{file2}, and a
+directory @file{sdir}. @file{first-dir/sdir} contains
+a file @file{sfile}.
+
address@hidden FIXME: should test all the examples in this section.
+
address@hidden
+* Alias modules:: The simplest kind of module
+* Regular modules::
+* Ampersand modules::
+* Excluding directories:: Excluding directories from a module
+* Module options:: Regular and ampersand modules can take options
+* Module program options:: How the modules ``program options'' programs
+ are run.
address@hidden menu
+
address@hidden Alias modules
address@hidden Alias modules
address@hidden Alias modules
address@hidden -a, in modules file
+
+Alias modules are the simplest kind of module:
+
address@hidden @code
address@hidden @var{mname} -a @address@hidden
+This represents the simplest way of defining a module
address@hidden The @samp{-a} flags the definition as a
+simple alias: @sc{cvs} will treat any use of @var{mname} (as
+a command argument) as if the list of names
address@hidden had been specified instead.
address@hidden may contain either other module names or
+paths. When you use paths in aliases, @code{checkout}
+creates all intermediate directories in the working
+directory, just as if the path had been specified
+explicitly in the @sc{cvs} arguments.
address@hidden table
+
+For example, if the modules file contains:
+
address@hidden
+amodule -a first-dir
address@hidden example
+
address@hidden
+then the following two commands are equivalent:
+
address@hidden
+$ cvs co amodule
+$ cvs co first-dir
address@hidden example
+
address@hidden
+and they each would provide output such as:
+
address@hidden
+cvs checkout: Updating first-dir
+U first-dir/file1
+U first-dir/file2
+cvs checkout: Updating first-dir/sdir
+U first-dir/sdir/sfile
address@hidden example
+
address@hidden Regular modules
address@hidden Regular modules
address@hidden Regular modules
+
address@hidden @code
address@hidden @var{mname} [ options ] @var{dir} [ @address@hidden ]
+In the simplest case, this form of module definition
+reduces to @address@hidden @var{dir}}. This defines
+all the files in directory @var{dir} as module mname.
address@hidden is a relative path (from @code{$CVSROOT}) to a
+directory of source in the source repository. In this
+case, on checkout, a single directory called
address@hidden is created as a working directory; no
+intermediate directory levels are used by default, even
+if @var{dir} was a path involving several directory
+levels.
address@hidden table
+
+For example, if a module is defined by:
+
address@hidden
+regmodule first-dir
address@hidden example
+
address@hidden
+then regmodule will contain the files from first-dir:
+
address@hidden
+$ cvs co regmodule
+cvs checkout: Updating regmodule
+U regmodule/file1
+U regmodule/file2
+cvs checkout: Updating regmodule/sdir
+U regmodule/sdir/sfile
+$
address@hidden example
+
+By explicitly specifying files in the module definition
+after @var{dir}, you can select particular files from
+directory @var{dir}. Here is
+an example:
+
address@hidden
+regfiles first-dir/sdir sfile
address@hidden example
+
address@hidden
+With this definition, getting the regfiles module
+will create a single working directory
address@hidden containing the file listed, which
+comes from a directory deeper
+in the @sc{cvs} source repository:
+
address@hidden
+$ cvs co regfiles
+U regfiles/sfile
+$
address@hidden example
+
address@hidden Ampersand modules
address@hidden Ampersand modules
address@hidden Ampersand modules
address@hidden &, in modules file
+
+A module definition can refer to other modules by
+including @samp{&@var{module}} in its definition.
address@hidden
address@hidden [ options ] @var{&address@hidden
address@hidden example
+
+Then getting the module creates a subdirectory for each such
+module, in the directory containing the module. For
+example, if modules contains
+
address@hidden
+ampermod &first-dir
address@hidden example
+
address@hidden
+then a checkout will create an @code{ampermod} directory
+which contains a directory called @code{first-dir},
+which in turns contains all the directories and files
+which live there. For example, the command
+
address@hidden
+$ cvs co ampermod
address@hidden example
+
address@hidden
+will create the following files:
+
address@hidden
+ampermod/first-dir/file1
+ampermod/first-dir/file2
+ampermod/first-dir/sdir/sfile
address@hidden example
+
+There is one quirk/bug: the messages that @sc{cvs}
+prints omit the @file{ampermod}, and thus do not
+correctly display the location to which it is checking
+out the files:
+
address@hidden
+$ cvs co ampermod
+cvs checkout: Updating first-dir
+U first-dir/file1
+U first-dir/file2
+cvs checkout: Updating first-dir/sdir
+U first-dir/sdir/sfile
+$
address@hidden example
+
+Do not rely on this buggy behavior; it may get fixed in
+a future release of @sc{cvs}.
+
address@hidden FIXCVS: What happens if regular and & modules are
address@hidden combined, as in "ampermodule first-dir &second-dir"?
address@hidden When I tried it, it seemed to just ignore the
address@hidden "first-dir". I think perhaps it should be an error
address@hidden (but this needs further investigation).
address@hidden In addition to discussing what each one does, we
address@hidden should put in a few words about why you would use one or
address@hidden the other in various situations.
+
address@hidden Excluding directories
address@hidden Excluding directories
address@hidden Excluding directories, in modules file
address@hidden !, in modules file
+
+An alias module may exclude particular directories from
+other modules by using an exclamation mark (@samp{!})
+before the name of each directory to be excluded.
+
+For example, if the modules file contains:
+
address@hidden
+exmodule -a !first-dir/sdir first-dir
address@hidden example
+
address@hidden
+then checking out the module @samp{exmodule} will check
+out everything in @samp{first-dir} except any files in
+the subdirectory @samp{first-dir/sdir}.
address@hidden Note that the "!first-dir/sdir" sometimes must be listed
address@hidden before "first-dir". That seems like a probable bug, in which
address@hidden case perhaps it should be fixed (to allow either
address@hidden order) rather than documented. See modules4 in testsuite.
+
address@hidden Module options
address@hidden Module options
address@hidden Options, in modules file
+
+Either regular modules or ampersand modules can contain
+options, which supply additional information concerning
+the module.
+
address@hidden @code
address@hidden -d, in modules file
address@hidden -d @var{name}
+Name the working directory something other than the
+module name.
address@hidden FIXME: Needs a bunch of examples, analogous to the
address@hidden examples for alias, regular, and ampersand modules
address@hidden which show where the files go without -d.
+
address@hidden Export program
address@hidden -e, in modules file
address@hidden -e @var{prog}
+Specify a program @var{prog} to run whenever files in a
+module are exported. @var{prog} runs with a single
+argument, the module name.
address@hidden FIXME: Is it run on server? client?
+
address@hidden Checkout program
address@hidden -o, in modules file
address@hidden -o @var{prog}
+Specify a program @var{prog} to run whenever files in a
+module are checked out. @var{prog} runs with a single
+argument, the module name. See @ref{Module program options} for
+information on how @var{prog} is called.
address@hidden FIXME: Is it run on server? client?
+
address@hidden Status of a module
address@hidden Module status
address@hidden -s, in modules file
address@hidden -s @var{status}
+Assign a status to the module. When the module file is
+printed with @samp{cvs checkout -s} the modules are
+sorted according to primarily module status, and
+secondarily according to the module name. This option
+has no other meaning. You can use this option for
+several things besides status: for instance, list the
+person that is responsible for this module.
+
address@hidden Tag program
address@hidden -t, in modules file
address@hidden -t @var{prog}
+Specify a program @var{prog} to run whenever files in a
+module are tagged with @code{rtag}. @var{prog} runs
+with two arguments: the module name and the symbolic
+tag specified to @code{rtag}. It is not run
+when @code{tag} is executed. Generally you will find
+that taginfo is a better solution (@pxref{user-defined logging}).
address@hidden FIXME: Is it run on server? client?
address@hidden Problems with -t include:
address@hidden * It is run after the tag not before
address@hidden * It doesn't get passed all the information that
address@hidden taginfo does ("mov", &c).
address@hidden * It only is run for rtag, not tag.
address@hidden table
+
+You should also see @pxref{Module program options} about how the
+``program options'' programs are run.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
+
address@hidden Module program options
address@hidden How the modules file ``program options'' programs are run
address@hidden Modules file program options
address@hidden -t, in modules file
address@hidden -o, in modules file
address@hidden -e, in modules file
+
address@hidden
+For checkout, rtag, and export, the program is server-based, and as such the
+following applies:-
+
+If using remote access methods (pserver, ext, etc.),
address@hidden will execute this program on the server from a temporary
+directory. The path is searched for this program.
+
+If using ``local access'' (on a local or remote NFS file system, i.e.
+repository set just to a path),
+the program will be executed from the newly checked-out tree, if
+found there, or alternatively searched for in the path if not.
+
+The programs are all run after the operation has effectively
+completed.
+
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden Wrappers
address@hidden The cvswrappers file
address@hidden cvswrappers (admin file)
address@hidden CVSWRAPPERS, environment variable
address@hidden Wrappers
+
address@hidden FIXME: need some better way of separating this out
address@hidden by functionality. -m is
address@hidden one feature, and -k is a another. And this discussion
address@hidden should be better motivated (e.g. start with the
address@hidden problems, then explain how the feature solves it).
+
+Wrappers refers to a @sc{cvs} feature which lets you
+control certain settings based on the name of the file
+which is being operated on. The settings are @samp{-k}
+for binary files, and @samp{-m} for nonmergeable text
+files.
+
+The @samp{-m} option
+specifies the merge methodology that should be used when
+a non-binary file is updated. @code{MERGE} means the usual
address@hidden behavior: try to merge the files. @code{COPY}
+means that @code{cvs update} will refuse to merge
+files, as it also does for files specified as binary
+with @samp{-kb} (but if the file is specified as
+binary, there is no need to specify @samp{-m 'COPY'}).
address@hidden will provide the user with the
+two versions of the files, and require the user using
+mechanisms outside @sc{cvs}, to insert any necessary
+changes.
+
address@hidden: do not use @code{COPY} with
address@hidden 1.9 or earlier - such versions of @sc{cvs} will
+copy one version of your file over the other, wiping
+out the previous contents.}
address@hidden Ordinarily we don't document the behavior of old
address@hidden versions. But this one is so dangerous, I think we
address@hidden must. I almost renamed it to -m 'NOMERGE' so we
address@hidden could say "never use -m 'COPY'".
+The @samp{-m} wrapper option only affects behavior when
+merging is done on update; it does not affect how files
+are stored. See @ref{Binary files}, for more on
+binary files.
+
+The basic format of the file @file{cvswrappers} is:
+
address@hidden FIXME: @example is all wrong for this. Use @deffn or
address@hidden something more sensible.
address@hidden
+wildcard [option value][option value]...
+
+where option is one of
+-m update methodology value: MERGE or COPY
+-k keyword expansion value: expansion mode
+
+and value is a single-quote delimited value.
address@hidden example
+
+
address@hidden FIXME: We don't document -W or point to where it is
address@hidden documented. Or .cvswrappers.
+For example, the following command imports a
+directory, treating files whose name ends in
address@hidden as binary:
+
address@hidden
+cvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag
address@hidden example
+
address@hidden Another good example, would be storing files
address@hidden (e.g. binary files) compressed in the repository.
address@hidden ::::::::::::::::::
address@hidden cvswrappers
address@hidden ::::::::::::::::::
address@hidden *.t12 -m 'COPY'
address@hidden *.t[0-9][0-9] -f 'gunzipcp %s' -t 'gzipcp %s %s' -m 'COPY'
address@hidden
address@hidden ::::::::::::::::::
address@hidden gunzipcp
address@hidden ::::::::::::::::::
address@hidden :
address@hidden [ -f $1 ] || exit 1
address@hidden zcat $1 > /tmp/.#$1.$$
address@hidden mv /tmp/.#$1.$$ $1
address@hidden
address@hidden ::::::::::::::::::
address@hidden gzipcp
address@hidden ::::::::::::::::::
address@hidden :
address@hidden DIRNAME=`echo $1 | sed -e "s|/.*/||g"`
address@hidden if [ ! -d $DIRNAME ] ; then
address@hidden DIRNAME=`echo $1 | sed -e "s|.*/||g"`
address@hidden fi
address@hidden gzip -c $DIRNAME > $2
address@hidden One catch--"cvs diff" will not invoke the wrappers
address@hidden (probably a CVS bug, although I haven't thought it out).
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden commit files
address@hidden The commit support files
address@hidden Committing, administrative support files
+
+The @samp{-i} flag in the @file{modules} file can be
+used to run a certain program whenever files are
+committed (@pxref{modules}). The files described in
+this section provide other, more flexible, ways to run
+programs whenever something is committed.
+
+There are three kind of programs that can be run on
+commit. They are specified in files in the repository,
+as described below. The following table summarizes the
+file names and the purpose of the corresponding
+programs.
+
address@hidden @file
address@hidden commitinfo
+The program is responsible for checking that the commit
+is allowed. If it exits with a non-zero exit status
+the commit will be aborted.
+
address@hidden verifymsg
+The specified program is used to evaluate the log message,
+and possibly verify that it contains all required
+fields. This is most useful in combination with the
address@hidden file, which can hold a log message
+template (@pxref{rcsinfo}).
+
address@hidden editinfo
+The specified program is used to edit the log message,
+and possibly verify that it contains all required
+fields. This is most useful in combination with the
address@hidden file, which can hold a log message
+template (@pxref{rcsinfo}). (obsolete)
+
address@hidden loginfo
+The specified program is called when the commit is
+complete. It receives the log message and some
+additional information and can store the log message in
+a file, or mail it to appropriate persons, or maybe
+post it to a local newsgroup, address@hidden Your
+imagination is the limit!
address@hidden table
+
address@hidden
+* syntax:: The common syntax
+* commitinfo:: Pre-commit checking
+* verifymsg:: How are log messages evaluated?
+* editinfo:: Specifying how log messages are created
+ (obsolete)
+* loginfo:: Where should log messages be sent?
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden syntax
address@hidden The common syntax
address@hidden Info files (syntax)
address@hidden Syntax of info files
address@hidden Common syntax of info files
+
address@hidden FIXME: having this so totally separate from the
address@hidden Variables node is rather bogus.
+
+The administrative files such as @file{commitinfo},
address@hidden, @file{rcsinfo}, @file{verifymsg}, etc.,
+all have a common format. The purpose of the files are
+described later on. The common syntax is described
+here.
+
address@hidden Regular expression syntax
+Each line contains the following:
address@hidden @bullet
address@hidden
address@hidden Say anything about DEFAULT and ALL? Right now we
address@hidden leave that to the description of each file (and in fact
address@hidden the practice is inconsistent which is really annoying).
+A regular expression. This is a basic regular
+expression in the syntax used by GNU emacs.
address@hidden FIXME: What we probably should be saying is "POSIX Basic
address@hidden Regular Expression with the following extensions (`\('
address@hidden `\|' '+' etc)"
address@hidden rather than define it with reference to emacs.
address@hidden The reference to emacs is not strictly speaking
address@hidden true, as we don't support \=, \s, or \S. Also it isn't
address@hidden clear we should document and/or promise to continue to
address@hidden support all the obscure emacs extensions like \<.
address@hidden Also need to better cite (or include) full
address@hidden documentation for the syntax.
address@hidden Also see comment in configure.in about what happens to the
address@hidden syntax if we pick up a system-supplied regexp matcher.
+
address@hidden
+A whitespace separator---one or more spaces and/or tabs.
+
address@hidden
+A file name or command-line template.
address@hidden itemize
+
address@hidden
+Blank lines are ignored. Lines that start with the
+character @samp{#} are treated as comments. Long lines
+unfortunately can @emph{not} be broken in two parts in
+any way.
+
+The first regular expression that matches the current
+directory name in the repository is used. The rest of the line
+is used as a file name or command-line as appropriate.
+
address@hidden FIXME: need an example. In particular, show what
address@hidden the regular expression is matched against (one
address@hidden ordinarily clueful person got confused about whether it
address@hidden includes the filename--"directory name" above should be
address@hidden unambiguous but there is nothing like an example to
address@hidden confirm people's understanding of this sort of thing).
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden commitinfo
address@hidden Commitinfo
address@hidden @file{commitinfo}
address@hidden Commits, precommit verification of
address@hidden Precommit checking
+
+The @file{commitinfo} file defines programs to execute
+whenever @samp{cvs commit} is about to execute. These
+programs are used for pre-commit checking to verify
+that the modified, added and removed files are really
+ready to be committed. This could be used, for
+instance, to verify that the changed files conform to
+to your site's standards for coding practice.
+
+As mentioned earlier, each line in the
address@hidden file consists of a regular expression
+and a command-line template. The template can include
+a program name and any number of arguments you wish to
+supply to it. The full path to the current source
+repository is appended to the template, followed by the
+file names of any files involved in the commit (added,
+removed, and modified files).
+
address@hidden Exit status, of commitinfo
+The first line with a regular expression matching the
+directory within the repository will be used. If the
+command returns a non-zero exit status the commit will
+be aborted.
address@hidden FIXME: need example(s) of what "directory within the
address@hidden repository" means.
+
address@hidden DEFAULT in commitinfo
+If the repository name does not match any of the
+regular expressions in this file, the @samp{DEFAULT}
+line is used, if it is specified.
+
address@hidden ALL in commitinfo
+All occurrences of the name @samp{ALL} appearing as a
+regular expression are used in addition to the first
+matching regular expression or the name @samp{DEFAULT}.
+
address@hidden @file{commitinfo}, working directory
address@hidden @file{commitinfo}, command environment
+The command will be run in the root of the workspace
+containing the new versions of any files the user would like
+to modify (commit), @emph{or in a copy of the workspace on
+the server (@pxref{Remote repositories})}. If a file is
+being removed, there will be no copy of the file under the
+current directory. If a file is being added, there will be
+no corresponding archive file in the repository unless the
+file is being resurrected.
+
+Note that both the repository directory and the corresponding
+Attic (@pxref{Attic}) directory may need to be checked to
+locate the archive file corresponding to any given file being
+committed. Much of the information about the specific commit
+request being made, including the destination branch, commit
+message, and command line options specified, is not available
+to the command.
+
address@hidden FIXME: should discuss using commitinfo to control
address@hidden who has checkin access to what (e.g. Joe can check into
address@hidden directories a, b, and c, and Mary can check into
address@hidden directories b, c, and d--note this case cannot be
address@hidden conveniently handled with unix groups). Of course,
address@hidden adding a new set of features to CVS might be a more
address@hidden natural way to fix this problem than telling people to
address@hidden use commitinfo.
address@hidden FIXME: Should make some reference, especially in
address@hidden the context of controlling who has access, to the fact
address@hidden that commitinfo can be circumvented. Perhaps
address@hidden mention SETXID (but has it been carefully examined
address@hidden for holes?). This fits in with the discussion of
address@hidden general CVS security in "Password authentication
address@hidden security" (the bit which is not pserver-specific).
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden verifymsg
address@hidden Verifying log messages
address@hidden @file{verifymsg} (admin file)
address@hidden Log message, verifying
+
+Once you have entered a log message, you can evaluate
+that message to check for specific content, such as
+a bug ID. Use the @file{verifymsg} file to
+specify a program that is used to verify the log message.
+This program could be a simple script that checks
+that the entered message contains the required fields.
+
+The @file{verifymsg} file is often most useful together
+with the @file{rcsinfo} file, which can be used to
+specify a log message template.
+
+Each line in the @file{verifymsg} file consists of a
+regular expression and a command-line template. The
+template must include a program name, and can include
+any number of arguments. The full path to the current
+log message template file is appended to the template.
+
+One thing that should be noted is that the @samp{ALL}
+keyword is not supported. If more than one matching
+line is found, the first one is used. This can be
+useful for specifying a default verification script in a
+directory, and then overriding it in a subdirectory.
+
address@hidden DEFAULT in @file{verifymsg}
+If the repository name does not match any of the
+regular expressions in this file, the @samp{DEFAULT}
+line is used, if it is specified.
+
address@hidden Exit status, of @file{verifymsg}
+If the verification script exits with a non-zero exit status,
+the commit is aborted.
+
address@hidden @file{verifymsg}, changing the log message
+In the default configuration, CVS allows the
+verification script to change the log message. This is
+controlled via the RereadLogAfterVerify CVSROOT/config
+option.
+
+When @samp{RereadLogAfterVerify=always} or
address@hidden, the log message will
+either always be reread after the verification script
+is run or reread only if the log message file status
+has changed.
+
address@hidden, for more on CVSROOT/config options.
+
+It is NOT a good idea for a @file{verifymsg} script to
+interact directly with the user in the various
+client/server methods. For the @code{pserver} method,
+there is no protocol support for communicating between
address@hidden and the client on the remote end. For the
address@hidden and @code{server} methods, it is possible
+for CVS to become confused by the characters going
+along the same channel as the CVS protocol
+messages. See @ref{Remote repositories}, for more
+information on client/server setups. In addition, at the time
+the @file{verifymsg} script runs, the CVS
+server has locks in place in the repository. If control is
+returned to the user here then other users may be stuck waiting
+for access to the repository.
+
+This option can be useful if you find yourself using an
+rcstemplate that needs to be modified to remove empty
+elements or to fill in default values. It can also be
+useful if the rcstemplate has changed in the repository
+and the CVS/Template was not updated, but is able to be
+adapted to the new format by the verification script
+that is run by @file{verifymsg}.
+
+An example of an update might be to change all
+occurrences of 'BugId:' to be 'DefectId:' (which can be
+useful if the rcstemplate has recently been changed and
+there are still checked-out user trees with cached
+copies in the CVS/Template file of the older version).
+
+Another example of an update might be to delete a line
+that contains 'BugID: none' from the log message after
+validation of that value as being allowed is made.
+
+The following is a little silly example of a
address@hidden file, together with the corresponding
address@hidden file, the log message template and an
+verification script. We begin with the log message template.
+We want to always record a bug-id number on the first
+line of the log message. The rest of log message is
+free text. The following template is found in the file
address@hidden/usr/cvssupport/tc.template}.
+
address@hidden
+BugId:
address@hidden example
+
+The script @file{/usr/cvssupport/bugid.verify} is used to
+evaluate the log message.
+
address@hidden
+#!/bin/sh
+#
+# bugid.verify filename
+#
+# Verify that the log message contains a valid bugid
+# on the first line.
+#
+if head -1 < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then
+ exit 0
+elif head -1 < $1 | grep '^BugId:[ ]*none$' > /dev/null; then
+ # It is okay to allow commits with 'BugId: none',
+ # but do not put that text into the real log message.
+ grep -v '^BugId:[ ]*none$' > $1.rewrite
+ mv $1.rewrite $1
+ exit 0
+else
+ echo "No BugId found."
+ exit 1
+fi
address@hidden example
+
+The @file{verifymsg} file contains this line:
+
address@hidden
+^tc /usr/cvssupport/bugid.verify
address@hidden example
+
+The @file{rcsinfo} file contains this line:
+
address@hidden
+^tc /usr/cvssupport/tc.template
address@hidden example
+
+The @file{config} file contains this line:
+
address@hidden
+RereadLogAfterVerify=always
address@hidden example
+
+
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden editinfo
address@hidden Editinfo
address@hidden editinfo (admin file)
address@hidden Editor, specifying per module
address@hidden Per-module editor
address@hidden Log messages, editing
+
address@hidden: The @file{editinfo} feature has been
+rendered obsolete. To set a default editor for log
+messages use the @code{CVSEDITOR}, @code{EDITOR} environment variables
+(@pxref{Environment variables}) or the @samp{-e} global
+option (@pxref{Global options}). See @ref{verifymsg},
+for information on the use of the @file{verifymsg}
+feature for evaluating log messages.}
+
+If you want to make sure that all log messages look the
+same way, you can use the @file{editinfo} file to
+specify a program that is used to edit the log message.
+This program could be a custom-made editor that always
+enforces a certain style of the log message, or maybe a
+simple shell script that calls an editor, and checks
+that the entered message contains the required fields.
+
+If no matching line is found in the @file{editinfo}
+file, the editor specified in the environment variable
address@hidden is used instead. If that variable is
+not set, then the environment variable @code{$EDITOR}
+is used instead. If that variable is not
+set a default will be used. See @ref{Committing your changes}.
+
+The @file{editinfo} file is often most useful together
+with the @file{rcsinfo} file, which can be used to
+specify a log message template.
+
+Each line in the @file{editinfo} file consists of a
+regular expression and a command-line template. The
+template must include a program name, and can include
+any number of arguments. The full path to the current
+log message template file is appended to the template.
+
+One thing that should be noted is that the @samp{ALL}
+keyword is not supported. If more than one matching
+line is found, the first one is used. This can be
+useful for specifying a default edit script in a
+module, and then overriding it in a subdirectory.
+
address@hidden DEFAULT in editinfo
+If the repository name does not match any of the
+regular expressions in this file, the @samp{DEFAULT}
+line is used, if it is specified.
+
+If the edit script exits with a non-zero exit status,
+the commit is aborted.
+
+Note: when @sc{cvs} is accessing a remote repository,
+or when the @samp{-m} or @samp{-F} options to @code{cvs
+commit} are used, @file{editinfo} will not be consulted.
+There is no good workaround for this; use
address@hidden instead.
+
address@hidden
+* editinfo example:: Editinfo example
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden editinfo example
address@hidden Editinfo example
+
+The following is a little silly example of a
address@hidden file, together with the corresponding
address@hidden file, the log message template and an
+editor script. We begin with the log message template.
+We want to always record a bug-id number on the first
+line of the log message. The rest of log message is
+free text. The following template is found in the file
address@hidden/usr/cvssupport/tc.template}.
+
address@hidden
+BugId:
address@hidden example
+
+The script @file{/usr/cvssupport/bugid.edit} is used to
+edit the log message.
+
address@hidden
+#!/bin/sh
+#
+# bugid.edit filename
+#
+# Call $EDITOR on FILENAME, and verify that the
+# resulting file contains a valid bugid on the first
+# line.
+if [ "x$EDITOR" = "x" ]; then EDITOR=vi; fi
+if [ "x$CVSEDITOR" = "x" ]; then CVSEDITOR=$EDITOR; fi
+$CVSEDITOR $1
+until head -1|grep '^BugId:[ ]*[0-9][0-9]*$' < $1
+do echo -n "No BugId found. Edit again? ([y]/n)"
+ read ans
+ case address@hidden@} in
+ n*) exit 1;;
+ esac
+ $CVSEDITOR $1
+done
address@hidden example
+
+The @file{editinfo} file contains this line:
+
address@hidden
+^tc /usr/cvssupport/bugid.edit
address@hidden example
+
+The @file{rcsinfo} file contains this line:
+
address@hidden
+^tc /usr/cvssupport/tc.template
address@hidden example
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden loginfo
address@hidden Loginfo
address@hidden loginfo (admin file)
address@hidden Storing log messages
address@hidden Mailing log messages
address@hidden Distributing log messages
address@hidden Log messages
+
address@hidden "cvs commit" is not quite right. What we
address@hidden mean is "when the repository gets changed" which
address@hidden also includes "cvs import" and "cvs add" on a directory.
+The @file{loginfo} file is used to control where
address@hidden commit} log information is sent. The first
+entry on a line is a regular expression which is tested
+against the directory that the change is being made to,
+relative to the @code{$CVSROOT}. If a match is found, then
+the remainder of the line is a filter program that
+should expect log information on its standard input.
+
+If the repository name does not match any of the
+regular expressions in this file, the @samp{DEFAULT}
+line is used, if it is specified.
+
+All occurrences of the name @samp{ALL} appearing as a
+regular expression are used in addition to the first
+matching regular expression or @samp{DEFAULT}.
+
+The first matching regular expression is used.
+
address@hidden files}, for a description of the syntax of
+the @file{loginfo} file.
+
+The user may specify a format string as
+part of the filter. The string is composed of a
address@hidden followed by a space, or followed by a single
+format character, or followed by a set of format
+characters surrounded by @address@hidden and @address@hidden as
+separators. The format characters are:
+
address@hidden @t
address@hidden s
+file name
address@hidden V
+old version number (pre-checkin)
address@hidden v
+new version number (post-checkin)
address@hidden table
+
+All other characters that appear in a format string
+expand to an empty field (commas separating fields are
+still provided).
+
+For example, some valid format strings are @samp{%},
address@hidden, @address@hidden@}}, and @address@hidden@}}.
+
+The output will be a space separated string of tokens enclosed in
+quotation marks (@t{"}).
+Any embedded dollar signs (@t{$}), backticks (@t{`}),
+backslashes (@t{\}), or quotation marks will be preceded
+by a backslash (this allows the shell to correctly parse it
+as a single string, regardless of the characters it contains).
+For backwards compatibility, the first
+token will be the repository subdirectory. The rest of the
+tokens will be comma-delimited lists of the information
+requested in the format string. For example, if
address@hidden/u/src/master/yoyodyne/tc} is the repository, @address@hidden@}}
+is the format string, and three files (@t{ChangeLog},
address@hidden, @t{foo.c}) were modified, the output
+might be:
+
address@hidden
+"yoyodyne/tc ChangeLog,1.1,1.2 Makefile,1.3,1.4 foo.c,1.12,1.13"
address@hidden example
+
+As another example, @address@hidden@}} means that only the
+name of the repository will be generated.
+
+Note: when @sc{cvs} is accessing a remote repository,
address@hidden will be run on the @emph{remote}
+(i.e., server) side, not the client side (@pxref{Remote
+repositories}).
+
address@hidden
+* loginfo example:: Loginfo example
+* Keeping a checked out copy:: Updating a tree on every checkin
address@hidden menu
+
address@hidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. .
address@hidden loginfo example
address@hidden Loginfo example
+
+The following @file{loginfo} file, together with the
+tiny shell-script below, appends all log messages
+to the file @file{$CVSROOT/CVSROOT/commitlog},
+and any commits to the administrative files (inside
+the @file{CVSROOT} directory) are also logged in
address@hidden/usr/adm/cvsroot-log}.
+Commits to the @file{prog1} directory are mailed to @t{ceder}.
+
address@hidden FIXME: is it a CVS feature or bug that only the
address@hidden first matching line is used? It is documented
address@hidden above, but is it useful? For example, if we wanted
address@hidden to run both "cvs-log" and "Mail" for the CVSROOT
address@hidden directory, it is kind of awkward if
address@hidden only the first matching line is used.
address@hidden
+ALL /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog $USER
+^CVSROOT /usr/local/bin/cvs-log /usr/adm/cvsroot-log
+^prog1 Mail -s %s ceder
address@hidden example
+
+The shell-script @file{/usr/local/bin/cvs-log} looks
+like this:
+
address@hidden
+#!/bin/sh
+(echo "------------------------------------------------------";
+ echo -n $2" ";
+ date;
+ echo;
+ cat) >> $1
address@hidden example
+
address@hidden Keeping a checked out copy
address@hidden Keeping a checked out copy
+
address@hidden What other index entries? It seems like
address@hidden people might want to use a lot of different
address@hidden words for this functionality.
address@hidden Keeping a checked out copy
address@hidden Checked out copy, keeping
address@hidden Web pages, maintaining with CVS
+
+It is often useful to maintain a directory tree which
+contains files which correspond to the latest version
+in the repository. For example, other developers might
+want to refer to the latest sources without having to
+check them out, or you might be maintaining a web site
+with @sc{cvs} and want every checkin to cause the files
+used by the web server to be updated.
address@hidden Can we offer more details on the web example? Or
address@hidden point the user at how to figure it out? This text
address@hidden strikes me as sufficient for someone who already has
address@hidden some idea of what we mean but not enough for the naive
address@hidden user/sysadmin to understand it and set it up.
+
+The way to do this is by having loginfo invoke
address@hidden update}. Doing so in the naive way will
+cause a problem with locks, so the @code{cvs update}
+must be run in the background.
address@hidden Should we try to describe the problem with locks?
address@hidden It seems like a digression for someone who just
address@hidden wants to know how to make it work.
address@hidden Another choice which might work for a single file
address@hidden is to use "cvs -n update -p" which doesn't take
address@hidden out locks (I think) but I don't see many advantages
address@hidden of that and we might as well document something which
address@hidden works for multiple files.
+Here is an example for unix (this should all be on one line):
+
address@hidden
+^cyclic-pages (date; cat; (sleep 2; cd /u/www/local-docs;
+ cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1
address@hidden example
+
+This will cause checkins to repository directories
+starting with @code{cyclic-pages} to update the checked
+out tree in @file{/u/www/local-docs}.
address@hidden More info on some of the details? The "sleep 2" is
address@hidden so if we are lucky the lock will be gone by the time
address@hidden we start and we can wait 2 seconds instead of 30.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden rcsinfo
address@hidden Rcsinfo
address@hidden rcsinfo (admin file)
address@hidden Form for log message
address@hidden Log message template
address@hidden Template for log message
+
+The @file{rcsinfo} file can be used to specify a form to
+edit when filling out the commit log. The
address@hidden file has a syntax similar to the
address@hidden, @file{commitinfo} and @file{loginfo}
+files. @xref{syntax}. Unlike the other files the second
+part is @emph{not} a command-line template. Instead,
+the part after the regular expression should be a full pathname to
+a file containing the log message template.
+
+If the repository name does not match any of the
+regular expressions in this file, the @samp{DEFAULT}
+line is used, if it is specified.
+
+All occurrences of the name @samp{ALL} appearing as a
+regular expression are used in addition to the first
+matching regular expression or @samp{DEFAULT}.
+
address@hidden FIXME: should be offering advice, somewhere around
address@hidden here, about where to put the template file. The
address@hidden verifymsg example uses /usr/cvssupport but doesn't
address@hidden say anything about what that directory is for or
address@hidden whether it is hardwired into CVS or who creates
address@hidden it or anything. In particular we should say
address@hidden how to version control the template file. A
address@hidden probably better answer than the /usr/cvssupport
address@hidden stuff is to use checkoutlist (with xref to the
address@hidden checkoutlist doc).
address@hidden Also I am starting to see a connection between
address@hidden this and the Keeping a checked out copy node.
address@hidden Probably want to say something about that.
+The log message template will be used as a default log
+message. If you specify a log message with @samp{cvs
+commit -m @var{message}} or @samp{cvs commit -f
address@hidden that log message will override the
+template.
+
address@hidden, for an example @file{rcsinfo}
+file.
+
+When @sc{cvs} is accessing a remote repository,
+the contents of @file{rcsinfo} at the time a directory
+is first checked out will specify a template. This
+template will be updated on all @samp{cvs update}
+commands. It will also be added to new directories
+added with a @samp{cvs add new-directry} command.
+In versions of @sc{cvs} prior to version 1.12, the
address@hidden/Template} file was not updated. If the
address@hidden server is at version 1.12 or higher an older
+client may be used and the @file{CVS/Template} will
+be updated from the server.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden cvsignore
address@hidden Ignoring files via cvsignore
address@hidden cvsignore (admin file), global
address@hidden Global cvsignore
address@hidden Ignoring files
address@hidden -- This chapter should maybe be moved to the
address@hidden tutorial part of the manual?
+
+There are certain file names that frequently occur
+inside your working copy, but that you don't want to
+put under @sc{cvs} control. Examples are all the object
+files that you get while you compile your sources.
+Normally, when you run @samp{cvs update}, it prints a
+line for each file it encounters that it doesn't know
+about (@pxref{update output}).
+
address@hidden has a list of files (or sh(1) file name patterns)
+that it should ignore while running @code{update},
address@hidden and @code{release}.
address@hidden -- Are those the only three commands affected?
+This list is constructed in the following way.
+
address@hidden @bullet
address@hidden
+The list is initialized to include certain file name
+patterns: names associated with @sc{cvs}
+administration, or with other common source control
+systems; common names for patch files, object files,
+archive files, and editor backup files; and other names
+that are usually artifacts of assorted utilities.
+Currently, the default list of ignored file name
+patterns is:
+
address@hidden Ignored files
address@hidden Automatically ignored files
address@hidden
+ RCS SCCS CVS CVS.adm
+ RCSLOG cvslog.*
+ tags TAGS
+ .make.state .nse_depinfo
+ *~ #* .#* ,* _$* *$
+ *.old *.bak *.BAK *.orig *.rej .del-*
+ *.a *.olb *.o *.obj *.so *.exe
+ *.Z *.elc *.ln
+ core
address@hidden example
+
address@hidden
+The per-repository list in
address@hidden/CVSROOT/cvsignore} is appended to
+the list, if that file exists.
+
address@hidden
+The per-user list in @file{.cvsignore} in your home
+directory is appended to the list, if it exists.
+
address@hidden
+Any entries in the environment variable
address@hidden is appended to the list.
+
address@hidden
+Any @samp{-I} options given to @sc{cvs} is appended.
+
address@hidden
+As @sc{cvs} traverses through your directories, the contents
+of any @file{.cvsignore} will be appended to the list.
+The patterns found in @file{.cvsignore} are only valid
+for the directory that contains them, not for
+any sub-directories.
address@hidden itemize
+
+In any of the 5 places listed above, a single
+exclamation mark (@samp{!}) clears the ignore list.
+This can be used if you want to store any file which
+normally is ignored by @sc{cvs}.
+
+Specifying @samp{-I !} to @code{cvs import} will import
+everything, which is generally what you want to do if
+you are importing files from a pristine distribution or
+any other source which is known to not contain any
+extraneous files. However, looking at the rules above
+you will see there is a fly in the ointment; if the
+distribution contains any @file{.cvsignore} files, then
+the patterns from those files will be processed even if
address@hidden !} is specified. The only workaround is to
+remove the @file{.cvsignore} files in order to do the
+import. Because this is awkward, in the future
address@hidden !} might be modified to override
address@hidden files in each directory.
+
+Note that the syntax of the ignore files consists of a
+series of lines, each of which contains a space
+separated list of filenames. This offers no clean way
+to specify filenames which contain spaces, but you can
+use a workaround like @file{foo?bar} to match a file
+named @file{foo bar} (it also matches @file{fooxbar}
+and the like). Also note that there is currently no
+way to specify comments.
address@hidden FIXCVS? I don't _like_ this syntax at all, but
address@hidden changing it raises all the usual compatibility
address@hidden issues and I'm also not sure what to change it to.
+
address@hidden checkoutlist
address@hidden The checkoutlist file
address@hidden checkoutlist
+
+It may be helpful to use @sc{cvs} to maintain your own
+files in the @file{CVSROOT} directory. For example,
+suppose that you have a script @file{logcommit.pl}
+which you run by including the following line in the
address@hidden administrative file:
+
address@hidden
+ALL $CVSROOT/CVSROOT/logcommit.pl
address@hidden example
+
+To maintain @file{logcommit.pl} with @sc{cvs} you would
+add the following line to the @file{checkoutlist}
+administrative file:
+
address@hidden
+logcommit.pl
address@hidden example
+
+The format of @file{checkoutlist} is one line for each
+file that you want to maintain using @sc{cvs}, giving
+the name of the file.
+
+After setting up @file{checkoutlist} in this fashion,
+the files listed there will function just like
address@hidden's built-in administrative files. For example,
+when checking in one of the files you should get a
+message such as:
+
address@hidden
+cvs commit: Rebuilding administrative file database
address@hidden example
+
address@hidden
+and the checked out copy in the @file{CVSROOT}
+directory should be updated.
+
+Note that listing @file{passwd} (@pxref{Password
+authentication server}) in @file{checkoutlist} is not
+recommended for security reasons.
+
+For information about keeping a checkout out copy in a
+more general context than the one provided by
address@hidden, see @ref{Keeping a checked out
+copy}.
+
address@hidden - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- -
address@hidden history file
address@hidden The history file
address@hidden History file
address@hidden Log information, saving
+
+The file @file{$CVSROOT/CVSROOT/history} is used
+to log information for the @code{history} command
+(@pxref{history}). This file must be created to turn
+on logging. This is done automatically if the
address@hidden init} command is used to set up the
+repository (@pxref{Creating a repository}).
+
+The file format of the @file{history} file is
+documented only in comments in the @sc{cvs} source
+code, but generally programs should use the @code{cvs
+history} command to access it anyway, in case the
+format changes with future releases of @sc{cvs}.
+
address@hidden Variables
address@hidden Expansions in administrative files
address@hidden Internal variables
address@hidden Variables
+
+Sometimes in writing an administrative file, you might
+want the file to be able to know various things based
+on environment @sc{cvs} is running in. There are
+several mechanisms to do that.
+
+To find the home directory of the user running @sc{cvs}
+(from the @code{HOME} environment variable), use
address@hidden followed by @samp{/} or the end of the line.
+Likewise for the home directory of @var{user}, use
address@hidden@var{user}}. These variables are expanded on
+the server machine, and don't get any reasonable
+expansion if pserver (@pxref{Password authenticated})
+is in use; therefore user variables (see below) may be
+a better choice to customize behavior based on the user
+running @sc{cvs}.
address@hidden Based on these limitations, should we deprecate ~?
address@hidden What is it good for? Are people using it?
+
+One may want to know about various pieces of
+information internal to @sc{cvs}. A @sc{cvs} internal
+variable has the syntax @address@hidden@address@hidden,
+where @var{variable} starts with a letter and consists
+of alphanumeric characters and @samp{_}. If the
+character following @var{variable} is a
+non-alphanumeric character other than @samp{_}, the
address@hidden@{} and @address@hidden can be omitted. The @sc{cvs}
+internal variables are:
+
address@hidden @code
address@hidden CVSROOT
address@hidden CVSROOT, internal variable
+This is the absolute path to the current @sc{cvs} root directory.
address@hidden, for a description of the various
+ways to specify this, but note that the internal
+variable contains just the directory and not any
+of the access method information.
+
address@hidden RCSBIN
address@hidden RCSBIN, internal variable
+In @sc{cvs} 1.9.18 and older, this specified the
+directory where @sc{cvs} was looking for @sc{rcs}
+programs. Because @sc{cvs} no longer runs @sc{rcs}
+programs, specifying this internal variable is now an
+error.
+
address@hidden CVSEDITOR
address@hidden CVSEDITOR, internal variable
address@hidden EDITOR
address@hidden EDITOR, internal variable
address@hidden VISUAL
address@hidden VISUAL, internal variable
+These all expand to the same value, which is the editor
+that @sc{cvs} is using. @xref{Global options}, for how
+to specify this.
+
address@hidden USER
address@hidden USER, internal variable
+Username of the user running @sc{cvs} (on the @sc{cvs}
+server machine).
+When using pserver, this is the user specified in the repository
+specification which need not be the same as the username the
+server is running as (@pxref{Password authentication server}).
+Do not confuse this with the environment variable of the same name.
address@hidden table
+
+If you want to pass a value to the administrative files
+which the user who is running @sc{cvs} can specify,
+use a user variable.
address@hidden User variables
+To expand a user variable, the
+administrative file contains
address@hidden@address@hidden@}}. To set a user variable,
+specify the global option @samp{-s} to @sc{cvs}, with
+argument @address@hidden@var{value}}. It may be
+particularly useful to specify this option via
address@hidden (@pxref{~/.cvsrc}).
+
+For example, if you want the administrative file to
+refer to a test directory you might create a user
+variable @code{TESTDIR}. Then if @sc{cvs} is invoked
+as
+
address@hidden
+cvs -s TESTDIR=/work/local/tests
address@hidden example
+
address@hidden
+and the
+administrative file contains @code{sh
address@hidden@}/runtests}, then that string is expanded
+to @code{sh /work/local/tests/runtests}.
+
+All other strings containing @samp{$} are reserved;
+there is no way to quote a @samp{$} character so that
address@hidden represents itself.
+
+Environment variables passed to administrative files are:
+
address@hidden @code
address@hidden environment variables, passed to administrative files
+
address@hidden CVS_USER
address@hidden CVS_USER, environment variable
+The @sc{cvs}-specific username provided by the user, if it
+can be provided (currently just for the pserver access
+method), and to the empty string otherwise. (@code{CVS_USER}
+and @code{USER} may differ when @file{$CVSROOT/CVSROOT/passwd}
+is used to map @sc{cvs} usernames to system usernames.)
+
address@hidden LOGNAME
address@hidden LOGNAME, environment variable
+The username of the system user.
+
address@hidden USER
address@hidden USER, environment variable
+Same as @code{LOGNAME}.
+Do not confuse this with the internal variable of the same name.
address@hidden table
+
address@hidden config
address@hidden The CVSROOT/config configuration file
+
address@hidden config, in CVSROOT
address@hidden CVSROOT/config
+
+The administrative file @file{config} contains various
+miscellaneous settings which affect the behavior of
address@hidden The syntax is slightly different from the
+other administrative files. Variables are not
+expanded. Lines which start with @samp{#} are
+considered comments.
address@hidden FIXME: where do we define comments for the other
address@hidden administrative files.
+Other lines consist of a keyword, @samp{=}, and a
+value. Note that this syntax is very strict.
+Extraneous spaces or tabs are not permitted.
address@hidden See comments in parseinfo.c:parse_config for more
address@hidden discussion of this strictness.
+
+Currently defined keywords are:
+
address@hidden @code
address@hidden RCSBIN, in CVSROOT/config
address@hidden address@hidden
+For @sc{cvs} 1.9.12 through 1.9.18, this setting told
address@hidden to look for @sc{rcs} programs in the
address@hidden directory. Current versions of @sc{cvs}
+do not run @sc{rcs} programs; for compatibility this
+setting is accepted, but it does nothing.
+
address@hidden SystemAuth, in CVSROOT/config
address@hidden address@hidden
+If @var{value} is @samp{yes}, then pserver should check
+for users in the system's user database if not found in
address@hidden/passwd}. If it is @samp{no}, then all
+pserver users must exist in @file{CVSROOT/passwd}.
+The default is @samp{yes}. For more on pserver, see
address@hidden authenticated}.
+
+
address@hidden TopLevelAdmin, in CVSROOT/config
address@hidden address@hidden
+Modify the @samp{checkout} command to create a
address@hidden directory at the top level of the new
+working directory, in addition to @samp{CVS}
+directories created within checked-out directories.
+The default value is @samp{no}.
+
+This option is useful if you find yourself performing
+many commands at the top level of your working
+directory, rather than in one of the checked out
+subdirectories. The @file{CVS} directory created there
+will mean you don't have to specify @code{CVSROOT} for
+each command. It also provides a place for the
address@hidden/Template} file (@pxref{Working directory
+storage}).
+
address@hidden LockDir, in CVSROOT/config
address@hidden address@hidden
+Put @sc{cvs} lock files in @var{directory} rather than
+directly in the repository. This is useful if you want
+to let users read from the repository while giving them
+write access only to @var{directory}, not to the
+repository.
+It can also be used to put the locks on a very fast
+in-memory file system to speed up locking and unlocking
+the repository.
+You need to create @var{directory}, but
address@hidden will create subdirectories of @var{directory} as it
+needs them. For information on @sc{cvs} locks, see
address@hidden
+
address@hidden Mention this in Compatibility section?
+Before enabling the LockDir option, make sure that you
+have tracked down and removed any copies of @sc{cvs} 1.9 or
+older. Such versions neither support LockDir, nor will
+give an error indicating that they don't support it.
+The result, if this is allowed to happen, is that some
address@hidden users will put the locks one place, and others will
+put them another place, and therefore the repository
+could become corrupted. @sc{cvs} 1.10 does not support
+LockDir but it will print a warning if run on a
+repository with LockDir enabled.
+
address@hidden LogHistory, in CVSROOT/config
address@hidden address@hidden
+Control what is logged to the @file{CVSROOT/history} file (@pxref{history}).
+Default of @samp{TOEFWUCGMAR} (or simply @samp{all}) will log
+all transactions. Any subset of the default is
+legal. (For example, to only log transactions that modify the
address@hidden,v} files, use @samp{LogHistory=TMAR}.)
+
address@hidden RereadLogAfterVerify, in CVSROOT/config
address@hidden @file{verifymsg}, changing the log message
address@hidden address@hidden
+Modify the @samp{commit} command such that CVS will reread the
+log message after running the program specified by @file{verifymsg}.
address@hidden may be one of @samp{yes} or @samp{always}, indicating that
+the log message should always be reread; @samp{no}
+or @samp{never}, indicating that it should never be
+reread; or @var{value} may be @samp{stat}, indicating
+that the file should be checked with the filesystem
address@hidden()} function to see if it has changed (see warning below)
+before rereading. The default value is @samp{always}.
+
address@hidden: the `stat' mode can cause CVS to pause for up to
+one extra second per directory committed. This can be less IO and
+CPU intensive but is not recommended for use with large repositories}
+
address@hidden, for more information on how verifymsg
+may be used.
+
address@hidden UserAdminOptions, in CVSROOT/config
address@hidden address@hidden
+Control what options will be allowed with the @code{cvs admin}
+command (@pxref{admin}) for users not in the @code{cvsadmin} group.
+The @var{value} string is a list of single character options
+which should be allowed. If a user who is not a member of the
address@hidden group tries to execute any @code{cvs admin}
+option which is not listed they will will receive an error message
+reporting that the option is restricted.
+
+If no @code{cvsadmin} group exists on the server, @sc{cvs} will
+ignore the @code{UserAdminOptions} keyword (@pxref{admin}).
+
+When not specified, @code{UserAdminOptions} defaults to
address@hidden In other words, it defaults to allowing
+users outside of the @code{cvsadmin} group to use the
address@hidden admin} command only to change the default keyword
+expansion mode for files.
+
+As an example, to restrict users not in the @code{cvsadmin}
+group to using @code{cvs admin} to change the default keyword
+substitution mode, lock revisions, unlock revisions, and
+replace the log message, use @samp{UserAdminOptions=klum}.
address@hidden table
+
address@hidden
---------------------------------------------------------------------
address@hidden Environment variables
address@hidden All environment variables which affect CVS
address@hidden Environment variables
address@hidden Reference manual for variables
+
+This is a complete list of all environment variables
+that affect @sc{cvs}.
+
address@hidden @code
address@hidden CVSIGNORE, environment variable
address@hidden $CVSIGNORE
+A whitespace-separated list of file name patterns that
address@hidden should ignore. @xref{cvsignore}.
+
address@hidden CVSWRAPPERS, environment variable
address@hidden $CVSWRAPPERS
+A whitespace-separated list of file name patterns that
address@hidden should treat as wrappers. @xref{Wrappers}.
+
address@hidden CVSREAD, environment variable
address@hidden Read-only files, and CVSREAD
address@hidden $CVSREAD
+If this is set, @code{checkout} and @code{update} will
+try hard to make the files in your working directory
+read-only. When this is not set, the default behavior
+is to permit modification of your working files.
+
address@hidden CVSREADONLYFS, environment variable
address@hidden $CVSREADONLYFS
+Turns on read-only repository mode. This allows one to
+check out from a read-only repository, such as within
+an anoncvs server, or from a CDROM repository.
+
+It has the same effect as if the @samp{-R} command-line
+option is used. This can also allow the use of
+read-only NFS repositories.
+
address@hidden $CVSUMASK
+Controls permissions of files in the repository. See
address@hidden permissions}.
+
address@hidden $CVSROOT
+Should contain the full pathname to the root of the @sc{cvs}
+source repository (where the @sc{rcs} files are
+kept). This information must be available to @sc{cvs} for
+most commands to execute; if @code{$CVSROOT} is not set,
+or if you wish to override it for one invocation, you
+can supply it on the command line: @samp{cvs -d cvsroot
address@hidden Once you have checked out a working
+directory, @sc{cvs} stores the appropriate root (in
+the file @file{CVS/Root}), so normally you only need to
+worry about this when initially checking out a working
+directory.
+
address@hidden $CVSEDITOR
address@hidden CVSEDITOR, environment variable
address@hidden $EDITOR
address@hidden EDITOR, environment variable
address@hidden $VISUAL
address@hidden VISUAL, environment variable
+Specifies the program to use for recording log messages
+during commit. @code{$CVSEDITOR} overrides
address@hidden, which overrides @code{$VISUAL}.
+See @ref{Committing your changes} for more or
address@hidden options} for alternative ways of specifying a
+log editor.
+
address@hidden PATH, environment variable
address@hidden $PATH
+If @code{$RCSBIN} is not set, and no path is compiled
+into @sc{cvs}, it will use @code{$PATH} to try to find all
+programs it uses.
+
address@hidden HOME, environment variable
address@hidden $HOME
address@hidden HOMEPATH, environment variable
address@hidden $HOMEPATH
address@hidden HOMEDRIVE, environment variable
address@hidden $HOMEDRIVE
+Used to locate the directory where the @file{.cvsrc}
+file, and other such files, are searched. On Unix, @sc{cvs}
+just checks for @code{HOME}. On Windows NT, the system will
+set @code{HOMEDRIVE}, for example to @samp{d:} and @code{HOMEPATH},
+for example to @file{\joe}. On Windows 95, you'll
+probably need to set @code{HOMEDRIVE} and @code{HOMEPATH} yourself.
address@hidden We are being vague about whether HOME works on
address@hidden Windows; see long comment in windows-NT/filesubr.c.
+
address@hidden CVS_RSH, environment variable
address@hidden $CVS_RSH
+Specifies the external program which @sc{cvs} connects with,
+when @code{:ext:} access method is specified.
address@hidden via rsh}.
+
address@hidden $CVS_SERVER
+Used in client-server mode when accessing a remote
+repository using @sc{rsh}. It specifies the name of
+the program to start on the server side (and any
+necessary arguments) when accessing a remote repository
+using the @code{:ext:}, @code{:fork:}, or @code{:server:} access methods.
+The default value for @code{:ext:} and @code{:server:} is @code{cvs};
+the default value for @code{:fork:} is the name used to run the client.
address@hidden via rsh}
+
address@hidden $CVS_PASSFILE
+Used in client-server mode when accessing the @code{cvs
+login server}. Default value is @file{$HOME/.cvspass}.
address@hidden authentication client}
+
address@hidden $CVS_CLIENT_PORT
+Used in client-server mode to set the port to use when accessing the server
+via Kerberos, GSSAPI, or @sc{cvs}'s password authentication protocol
+if the port is not specified in the CVSROOT.
address@hidden repositories}
+
address@hidden CVS_RCMD_PORT, environment variable
address@hidden $CVS_RCMD_PORT
+Used in client-server mode. If set, specifies the port
+number to be used when accessing the @sc{rcmd} demon on
+the server side. (Currently not used for Unix clients).
+
address@hidden CVS_CLIENT_LOG, environment variable
address@hidden $CVS_CLIENT_LOG
+Used for debugging only in client-server
+mode. If set, everything sent to the server is logged
+into @address@hidden and everything
+sent from the server is logged into
address@hidden@code{$CVS_CLIENT_LOG}.out}.
+
address@hidden CVS_SERVER_SLEEP, environment variable
address@hidden $CVS_SERVER_SLEEP
+Used only for debugging the server side in
+client-server mode. If set, delays the start of the
+server child process the specified amount of
+seconds so that you can attach to it with a debugger.
+
address@hidden CVS_IGNORE_REMOTE_ROOT, environment variable
address@hidden $CVS_IGNORE_REMOTE_ROOT
+For @sc{cvs} 1.10 and older, setting this variable
+prevents @sc{cvs} from overwriting the @file{CVS/Root}
+file when the @samp{-d} global option is specified.
+Later versions of @sc{cvs} do not rewrite
address@hidden/Root}, so @code{CVS_IGNORE_REMOTE_ROOT} has no
+effect.
+
address@hidden CVS_LOCAL_BRANCH_NUM, environment variable
address@hidden $CVS_LOCAL_BRANCH_NUM
+Setting this variable allows some control over the
+branch number that is assigned. This is specifically to
+support the local commit feature of CVSup. If one sets
address@hidden to (say) 1000 then branches
+the local repository, the revision numbers will look
+like 1.66.1000.xx. There is almost a dead-set certainty
+that there will be no conflicts with version numbers.
+
address@hidden COMSPEC, environment variable
address@hidden $COMSPEC
+Used under OS/2 only. It specifies the name of the
+command interpreter and defaults to @sc{cmd.exe}.
+
address@hidden TMPDIR, environment variable
address@hidden $TMPDIR
address@hidden TMP, environment variable
address@hidden $TMP
address@hidden TEMP, environment variable
address@hidden $TEMP
address@hidden Temporary files, location of
address@hidden This is quite nuts. We don't talk about tempnam
address@hidden or mkstemp which we sometimes use. The discussion
address@hidden of "Global options" is semi-incoherent.
address@hidden I'm not even sure those are the only inaccuracies.
address@hidden Furthermore, the conventions are
address@hidden pretty crazy and they should be simplified.
+Directory in which temporary files are located.
+The @sc{cvs} server uses
address@hidden @xref{Global options}, for a
+description of how to specify this.
+Some parts of @sc{cvs} will always use @file{/tmp} (via
+the @code{tmpnam} function provided by the system).
+
+On Windows NT, @code{TMP} is used (via the @code{_tempnam}
+function provided by the system).
+
+The @code{patch} program which is used by the @sc{cvs}
+client uses @code{TMPDIR}, and if it is not set, uses
address@hidden/tmp} (at least with GNU patch 2.1). Note that
+if your server and client are both running @sc{cvs}
+1.9.10 or later, @sc{cvs} will not invoke an external
address@hidden program.
+
address@hidden CVS_PID, environment variable
address@hidden $CVS_PID
+This is the process identification (aka pid) number of
+the @sc{cvs} process. It is often useful in the
+programs and/or scripts specified by the
address@hidden, @file{verifymsg}, @file{loginfo}
+files.
address@hidden table
+
address@hidden Compatibility
address@hidden Compatibility between CVS Versions
+
address@hidden CVS, versions of
address@hidden Versions, of CVS
address@hidden Compatibility, between CVS versions
address@hidden We don't mention versions older than CVS 1.3
address@hidden on the theory that it would clutter it up for the vast
address@hidden majority of people, who don't have anything that old.
address@hidden
+The repository format is compatible going back to
address@hidden 1.3. But see @ref{Watches Compatibility}, if
+you have copies of @sc{cvs} 1.6 or older and you want
+to use the optional developer communication features.
address@hidden If you "cvs rm" and commit using 1.3, then you'll
address@hidden want to run "rcs -sdead <file,v>" on each of the
address@hidden files in the Attic if you then want 1.5 and
address@hidden later to recognize those files as dead (I think the
address@hidden symptom if this is not done is that files reappear
address@hidden in joins). (Wait: the above will work but really to
address@hidden be strictly correct we should suggest checking
address@hidden in a new revision rather than just changing the
address@hidden state of the head revision, shouldn't we?).
address@hidden The old convert.sh script was for this, but it never
address@hidden did get updated to reflect use of the RCS "dead"
address@hidden state.
address@hidden Note: this is tricky to document without confusing
address@hidden people--need to carefully say what CVS version we
address@hidden are talking about and keep in mind the distinction
address@hidden between a
address@hidden repository created with 1.3 and on which one now
address@hidden uses 1.5+, and a repository on which one wants to
address@hidden use both versions side by side (e.g. during a
address@hidden transition period).
address@hidden Wait, can't CVS just detect the case in which a file
address@hidden is in the Attic but the head revision is not dead?
address@hidden Not sure whether this should produce a warning or
address@hidden something, and probably needs further thought, but
address@hidden it would appear that the situation can be detected.
address@hidden
address@hidden We might want to separate out the 1.3 compatibility
address@hidden section (for repository & working directory) from the
address@hidden rest--that might help avoid confusing people who
address@hidden are upgrading (for example) from 1.6 to 1.8.
address@hidden
address@hidden A minor incompatibility is if a current version of CVS
address@hidden puts "Nfoo" into CVS/Tag, then CVS 1.9 or older will
address@hidden see this as if there is no tag. Seems to me this is
address@hidden too obscure to mention.
+
+The working directory format is compatible going back
+to @sc{cvs} 1.5. It did change between @sc{cvs} 1.3
+and @sc{cvs} 1.5. If you run @sc{cvs} 1.5 or newer on
+a working directory checked out with @sc{cvs} 1.3,
address@hidden will convert it, but to go back to @sc{cvs}
+1.3 you need to check out a new working directory with
address@hidden 1.3.
+
+The remote protocol is interoperable going back to @sc{cvs} 1.5, but no
+further (1.5 was the first official release with the remote protocol,
+but some older versions might still be floating around). In many
+cases you need to upgrade both the client and the server to take
+advantage of new features and bugfixes, however.
+
address@hidden Perhaps should be saying something here about the
address@hidden "D" lines in Entries (written by CVS 1.9; 1.8 and
address@hidden older don't use them). These are supposed to be
address@hidden compatible in both directions, but I'm not sure
address@hidden they quite are 100%. One common gripe is if you
address@hidden "rm -r" a directory and 1.9 gets confused, as it
address@hidden still sees it in Entries. That one is fixed in
address@hidden (say) 1.9.6. Someone else reported problems with
address@hidden starting with a directory which was checked out with
address@hidden an old version, and then using a new version, and
address@hidden some "D" lines appeared, but not for every
address@hidden directory, causing some directories to be skipped.
address@hidden They weren't sure how to reproduce this, though.
+
address@hidden
---------------------------------------------------------------------
address@hidden Troubleshooting
address@hidden Troubleshooting
+
+If you are having trouble with @sc{cvs}, this appendix
+may help. If there is a particular error message which
+you are seeing, then you can look up the message
+alphabetically. If not, you can look through the
+section on other problems to see if your problem is
+mentioned there.
+
address@hidden
+* Error messages:: Partial list of CVS errors
+* Connection:: Trouble making a connection to a CVS server
+* Other problems:: Problems not readily listed by error message
address@hidden menu
+
+
address@hidden Error messages
address@hidden Partial list of error messages
+
+Here is a partial list of error messages that you may
+see from @sc{cvs}. It is not a complete address@hidden
+is capable of printing many, many error messages, often
+with parts of them supplied by the operating system,
+but the intention is to list the common and/or
+potentially confusing error messages.
+
+The messages are alphabetical, but introductory text
+such as @samp{cvs update: } is not considered in
+ordering them.
+
+In some cases the list includes messages printed by old
+versions of @sc{cvs} (partly because users may not be
+sure which version of @sc{cvs} they are using at any
+particular moment).
address@hidden If we want to start retiring messages, perhaps we
address@hidden should pick a cutoff version (for example, no more
address@hidden messages which are specific to versions before 1.9)
address@hidden and then move the old messages to an "old messages"
address@hidden node rather than deleting them completely.
+
address@hidden @code
address@hidden FIXME: What is the correct way to format a multiline
address@hidden error message here? Maybe @table is the wrong
address@hidden choice? Texinfo gurus?
address@hidden @var{file}:@var{line}: Assertion '@var{text}' failed
+The exact format of this message may vary depending on
+your system. It indicates a bug in @sc{cvs}, which can
+be handled as described in @ref{BUGS}.
+
address@hidden cvs @var{command}: authorization failed: server @var{host}
rejected access
+This is a generic response when trying to connect to a
+pserver server which chooses not to provide a
+specific reason for denying authorization. Check that
+the username and password specified are correct and
+that the @code{CVSROOT} specified is allowed by @samp{--allow-root}
+in @file{inetd.conf}. See @ref{Password authenticated}.
+
address@hidden cvs @var{command}: conflict: removed @var{file} was modified by
second party
+This message indicates that you removed a file, and
+someone else modified it. To resolve the conflict,
+first run @samp{cvs add @var{file}}. If desired, look
+at the other party's modification to decide whether you
+still want to remove it. If you don't want to remove
+it, stop here. If you do want to remove it, proceed
+with @samp{cvs remove @var{file}} and commit your
+removal.
address@hidden Tests conflicts2-142b* in sanity.sh test for this.
+
address@hidden cannot change permissions on temporary directory
address@hidden
+Operation not permitted
address@hidden example
+This message has been happening in a non-reproducible,
+occasional way when we run the client/server testsuite,
+both on Red Hat Linux 3.0.3 and 4.1. We haven't been
+able to figure out what causes it, nor is it known
+whether it is specific to linux (or even to this
+particular machine!). If the problem does occur on
+other unices, @samp{Operation not permitted} would be
+likely to read @samp{Not owner} or whatever the system
+in question uses for the unix @code{EPERM} error. If
+you have any information to add, please let us know as
+described in @ref{BUGS}. If you experience this error
+while using @sc{cvs}, retrying the operation which
+produced it should work fine.
address@hidden This has been seen in a variety of tests, including
address@hidden multibranch-2, multibranch-5, and basic1-24-rm-rm,
address@hidden so it doesn't seem particularly specific to any one
address@hidden test.
+
address@hidden cvs [server aborted]: Cannot check out files into the repository
itself
+The obvious cause for this message (especially for
+non-client/server @sc{cvs}) is that the @sc{cvs} root
+is, for example, @file{/usr/local/cvsroot} and you try
+to check out files when you are in a subdirectory, such
+as @file{/usr/local/cvsroot/test}. However, there is a
+more subtle cause, which is that the temporary
+directory on the server is set to a subdirectory of the
+root (which is also not allowed). If this is the
+problem, set the temporary directory to somewhere else,
+for example @file{/var/tmp}; see @code{TMPDIR} in
address@hidden variables}, for how to set the
+temporary directory.
+
address@hidden cannot commit files as 'root'
+See @samp{'root' is not allowed to commit files}.
+
address@hidden For one example see basica-1a10 in the testsuite
address@hidden For another example, "cvs co ." on NT; see comment
address@hidden at windows-NT/filesubr.c (expand_wild).
address@hidden For another example, "cvs co foo/bar" where foo exists.
address@hidden cannot open CVS/Entries for reading: No such file or directory
+This generally indicates a @sc{cvs} internal error, and
+can be handled as with other @sc{cvs} bugs
+(@pxref{BUGS}). Usually there is a workaround---the
+exact nature of which would depend on the situation but
+which hopefully could be figured out.
+
address@hidden This is more obscure than it might sound; it only
address@hidden happens if you run "cvs init" from a directory which
address@hidden contains a CVS/Root file at the start.
address@hidden cvs [init aborted]: cannot open CVS/Root: No such file or
directory
+This message is harmless. Provided it is not
+accompanied by other errors, the operation has
+completed successfully. This message should not occur
+with current versions of @sc{cvs}, but it is documented
+here for the benefit of @sc{cvs} 1.9 and older.
+
address@hidden cvs server: cannot open /root/.cvsignore: Permission denied
address@hidden cvs [server aborted]: can't chdir(/root): Permission denied
+See @ref{Connection}.
+
address@hidden cvs [checkout aborted]: cannot rename file @var{file} to
CVS/,,@var{file}: Invalid argument
+This message has been reported as intermittently
+happening with @sc{cvs} 1.9 on Solaris 2.5. The cause is
+unknown; if you know more about what causes it, let us
+know as described in @ref{BUGS}.
+
address@hidden cvs address@hidden aborted]: cannot start server via rcmd
+This, unfortunately, is a rather nonspecific error
+message which @sc{cvs} 1.9 will print if you are
+running the @sc{cvs} client and it is having trouble
+connecting to the server. Current versions of @sc{cvs}
+should print a much more specific error message. If
+you get this message when you didn't mean to run the
+client at all, you probably forgot to specify
address@hidden:local:}, as described in @ref{Repository}.
+
address@hidden ci: @var{file},v: bad diff output line: Binary files - and
/tmp/T2a22651 differ
address@hidden 1.9 and older will print this message
+when trying to check in a binary file if
address@hidden is not correctly installed. Re-read the
+instructions that came with your @sc{rcs} distribution
+and the @sc{install} file in the @sc{cvs}
+distribution. Alternately, upgrade to a current
+version of @sc{cvs}, which checks in files itself
+rather than via @sc{rcs}.
+
address@hidden cvs checkout: could not check out @var{file}
+With @sc{cvs} 1.9, this can mean that the @code{co} program
+(part of @sc{rcs}) returned a failure. It should be
+preceded by another error message, however it has been
+observed without another error message and the cause is
+not well-understood. With the current version of @sc{cvs},
+which does not run @code{co}, if this message occurs
+without another error message, it is definitely a @sc{cvs}
+bug (@pxref{BUGS}).
address@hidden My current suspicion is that the RCS in the rcs (not
address@hidden cvs/winnt/rcs57nt.zip) directory on the _Practical_
address@hidden CD is bad (remains to be confirmed).
address@hidden There is also a report of something which looks
address@hidden very similar on SGI, Irix 5.2, so I dunno.
+
address@hidden cvs [login aborted]: could not find out home directory
+This means that you need to set the environment
+variables that @sc{cvs} uses to locate your home directory.
+See the discussion of @code{HOME}, @code{HOMEDRIVE}, and @code{HOMEPATH} in
address@hidden variables}.
+
address@hidden cvs update: could not merge revision @var{rev} of @var{file}: No
such file or directory
address@hidden 1.9 and older will print this message if there was
+a problem finding the @code{rcsmerge} program. Make
+sure that it is in your @code{PATH}, or upgrade to a
+current version of @sc{cvs}, which does not require
+an external @code{rcsmerge} program.
+
address@hidden cvs [update aborted]: could not patch @var{file}: No such file
or directory
+This means that there was a problem finding the
address@hidden program. Make sure that it is in your
address@hidden Note that despite appearances the message
+is @emph{not} referring to whether it can find @var{file}.
+If both the client and the server are running a current
+version of @sc{cvs}, then there is no need for an
+external patch program and you should not see this
+message. But if either client or server is running
address@hidden 1.9, then you need @code{patch}.
+
address@hidden cvs update: could not patch @var{file}; will refetch
+This means that for whatever reason the client was
+unable to apply a patch that the server sent. The
+message is nothing to be concerned about, because
+inability to apply the patch only slows things down and
+has no effect on what @sc{cvs} does.
address@hidden xref to update output. Or File status?
address@hidden Or some place else that
address@hidden explains this whole "patch"/P/Needs Patch thing?
+
address@hidden dying gasps from @var{server} unexpected
+There is a known bug in the server for @sc{cvs} 1.9.18
+and older which can cause this. For me, this was
+reproducible if I used the @samp{-t} global option. It
+was fixed by Andy Piper's 14 Nov 1997 change to
+src/filesubr.c, if anyone is curious.
+If you see the message,
+you probably can just retry the operation which failed,
+or if you have discovered information concerning its
+cause, please let us know as described in @ref{BUGS}.
+
address@hidden end of file from server (consult above messages if any)
+The most common cause for this message is if you are
+using an external @code{rsh} program and it exited with
+an error. In this case the @code{rsh} program should
+have printed a message, which will appear before the
+above message. For more information on setting up a
address@hidden client and server, see @ref{Remote repositories}.
+
address@hidden cvs [update aborted]: EOF in key in RCS file @var{file},v
address@hidden cvs [checkout aborted]: EOF while looking for end of string in
RCS file @var{file},v
+This means that there is a syntax error in the given
address@hidden file. Note that this might be true even if @sc{rcs} can
+read the file OK; @sc{cvs} does more error checking of
+errors in the RCS file. That is why you may see this
+message when upgrading from @sc{cvs} 1.9 to @sc{cvs}
+1.10. The likely cause for the original corruption is
+hardware, the operating system, or the like. Of
+course, if you find a case in which @sc{cvs} seems to
+corrupting the file, by all means report it,
+(@pxref{BUGS}).
+There are quite a few variations of this error message,
+depending on exactly where in the @sc{rcs} file @sc{cvs}
+finds the syntax error.
+
address@hidden mkmodules
address@hidden cvs commit: Executing 'mkmodules'
+This means that your repository is set up for a version
+of @sc{cvs} prior to @sc{cvs} 1.8. When using @sc{cvs}
+1.8 or later, the above message will be preceded by
+
address@hidden
+cvs commit: Rebuilding administrative file database
address@hidden example
+
+If you see both messages, the database is being rebuilt
+twice, which is unnecessary but harmless. If you wish
+to avoid the duplication, and you have no versions of
address@hidden 1.7 or earlier in use, remove @code{-i mkmodules}
+every place it appears in your @code{modules}
+file. For more information on the @code{modules} file,
+see @ref{modules}.
+
address@hidden This message comes from "co", and I believe is
address@hidden possible only with older versions of CVS which call
address@hidden co. The problem with being able to create the bogus
address@hidden RCS file still exists, though (and I think maybe
address@hidden there is a different symptom(s) now).
address@hidden FIXME: Would be nice to have a more exact wording
address@hidden for this message.
address@hidden missing author
+Typically this can happen if you created an RCS file
+with your username set to empty. @sc{cvs} will, bogusly,
+create an illegal RCS file with no value for the author
+field. The solution is to make sure your username is
+set to a non-empty value and re-create the RCS file.
address@hidden "make sure your username is set" is complicated in
address@hidden and of itself, as there are the environment
address@hidden variables the system login name, &c, and it depends
address@hidden on the version of CVS.
+
address@hidden cvs [checkout aborted]: no such tag @var{tag}
+This message means that @sc{cvs} isn't familiar with
+the tag @var{tag}. Usually this means that you have
+mistyped a tag name; however there are (relatively
+obscure) cases in which @sc{cvs} will require you to
address@hidden Search sanity.sh for "no such tag" to see some of
address@hidden the relatively obscure cases.
+try a few other @sc{cvs} commands involving that tag,
+before you find one which will cause @sc{cvs} to update
+the @file{val-tags} file; see discussion of val-tags in
address@hidden permissions}. You only need to worry about
+this once for a given tag; when a tag is listed in
address@hidden, it stays there. Note that using
address@hidden to not require tag matches does not override
+this check; see @ref{Common options}.
+
address@hidden *PANIC* administration files missing
+This typically means that there is a directory named
address@hidden but it does not contain the administrative files
+which @sc{cvs} puts in a CVS directory. If the problem is
+that you created a CVS directory via some mechanism
+other than @sc{cvs}, then the answer is simple, use a name
+other than @sc{cvs}. If not, it indicates a @sc{cvs} bug
+(@pxref{BUGS}).
+
address@hidden rcs error: Unknown option: -x,v/
+This message will be followed by a usage message for
address@hidden It means that you have an old version of
address@hidden (probably supplied with your operating
+system), as well as an old version of @sc{cvs}.
address@hidden 1.9.18 and earlier only work with @sc{rcs} version 5 and
+later; current versions of @sc{cvs} do not run @sc{rcs} programs.
address@hidden For more information on installing @sc{cvs}, see
address@hidden (FIXME: where? it depends on whether you are
address@hidden getting binaries or sources or what).
address@hidden The message can also say "ci error" or something
address@hidden instead of "rcs error", I suspect.
+
address@hidden cvs [server aborted]: received broken pipe signal
+This message seems to be caused by a hard-to-track-down
+bug in @sc{cvs} or the systems it runs on (we don't
+know---we haven't tracked it down yet!). It seems to
+happen only after a @sc{cvs} command has completed, and
+you should be able to just ignore the message.
+However, if you have discovered information concerning its
+cause, please let us know as described in @ref{BUGS}.
+
address@hidden 'root' is not allowed to commit files
+When committing a permanent change, @sc{cvs} makes a log entry of
+who committed the change. If you are committing the change logged
+in as "root" (not under "su" or other root-priv giving program),
address@hidden cannot determine who is actually making the change.
+As such, by default, @sc{cvs} disallows changes to be committed by users
+logged in as "root". (You can disable this option by passing the
address@hidden option to @file{configure} and recompiling @sc{cvs}.
+On some systems this means editing the appropriate @file{config.h} file
+before building @sc{cvs}.)
+
address@hidden Too many arguments!
+This message is typically printed by the @file{log.pl}
+script which is in the @file{contrib} directory in the
address@hidden source distribution. In some versions of
address@hidden, @file{log.pl} has been part of the default
address@hidden installation. The @file{log.pl} script gets
+called from the @file{loginfo} administrative file.
+Check that the arguments passed in @file{loginfo} match
+what your version of @file{log.pl} expects. In
+particular, the @file{log.pl} from @sc{cvs} 1.3 and
+older expects the logfile as an argument whereas the
address@hidden from @sc{cvs} 1.5 and newer expects the
+logfile to be specified with a @samp{-f} option. Of
+course, if you don't need @file{log.pl} you can just
+comment it out of @file{loginfo}.
+
address@hidden cvs [update aborted]: unexpected EOF reading @var{file},v
+See @samp{EOF in key in RCS file}.
+
address@hidden cvs [login aborted]: unrecognized auth response from @var{server}
+This message typically means that the server is not set
+up properly. For example, if @file{inetd.conf} points
+to a nonexistent cvs executable. To debug it further,
+find the log file which inetd writes
+(@file{/var/log/messages} or whatever inetd uses on
+your system). For details, see @ref{Connection}, and
address@hidden authentication server}.
+
address@hidden cvs commit: Up-to-date check failed for address@hidden'
+This means that someone else has committed a change to
+that file since the last time that you did a @code{cvs
+update}. So before proceeding with your @code{cvs
+commit} you need to @code{cvs update}. @sc{cvs} will merge
+the changes that you made and the changes that the
+other person made. If it does not detect any conflicts
+it will report @samp{M @var{file}} and you are ready
+to @code{cvs commit}. If it detects conflicts it will
+print a message saying so, will report @samp{C @var{file}},
+and you need to manually resolve the
+conflict. For more details on this process see
address@hidden example}.
+
address@hidden Usage: diff3 [-exEX3 [-i | -m] [-L label1 -L label3]] file1
file2 file3
address@hidden
+Only one of [exEX3] allowed
address@hidden example
+This indicates a problem with the installation of
address@hidden and @code{rcsmerge}. Specifically
address@hidden was compiled to look for GNU diff3, but
+it is finding unix diff3 instead. The exact text of
+the message will vary depending on the system. The
+simplest solution is to upgrade to a current version of
address@hidden, which does not rely on external
address@hidden or @code{diff3} programs.
+
address@hidden warning: unrecognized response address@hidden' from cvs server
+If @var{text} contains a valid response (such as
address@hidden) followed by an extra carriage return
+character (on many systems this will cause the second
+part of the message to overwrite the first part), then
+it probably means that you are using the @samp{:ext:}
+access method with a version of rsh, such as most
+non-unix rsh versions, which does not by default
+provide a transparent data stream. In such cases you
+probably want to try @samp{:server:} instead of
address@hidden:ext:}. If @var{text} is something else, this
+may signify a problem with your @sc{cvs} server.
+Double-check your installation against the instructions
+for setting up the @sc{cvs} server.
address@hidden FIXCVS: should be printing CR as \r or \015 or some
address@hidden such, probably.
+
address@hidden cvs commit: address@hidden waiting for @var{user}'s lock in
@var{directory}
+This is a normal message, not an error. See
address@hidden, for more details.
+
address@hidden cvs commit: warning: editor session failed
address@hidden Exit status, of editor
+This means that the editor which @sc{cvs} is using exits with a nonzero
+exit status. Some versions of vi will do this even when there was not
+a problem editing the file. If so, point the
address@hidden environment variable to a small script
+such as:
+
address@hidden
+#!/bin/sh
+vi $*
+exit 0
address@hidden example
+
address@hidden "warning: foo was lost" and "no longer pertinent" (both normal).
address@hidden Would be nice to write these up--they are
address@hidden potentially confusing for the new user.
address@hidden table
+
address@hidden Connection
address@hidden Trouble making a connection to a CVS server
+
+This section concerns what to do if you are having
+trouble making a connection to a @sc{cvs} server. If
+you are running the @sc{cvs} command line client
+running on Windows, first upgrade the client to
address@hidden 1.9.12 or later. The error reporting in
+earlier versions provided much less information about
+what the problem was. If the client is non-Windows,
address@hidden 1.9 should be fine.
+
+If the error messages are not sufficient to track down
+the problem, the next steps depend largely on which
+access method you are using.
+
address@hidden @code
address@hidden :ext:, troubleshooting
address@hidden :ext:
+Try running the rsh program from the command line. For
+example: "rsh servername cvs -v" should print @sc{cvs}
+version information. If this doesn't work, you need to
+fix it before you can worry about @sc{cvs} problems.
+
address@hidden :server:, troubleshooting
address@hidden :server:
+You don't need a command line rsh program to use this
+access method, but if you have an rsh program around,
+it may be useful as a debugging tool. Follow the
+directions given for :ext:.
+
address@hidden :pserver:, troubleshooting
address@hidden :pserver:
+Errors along the lines of "connection refused" typically indicate
+that inetd isn't even listening for connections on port 2401
+whereas errors like "connection reset by peer",
+"received broken pipe signal", "recv() from server: EOF",
+or "end of file from server"
+typically indicate that inetd is listening for
+connections but is unable to start @sc{cvs} (this is frequently
+caused by having an incorrect path in @file{inetd.conf}
+or by firewall software rejecting the connection).
+"unrecognized auth response" errors are caused by a bad command
+line in @file{inetd.conf}, typically an invalid option or forgetting
+to put the @samp{pserver} command at the end of the line.
+Another less common problem is invisible control characters that
+your editor "helpfully" added without you noticing.
+
+One good debugging tool is to "telnet servername
+2401". After connecting, send any text (for example
+"foo" followed by return). If @sc{cvs} is working
+correctly, it will respond with
+
address@hidden
+cvs [pserver aborted]: bad auth protocol start: foo
address@hidden example
+
+If instead you get:
+
address@hidden
+Usage: cvs [cvs-options] command [command-options-and-arguments]
+...
address@hidden example
+
address@hidden
+then you're missing the @samp{pserver} command at the end of the
+line in @file{inetd.conf}; check to make sure that the entire command
+is on one line and that it's complete.
+
+Likewise, if you get something like:
+
address@hidden
+Unknown command: `pserved'
+
+CVS commands are:
+ add Add a new file/directory to the repository
+...
address@hidden example
+
address@hidden
+then you've misspelled @samp{pserver} in some way. If it isn't
+obvious, check for invisible control characters (particularly
+carriage returns) in @file{inetd.conf}.
+
+If it fails to work at all, then make sure inetd is working
+right. Change the invocation in @file{inetd.conf} to run the
+echo program instead of cvs. For example:
+
address@hidden
+2401 stream tcp nowait root /bin/echo echo hello
address@hidden example
+
+After making that change and instructing inetd to
+re-read its configuration file, "telnet servername
+2401" should show you the text hello and then the
+server should close the connection. If this doesn't
+work, you need to fix it before you can worry about
address@hidden problems.
+
+On AIX systems, the system will often have its own
+program trying to use port 2401. This is AIX's problem
+in the sense that port 2401 is registered for use with
address@hidden I hear that there is an AIX patch available
+to address this problem.
+
+Another good debugging tool is the @samp{-d}
+(debugging) option to inetd. Consult your system
+documentation for more information.
+
+If you seem to be connecting but get errors like:
+
address@hidden
+cvs server: cannot open /root/.cvsignore: Permission denied
+cvs [server aborted]: can't chdir(/root): Permission denied
address@hidden example
+
address@hidden
+then you probably haven't specified @samp{-f} in @file{inetd.conf}.
+(In releases prior to @sc{cvs} 1.11.1, this problem can be caused by
+your system setting the @code{$HOME} environment variable
+for programs being run by inetd. In this case, you can either
+have inetd run a shell script that unsets @code{$HOME} and then runs
address@hidden, or you can use @code{env} to run @sc{cvs} with a pristine
+environment.)
+
+If you can connect successfully for a while but then can't,
+you've probably hit inetd's rate limit.
+(If inetd receives too many requests for the same service
+in a short period of time, it assumes that something is wrong
+and temporarily disables the service.)
+Check your inetd documentation to find out how to adjust the
+rate limit (some versions of inetd have a single rate limit,
+others allow you to set the limit for each service separately.)
address@hidden table
+
address@hidden Other problems
address@hidden Other common problems
+
+Here is a list of problems which do not fit into the
+above categories. They are in no particular order.
+
address@hidden @bullet
address@hidden
+On Windows, if there is a 30 second or so delay when
+you run a @sc{cvs} command, it may mean that you have
+your home directory set to @file{C:/}, for example (see
address@hidden and @code{HOMEPATH} in
address@hidden variables}). @sc{cvs} expects the home
+directory to not end in a slash, for example @file{C:}
+or @file{C:\cvs}.
address@hidden FIXCVS: CVS should at least detect this and print an
address@hidden error, presumably.
+
address@hidden
+If you are running @sc{cvs} 1.9.18 or older, and
address@hidden update} finds a conflict and tries to
+merge, as described in @ref{Conflicts example}, but
+doesn't tell you there were conflicts, then you may
+have an old version of @sc{rcs}. The easiest solution
+probably is to upgrade to a current version of
address@hidden, which does not rely on external @sc{rcs}
+programs.
address@hidden itemize
+
address@hidden
---------------------------------------------------------------------
address@hidden Credits
address@hidden Credits
+
address@hidden Contributors (manual)
address@hidden Credits (manual)
+Roland Pesch, then of Cygnus Support <@t{roland@@wrs.com}>
+wrote the manual pages which were distributed with
address@hidden 1.3. Much of their text was copied into this
+manual. He also read an early draft
+of this manual and contributed many ideas and
+corrections.
+
+The mailing-list @code{info-cvs} is sometimes
+informative. I have included information from postings
+made by the following persons:
+David G. Grubbs <@t{dgg@@think.com}>.
+
+Some text has been extracted from the man pages for
address@hidden
+
+The @sc{cvs} @sc{faq} by David G. Grubbs has provided
+useful material. The @sc{faq} is no longer maintained,
+however, and this manual is about the closest thing there
+is to a successor (with respect to documenting how to
+use @sc{cvs}, at least).
+
+In addition, the following persons have helped by
+telling me about mistakes I've made:
+
address@hidden
+Roxanne Brunskill <@t{rbrunski@@datap.ca}>,
+Kathy Dyer <@t{dyer@@phoenix.ocf.llnl.gov}>,
+Karl Pingle <@t{pingle@@acuson.com}>,
+Thomas A Peterson <@t{tap@@src.honeywell.com}>,
+Inge Wallin <@t{ingwa@@signum.se}>,
+Dirk Koschuetzki <@t{koschuet@@fmi.uni-passau.de}>
+and Michael Brown <@t{brown@@wi.extrel.com}>.
address@hidden display
+
+The list of contributors here is not comprehensive; for a more
+complete list of who has contributed to this manual see
+the file @file{doc/ChangeLog} in the @sc{cvs} source
+distribution.
+
address@hidden
---------------------------------------------------------------------
address@hidden BUGS
address@hidden Dealing with bugs in CVS or this manual
+
address@hidden Bugs in this manual or CVS
+Neither @sc{cvs} nor this manual is perfect, and they
+probably never will be. If you are having trouble
+using @sc{cvs}, or think you have found a bug, there
+are a number of things you can do about it. Note that
+if the manual is unclear, that can be considered a bug
+in the manual, so these problems are often worth doing
+something about as well as problems with @sc{cvs} itself.
+
address@hidden Reporting bugs
address@hidden Bugs, reporting
address@hidden Errors, reporting
address@hidden @bullet
address@hidden
+If you want someone to help you and fix bugs that you
+report, there are companies which will do that for a
+fee. One such company is:
+
address@hidden Ximbiot
address@hidden Support, getting CVS support
address@hidden
+Ximbiot
+319 S. River St.
+Harrisburg, PA 17104-1657
+USA
+Email: info@@ximbiot.com
+Phone: (717) 579-6168
+Fax: (717) 234-3125
+http://ximbiot.com/
+
address@hidden example
+
address@hidden
+If you got @sc{cvs} through a distributor, such as an
+operating system vendor or a vendor of freeware
address@hidden, you may wish to see whether the
+distributor provides support. Often, they will provide
+no support or minimal support, but this may vary from
+distributor to distributor.
+
address@hidden
+If you have the skills and time to do so, you may wish
+to fix the bug yourself. If you wish to submit your
+fix for inclusion in future releases of @sc{cvs}, see
+the file @sc{hacking} in the @sc{cvs} source
+distribution. It contains much more information on the
+process of submitting fixes.
+
address@hidden
+There may be resources on the net which can help. Two
+good places to start are:
+
address@hidden
+http://www.cvshome.org
+http://www.loria.fr/~molli/cvs-index.html
address@hidden example
+
+If you are so inspired, increasing the information
+available on the net is likely to be appreciated. For
+example, before the standard @sc{cvs} distribution
+worked on Windows 95, there was a web page with some
+explanation and patches for running @sc{cvs} on Windows
+95, and various people helped out by mentioning this
+page on mailing lists or newsgroups when the subject
+came up.
+
address@hidden
+It is also possible to report bugs to @code{bug-cvs}.
+Note that someone may or may not want to do anything
+with your bug report---if you need a solution consider
+one of the options mentioned above. People probably do
+want to hear about bugs which are particularly severe
+in consequences and/or easy to fix, however. You can
+also increase your odds by being as clear as possible
+about the exact nature of the bug and any other
+relevant information. The way to report bugs is to
+send email to @code{bug-cvs@@gnu.org}. Note
+that submissions to @code{bug-cvs} may be distributed
+under the terms of the @sc{gnu} Public License, so if
+you don't like this, don't submit them. There is
+usually no justification for sending mail directly to
+one of the @sc{cvs} maintainers rather than to
address@hidden; those maintainers who want to hear
+about such bug reports read @code{bug-cvs}. Also note
+that sending a bug report to other mailing lists or
+newsgroups is @emph{not} a substitute for sending it to
address@hidden It is fine to discuss @sc{cvs} bugs on
+whatever forum you prefer, but there are not
+necessarily any maintainers reading bug reports sent
+anywhere except @code{bug-cvs}.
address@hidden itemize
+
address@hidden Known bugs in this manual or CVS
+People often ask if there is a list of known bugs or
+whether a particular bug is a known one. The file
address@hidden in the @sc{cvs} source distribution is one
+list of known bugs, but it doesn't necessarily try to
+be comprehensive. Perhaps there will never be a
+comprehensive, detailed list of known bugs.
+
address@hidden
---------------------------------------------------------------------
address@hidden Index
address@hidden Index
address@hidden Index
+
address@hidden cp
+
address@hidden
+
address@hidden
+
address@hidden
Index: res_info/texi_hello/hello.texi.first
===================================================================
RCS file: res_info/texi_hello/hello.texi.first
diff -N res_info/texi_hello/hello.texi.first
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ res_info/texi_hello/hello.texi.first 2 Aug 2009 13:11:04 -0000
1.1
@@ -0,0 +1,789 @@
+\input texinfo @c -*-texinfo-*-
address@hidden %**start of header
address@hidden hello.info
address@hidden UPDATED 28 March 2002
address@hidden UPDATED-MONTH March 2002
address@hidden EDITION 4.2
address@hidden VERSION 4.2
address@hidden GNU Hello 4.2
address@hidden %**end of header
+
address@hidden If your manual is published on paper by the FSF, it should
include
address@hidden the standard FSF Front-Cover and Back-Cover Texts, as given in
address@hidden maintain.texi.
+
address@hidden Define a new index for options.
address@hidden op
address@hidden Combine everything into one index (arbitrarily chosen to be the
address@hidden concept index).
address@hidden op cp
+
address@hidden Basics
address@hidden
+* Hello: (hello). Hello, GNU world.
address@hidden direntry
+
+
address@hidden
+
+
address@hidden Top
address@hidden GNU Hello
+
+This manual is for GNU Hello (version 4.2, 28 March 2002).
+
address@hidden
+* Overview:: General purpose and information.
+* Sample output:: Sample output from @command{hello}.
+* Invoking hello:: How to run @command{hello}.
+* Reporting bugs:: Sending bug reports and feature suggestions.
+* GNU Free Documentation License:: Copying and sharing this documentation.
+* Concept index:: Index of concepts.
address@hidden menu
+
+
address@hidden Overview
address@hidden Overview
+
address@hidden greetings
address@hidden overview
+
+The GNU @command{hello} program
+(@url{http://www.gnu.org/software/hello/}) produces a familiar,
+friendly greeting. It allows nonprogrammers to use a classic computer
+science tool which would otherwise be unavailable to them. Because it
+is protected by the GNU General Public License, users are free (in
+perpetuity) to share and change it.
+
address@hidden joke, not
+Not to spoil the joke, but of course the practical purpose of GNU
+Hello is to serve as a minimal example of a GNU package. So, although
+most manuals don't need to discuss the implementation of the programs
+they document, that is part of the goal here.
+
address@hidden GNU coding standards
address@hidden GNU maintainer standards
address@hidden standards, GNU coding
address@hidden standards, GNU maintainer
+First, GNU Hello follows the GNU coding standards
+(@pxref{Top,,Preface,standards, GNU Coding Standards}) and GNU
+maintainer standards (@pxref{Top,,Preface,maintain, Information for
+GNU Maintainers}). These are the basic documents which all GNU
+packages should adhere to.
+
+The Hello package also implements recommended development practices
+not embodied in the standards, using other GNU packages and features:
+
address@hidden @bullet
+
address@hidden
address@hidden Automake
address@hidden Autoconf
+It uses Automake (@pxref{Top,,Introduction,Automake,GNU Automake}) and
+hence also Autoconf (@pxref{Top,,Introduction,Autoconf,GNU Autoconf})
+for configuration.
+
address@hidden
address@hidden Gnulib
+It uses Gnulib (@pxref{Top,,Gnulib,gnulib,GNU Gnulib}) to enhance
+portability and avoid duplication of common sources.
+
address@hidden
address@hidden Gettext
+GNU Gettext (@pxref{Top,,Introduction,gettext,GNU Gettext}) is used
+for internationalization support. Hello's greeting has been translated
+into many languages.
+
address@hidden
address@hidden --help
+Internally, Hello uses the GNU @code{getopt_long} function
+(@pxref{Getopt Long Options,,,libc,GNU C Library}) to parse options,
+thus supporting GNU-style long options such as @option{--help}.
+
address@hidden
address@hidden Help2man
+Man pages are generated with GNU @code{help2man}
+(@pxref{Top,,Overview,help2man,GNU @code{help2man}}) from the
address@hidden output. This relieves the maintainers of the burden
+of maintaining man documentation separately, yet provides a reasonable
+overview for man devotees.
+
address@hidden
address@hidden Texinfo
+Finally, Texinfo (@pxref{Top,,Introduction,texinfo,Texinfo}) is the
+documentation format for this manual. It supports output in Info,
+HTML, PDF, DVI, plain text, XML, and other formats.
+
address@hidden itemize
+
+GNU Hello is implemented in C. GNU Gettext contains ``hello world''
+examples in a variety of other programming languages; see the Gettext
+home page at @url{http://www.gnu.org/software/gettext/}.
+
address@hidden authors
address@hidden Haertel, Mike
address@hidden MacKenzie, David
address@hidden Brittenson, Jan
address@hidden Hannum, Charles
address@hidden McGrath, Roland
address@hidden Friedman, Noah
address@hidden Eichwalder, Karl
address@hidden King, The
address@hidden Berry, Karl
+GNU Hello was written by Mike Haertel, David MacKenzie, Jan
+Brittenson, Charles Hannum, Roland McGrath, Noah Friedman, Karl
+Eichwalder, Karl Berry, and @w{The King}.
+
+
address@hidden Sample output
address@hidden Sample output
+
address@hidden sample output
address@hidden examples
+
+Here are some realistic examples of running GNU Hello.
+
+This is the output of the command @samp{hello}:
+
address@hidden
+Hello, world!
address@hidden example
+
+This is the output of the command @samp{hello --traditional}:
+
address@hidden
+hello, world
address@hidden example
+
+This is the output of the command @samp{hello --greeting=hi}:
+
address@hidden
+hi
address@hidden example
+
+
address@hidden Invoking hello
address@hidden Invoking @command{hello}
+
address@hidden invoking
address@hidden options
address@hidden usage
address@hidden help
+
+The format for running the @command{hello} program is:
+
address@hidden
+hello @var{option} @dots{}
address@hidden example
+
+With no options, @command{hello} prints the greeting @samp{Hello,
+world!}.
+
address@hidden supports the following options:
+
address@hidden @option
address@hidden address@hidden
address@hidden -g @var{text}
address@hidden --greeting
address@hidden -g
+Output @var{text} instead of the default greeting.
+
address@hidden --help
address@hidden -h
address@hidden --help
address@hidden -h
+Print an informative help message on standard output and exit
+successfully.
+
address@hidden environment variables, help for
+For the @option{--help} output of GNU programs, it's strongly
+encouraged to include a brief (one or two sentences) description of
+what the program does, as well as the synopsis of how to run the
+program. Any environment variables which affect execution should also
+be mentioned (Hello doesn't have any).
+
address@hidden --next-generation
address@hidden -n
address@hidden --next-generation
address@hidden -n
+Output @samp{Hello, world!}, but possibly including box-drawing
+characters or other fancy stuff, especially in translated locales.
+(If you would like to volunteer to translate messages for GNU packages,
+please see @url{http://translationproject.org}.)
+
address@hidden --traditional
address@hidden -t
address@hidden --traditional
address@hidden -t
address@hidden traditional
address@hidden modern
+Output the traditional greeting message @samp{hello, world}.
+
address@hidden --version
address@hidden -v
address@hidden --version
address@hidden -v
+Print the version number and licensing information of Hello on
+standard output and then exit successfully.
+
address@hidden table
+
+If more than one of the greeting options (@option{-g}, @option{-n},
address@hidden, and their long-named equivalents) is specified, whichever
+comes last takes precedence.
+
+
address@hidden Reporting bugs
address@hidden Reporting bugs
+
address@hidden bug reporting
address@hidden problems
address@hidden reporting bugs
+
+To report bugs or suggest enhancements for GNU Hello, please
+send electronic mail to @email{bug-hello@@gnu.org}.
+
address@hidden checklist for bug reports
+For bug reports, please include enough information for the maintainers
+to reproduce the problem. Generally speaking, that means:
+
address@hidden @bullet
address@hidden The version numbers of Hello (which you can find by running
+ @address@hidden --version}}) and any other program(s) or
+ manual(s) involved.
address@hidden Hardware and operating system names and versions.
address@hidden The contents of any input files necessary to reproduce the bug.
address@hidden The expected behavior and/or output.
address@hidden A description of the problem and samples of any erroneous output.
address@hidden Options you gave to @command{configure} other than specifying
+ installation directories.
address@hidden Anything else that you think would be helpful.
address@hidden 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.
+
address@hidden patches, contributing
+Patches are welcome; if possible, please make them with @address@hidden
+-c}} (@pxref{Top,, Overview, diff, Comparing and Merging Files}) and
+include @file{ChangeLog} entries (@pxref{Change Log,,, emacs, The GNU
+Emacs Manual}). Please follow the existing coding style.
+
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
+
address@hidden The GNU Free Documentation License.
address@hidden Version 1.3, 3 November 2008
+
address@hidden This file is intended to be included within another document,
address@hidden hence no sectioning command or @node.
+
address@hidden
+Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation,
Inc.
address@hidden://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
address@hidden display
+
address@hidden 0
address@hidden
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{free} in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
address@hidden
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The ``Document'', below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as ``you''. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section
+of the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall
+subject (or to related matters) and contains nothing that could fall
+directly within that overall subject. (Thus, if the Document is in
+part a textbook of mathematics, a Secondary Section may not explain
+any mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
address@hidden without markup, Texinfo input format, address@hidden input
+format, @acronym{SGML} or @acronym{XML} using a publicly available
address@hidden, and standard-conforming simple @acronym{HTML},
+PostScript or @acronym{PDF} designed for human modification. Examples
+of transparent image formats include @acronym{PNG}, @acronym{XCF} and
address@hidden Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, @acronym{SGML} or
address@hidden for which the @acronym{DTD} and/or processing tools are
+not generally available, and the machine-generated @acronym{HTML},
+PostScript or @acronym{PDF} produced by some word processors for
+output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+The ``publisher'' means any person or entity that distributes copies
+of the Document to the public.
+
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements'',
+``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
address@hidden
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
address@hidden
+COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
address@hidden
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
address@hidden A
address@hidden
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
address@hidden
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
+
address@hidden
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
address@hidden
+Preserve all the copyright notices of the Document.
+
address@hidden
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
address@hidden
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
address@hidden
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
address@hidden
+Include an unaltered copy of this License.
+
address@hidden
+Preserve the section Entitled ``History'', Preserve its Title, and add
+to it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section Entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
address@hidden
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
address@hidden
+For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
+the Title of the section, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements and/or
+dedications given therein.
+
address@hidden
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
address@hidden
+Delete any section Entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
address@hidden
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
address@hidden
+Preserve any Warranty Disclaimers.
address@hidden enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
address@hidden
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements'',
+and any sections Entitled ``Dedications''. You must delete all
+sections Entitled ``Endorsements.''
+
address@hidden
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
address@hidden
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
address@hidden
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
address@hidden
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document
+except as expressly provided under this License. Any attempt
+otherwise to copy, modify, sublicense, or distribute it is void, and
+will automatically terminate your rights under this License.
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License. If your rights have been terminated and not permanently
+reinstated, receipt of a copy of some or all of the same material does
+not give you any rights to use it.
+
address@hidden
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
address@hidden://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation. If the Document
+specifies that a proxy can decide which future versions of this
+License can be used, that proxy's public statement of acceptance of a
+version permanently authorizes you to choose that version for the
+Document.
+
address@hidden
+RELICENSING
+
+``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
+World Wide Web server that publishes copyrightable works and also
+provides prominent facilities for anybody to edit those works. A
+public wiki that anybody can edit is an example of such a server. A
+``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
+site means any set of copyrightable works thus published on the MMC
+site.
+
+``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
+license published by Creative Commons Corporation, a not-for-profit
+corporation with a principal place of business in San Francisco,
+California, as well as future copyleft versions of that license
+published by that same organization.
+
+``Incorporate'' means to publish or republish a Document, in whole or
+in part, as part of another Document.
+
+An MMC is ``eligible for relicensing'' if it is licensed under this
+License, and if all works that were first published under this License
+somewhere other than this MMC, and subsequently incorporated in whole
+or in part into the MMC, (1) had no cover texts or invariant sections,
+and (2) were thus incorporated prior to November 1, 2008.
+
+The operator of an MMC Site may republish an MMC contained in the site
+under CC-BY-SA on the same site at any time before August 1, 2009,
+provided the MMC is eligible for relicensing.
+
address@hidden enumerate
+
address@hidden
address@hidden ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
address@hidden
address@hidden
+ Copyright (C) @var{year} @var{your name}.
+ 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, no Front-Cover Texts, and no Back-Cover
+ Texts. A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
address@hidden group
address@hidden smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the address@hidden'' line with this:
+
address@hidden
address@hidden
+ with the Invariant Sections being @var{list their titles}, with
+ the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
+ being @var{list}.
address@hidden group
address@hidden smallexample
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
address@hidden Local Variables:
address@hidden ispell-local-pdict: "ispell-dict"
address@hidden End:
+
+
+
address@hidden Concept index
address@hidden Concept index
+
address@hidden cp
+
address@hidden
Index: res_info/texi_info-stnd/info-stnd.texi.first
===================================================================
RCS file: res_info/texi_info-stnd/info-stnd.texi.first
diff -N res_info/texi_info-stnd/info-stnd.texi.first
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ res_info/texi_info-stnd/info-stnd.texi.first 2 Aug 2009 13:11:05
-0000 1.1
@@ -0,0 +1,2540 @@
+\input texinfo @c -*-texinfo-*-
address@hidden Id: info-stnd.texi,v 1.1 2003/02/03 16:10:29 pertusus Exp $
address@hidden %**start of header
address@hidden info-stnd.info
address@hidden UPDATED 23 March 2002
address@hidden UPDATED-MONTH March 2002
address@hidden EDITION 4.2
address@hidden VERSION 4.2
address@hidden GNU Info 4.2
address@hidden vr cp
address@hidden fn cp
address@hidden ky cp
address@hidden %**end of header
+
+
address@hidden Texinfo documentation system
address@hidden
+* info standalone: (info-stnd). Read Info documents without Emacs.
+* infokey: (info-stnd)Invoking infokey. Compile Info customizations.
address@hidden direntry
+
+
address@hidden
+
address@hidden Top
address@hidden GNU Info
+
+This manual is for GNU Info (version 4.2, 23 March 2002),
+a program for viewing documents in Info format (usually created from
+Texinfo source files).
+
+Copyright @copyright{} 1992, 93, 96, 97, 98, 99, 2001, 02
+Free Software Foundation, Inc.
+
address@hidden
+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.''
address@hidden quotation
+
+This documentation is different from the documentation for the Info
+reader that is part of GNU Emacs. If you do not know how to use Info,
+but have a working Info reader, you should read the Emacs documentation
+first, as it includes more background information and a thorough tutorial.
+
address@hidden
+* What is Info:: What is Info?
+* Invoking Info:: Options you can pass on the command line.
+* Cursor Commands:: Commands which move the cursor within a node.
+* Scrolling Commands:: Commands for reading the text within a node.
+* Node Commands:: Commands for selecting a new node.
+* Searching Commands:: Commands for searching an Info file.
+* Xref Commands:: Commands for selecting cross references.
+* Window Commands:: Commands which manipulate multiple windows.
+* Printing Nodes:: How to print out the contents of a node.
+* Miscellaneous Commands:: A few commands that defy categories.
+* Variables:: How to change the default behavior of Info.
+* Custom Key Bindings:: How to define your own key-to-command
+ bindings.
+* Copying This Manual:: The GNU Free Documentation License.
+* Index:: Global index containing keystrokes,
+ command names, variable names,
+ and general concepts.
address@hidden menu
+
+
address@hidden What is Info
address@hidden What is Info?
+
address@hidden is a program which is used to view Info files on an ASCII
+terminal. @dfn{Info files} are the result of processing Texinfo files
+with the program @code{makeinfo} or with one of the Emacs commands, such
+as @code{M-x texinfo-format-buffer}. Texinfo itself is a documentation
+system that uses a single source file to produce both on-line
+information and printed output. You can typeset and print the files
+that you read in Info.
+
+
address@hidden Invoking Info
address@hidden Invoking Info
+
address@hidden Info, invoking
address@hidden invoking Info
address@hidden command line options
address@hidden options, command line
address@hidden arguments, command line
+
+GNU Info accepts several options to control the initial node being
+viewed, and to specify which directories to search for Info files. Here
+is a template showing an invocation of GNU Info from the shell:
+
address@hidden
+info address@hidden@dots{} address@hidden@dots{}]
address@hidden example
+
+The program accepts the following options:
+
address@hidden @code
address@hidden
address@hidden address@hidden
address@hidden Searching all indices
address@hidden Info address@hidden, searching all indices}
address@hidden address@hidden, in Info files}
+Specify a string to search in every index of every Info file installed
+on your system. Info looks up the named @var{string} in all the indices
+it can find, prints the results to standard output, and then exits. If
+you are not sure which Info file explains certain issues, this option is
+your friend. Note that if your system has a lot of Info files
+installed, searching all of them might take some time.
+
+You can invoke the apropos command from inside Info; see
address@hidden Commands}.
+
address@hidden directory path
address@hidden --directory @var{directory-path}
address@hidden -d @var{directory-path}
+Prepend @var{directory-path} to the list of directory paths searched
+when Info needs to find a file. You may issue @code{--directory}
+multiple times; once for each directory which contains Info files. The
+list of directories searched by Info is constructed from the value of
+the environment variable @code{INFOPATH}; @code{--directory} causes the
+named @var{directory-path} to be prepended to that list. The value of
address@hidden is a list of directories usually separated by a colon;
+on MS-DOS/MS-Windows systems, the semicolon is used. If you do not
+define @code{INFOPATH}, Info uses a default path defined when Info was
+built as the initial list of directories. If the value of
address@hidden ends with a colon (or semicolon on MS-DOS/MS-Windows),
+the initial list of directories is constructed by appending the
+build-time default to the value of @code{INFOPATH}.
+
address@hidden keystrokes, recording
address@hidden remembering user keystrokes
address@hidden address@hidden
+Specify a file where all user keystrokes will be recorded. This file
+can be used later to replay the same sequence of commands, see the
address@hidden option below.
+
address@hidden --file @var{filename}
address@hidden -f @var{filename}
address@hidden Info file, selecting
+Specify a particular Info file to visit. By default, Info visits
+the file @code{dir}; if you use this option, Info will start with
address@hidden(@var{filename})Top} as the first file and node.
+
address@hidden relative Info file names
address@hidden file names, relative
address@hidden Info files, relative
+If @var{filename} is an absolute file name, or begins with @file{./} or
address@hidden/}, Info looks for @var{filename} only in the directory of the
+specified @var{filename}, and adds the directory of @var{filename} to
+the value of @code{INFOPATH}. In contrast, if @var{filename} is in the
+form of a relative file name, but without the @file{./} or @file{../}
+prefix, Info will only look for it in the directories specified in
address@hidden In other words, Info does @emph{not} treat file names
+which lack @file{./} and @file{../} prefix as relative to the current
+directory.
+
address@hidden compressed Info files
address@hidden files, compressed
address@hidden Info files, compressed
+In every directory Info tries, if @var{filename} is not found, Info
+looks for it with a number of known extensions of Info address@hidden
address@hidden, @file{-info}, @file{/index}, and @file{.inf}.}. For every
+known extension, Info looks for a compressed file, if a regular file
+isn't found. Info supports files compressed with @code{gzip},
address@hidden, @code{compress} and @code{yabba} programs; it calls
address@hidden, @code{bunzip2}, @code{uncompress} and @code{unyabba},
+accordingly, to decompress such files. Compressed Info files are
+assumed to have @file{.z}, @file{.gz}, @file{.bz2}, @file{.Z}, or
address@hidden extensions, possibly in addition to one of the known Info
+files address@hidden MS-DOS version allows for the Info
+extension, such as @code{.inf}, and the short compressed file
+extensions, such as @file{.z} and @file{.gz}, to be merged into a single
+extension, since DOS doesn't allow more than a single dot in the
+basename of a file. Thus, on MS-DOS, if Info looks for @file{bison},
+file names like @file{bison.igz} and @file{bison.inz} will be found and
+decompressed by @code{gunzip}.}.
+
address@hidden --help
address@hidden -h
+Produces a relatively brief description of the available Info options.
+
address@hidden --index-search @var{string}
address@hidden index search, selecting from the command line
address@hidden online help, using Info as
+After processing all command-line arguments, go to the index in the Info
+file and search for index entries which matche @var{string}. If such an
+entry is found, the Info session begins with displaying the node pointed
+to by the first matching index entry; press @kbd{,} to step through the
+rest of the matching entries. If no such entry exists, print @samp{no
+entries found} and exit with nonzero status. This can be used from
+another program as a way to provide online help, or as a quick way of
+starting to read an Info file at a certain node when you don't know the
+exact name of that node.
+
+This command can also be invoked from inside Info; see @ref{Searching
+Commands}.
+
address@hidden --node @var{nodename}
address@hidden -n @var{nodename}
address@hidden node, selecting from the command line
+Specify a particular node to visit in the initial file that Info
+loads. This is especially useful in conjunction with
address@hidden@footnote{Of course, you can specify both the file and node
+in a @code{--node} command; but don't forget to escape the open and
+close parentheses and whitespace from the shell as in: @code{info --node
+"(emacs)Buffers"}.}. You may specify @code{--node} multiple times; for
+an interactive Info, each @var{nodename} is visited in its own window,
+for a non-interactive Info (such as when @code{--output} is given) each
address@hidden is processed sequentially.
+
address@hidden --output @var{filename}
address@hidden -o @var{filename}
address@hidden file, outputting to
address@hidden outputting to a file
+Specify @var{filename} as the name of a file to which to direct output.
+Each node that Info visits will be output to @var{filename} instead of
+interactively viewed. A value of @code{-} for @var{filename} specifies
+the standard output.
+
address@hidden colors in man pages
address@hidden ANSI escape sequences in man pages
address@hidden --raw-escapes
address@hidden -R
+Do not remove ANSI escape sequences from man pages. Some versions of
+Groff, the GNU document formatter, produce man pages with ANSI escape
+sequences for bold, italics, and underlined characters, and for
+colorized text. By default, Info removes those escape sequences
+before it displays the man page. If your terminal supports these
+escapes, use @code{--raw-escapes} to let the terminal handle them and
+display the man pages with those attributes.
+
address@hidden replaying recorded keystrokes
address@hidden address@hidden
+Read keystrokes from @var{dribble-file}, presumably recorded during
+previous Info session (see the description of the @samp{--dribble}
+option above). When the keystrokes in the files are all read, Info
+reverts its input to the usual interactive operation.
+
address@hidden
address@hidden command-line options, how to find
address@hidden invocation description, how to find
address@hidden --show-options
address@hidden --usage
address@hidden -O
+This option causes Info to look for the node that describes how to
+invoke the program and its command-line options, and begin the session
+by displaying that node. It is provided to make it easier to find the
+most important usage information in a manual without the need to wade
+through complex menu hierarchies. The effect is similar to the
address@hidden goto-invocation} command (@pxref{goto-invocation}) from inside
+Info.
+
address@hidden speech synthesizers
address@hidden --speech-friendly
address@hidden -b
+On MS-DOS/MS-Windows only, this option causes Info to use standard file
+I/O functions for screen writes. (By default, Info uses direct writes
+to the video memory on these systems, for faster operation and colored
+display support.) This allows the speech synthesizers used by blind
+persons to catch the output and convert it to audible speech.
+
address@hidden --subnodes
address@hidden @code{--subnodes}, command line option
+This option only has meaning when given in conjunction with
address@hidden It means to recursively output the nodes appearing in
+the menus of each node being output. Menu items which resolve to
+external Info files are not output, and neither are menu items which are
+members of an index. Each node is only output once.
+
address@hidden --version
address@hidden version information
+Prints the version information of Info and exits.
+
address@hidden
address@hidden vi-like key bindings
address@hidden Less-like key bindings
address@hidden --vi-keys
+This option binds functions to keys differently, to emulate the key
+bindings of @code{vi} and Less. The default key bindings are generally
+modeled after Emacs.
+(@xref{Custom Key Bindings},
+for a more general way of altering GNU Info's key bindings.)
+
address@hidden @var{menu-item}
address@hidden menu, following
address@hidden menu items}
+Info treats its remaining arguments as the names of menu items. The
+first argument is a menu item in the initial node visited (generally
address@hidden), the second argument is a menu item in the first argument's
+node, etc. You can easily move to the node of your choice by specifying
+the menu names which describe the path to that node. For example,
+
address@hidden
+info emacs buffers
address@hidden example
+
address@hidden
+first selects the menu item @samp{Emacs} in the node @samp{(dir)Top},
+and then selects the menu item @samp{Buffers} in the node
address@hidden(emacs)Top}.
address@hidden table
+
+To avoid searching the @file{dir} files and just show some arbitrary
+file, use @samp{-f} and the filename, as in @samp{info -f ./foo.info}.
+
+The index search and the search for the node which describes program
+invocation and command-line options begins @emph{after} processing all
+the command-line menu items. Therefore, the Info file searched for the
+index or the invocation node is the file where Info finds itself after
+following all the menu items given on the command line. This is so
address@hidden emacs --show-options} does what you'd expect.
+
address@hidden FIXME: the feature with lowercasing the file name isn't
documented
+
+
address@hidden Cursor Commands
address@hidden Moving the Cursor
address@hidden cursor, moving
address@hidden moving the cursor
+
+Many people find that reading screens of text page by page is made
+easier when one is able to indicate particular pieces of text with some
+kind of pointing device. Since this is the case, GNU Info (both the
+Emacs and standalone versions) have several commands which allow you to
+move the cursor about the screen. The notation used in this manual to
+describe keystrokes is identical to the notation used within the Emacs
+manual, and the GNU Readline manual. @xref{Characters, , Character
+Conventions, emacs, the GNU Emacs Manual}, if you are unfamiliar with the
address@hidden
+Here's a short summary. @address@hidden means press the @kbd{CTRL} key
+and the key @var{x}. @address@hidden means press the @kbd{META} key and
+the key @var{x}. On many terminals th @kbd{META} key is known as the
address@hidden key. @kbd{SPC} is the space bar. The other keys are usually
+called by the names imprinted on them.}.
+
+The following table lists the basic cursor movement commands in Info.
+Each entry consists of the key sequence you should type to execute the
+cursor movement, the @address@hidden@code{M-x} is also a command; it
+invokes @code{execute-extended-command}. @xref{M-x, , Executing an
+extended command, emacs, the GNU Emacs Manual}, for more detailed
+information.} command name (displayed in parentheses), and a short
+description of what the command does. All of the cursor motion commands
+can take a @dfn{numeric} argument (see @ref{Miscellaneous Commands,
address@hidden, to find out how to supply them}. With a
+numeric argument, the motion commands are simply executed that
+many times; for example, a numeric argument of 4 given to
address@hidden causes the cursor to move down 4 lines. With a
+negative numeric argument, the motion is reversed; an argument of -4
+given to the @code{next-line} command would cause the cursor to move
address@hidden 4 lines.
+
address@hidden @asis
address@hidden @key{C-n} (@code{next-line})
address@hidden @key{DOWN} (an arrow key)
address@hidden C-n
address@hidden DOWN (an arrow key)
address@hidden next-line
+Move the cursor down to the next line.
+
address@hidden @key{C-p} (@code{prev-line})
address@hidden @key{UP} (an arrow key)
address@hidden C-p
address@hidden UP (an arrow key)
address@hidden prev-line
+Move the cursor up to the previous line.
+
address@hidden @key{C-a} (@code{beginning-of-line})
address@hidden @key{Home} (on DOS/Windows only)
address@hidden C-a, in Info windows
address@hidden Home
address@hidden beginning-of-line
+Move the cursor to the start of the current line.
+
address@hidden @key{C-e} (@code{end-of-line})
address@hidden @key{End} (on DOS/Windows only)
address@hidden C-e, in Info windows
address@hidden End
address@hidden end-of-line
+Move the cursor to the end of the current line.
+
address@hidden @key{C-f} (@code{forward-char})
address@hidden @key{RIGHT} (an arrow key)
address@hidden C-f, in Info windows
address@hidden RIGHT (an arrow key)
address@hidden forward-char
+Move the cursor forward a character.
+
address@hidden @key{C-b} (@code{backward-char})
address@hidden @key{LEFT} (an arrow key)
address@hidden C-b, in Info windows
address@hidden LEFT (an arrow key)
address@hidden backward-char
+Move the cursor backward a character.
+
address@hidden @key{M-f} (@code{forward-word})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden M-f, in Info windows
address@hidden C-RIGHT
address@hidden forward-word
+Move the cursor forward a word.
+
address@hidden @key{M-b} (@code{backward-word})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden M-b, in Info windows
address@hidden C-LEFT
address@hidden backward-word
+Move the cursor backward a word.
+
address@hidden @key{M-<} (@code{beginning-of-node})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden @key{b}
address@hidden @key{M-b}, vi-like operation
address@hidden b, in Info windows
address@hidden M-<
address@hidden C-Home
address@hidden M-b, vi-like operation
address@hidden beginning-of-node
+Move the cursor to the start of the current node.
+
address@hidden @key{M->} (@code{end-of-node})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden @key{e}
address@hidden M->
address@hidden e, in Info windows
address@hidden C-End
address@hidden end-of-node
+Move the cursor to the end of the current node.
+
address@hidden @key{M-r} (@code{move-to-window-line})
address@hidden M-r
address@hidden move-to-window-line
+Move the cursor to a specific line of the window. Without a numeric
+argument, @code{M-r} moves the cursor to the start of the line in the
+center of the window. With a numeric argument of @var{n}, @code{M-r}
+moves the cursor to the start of the @var{n}th line in the window.
address@hidden table
+
+
address@hidden Scrolling Commands
address@hidden Moving Text Within a Window
address@hidden scrolling
+
+Sometimes you are looking at a screenful of text, and only part of the
+current paragraph you are reading is visible on the screen. The
+commands detailed in this section are used to shift which part of the
+current node is visible on the screen.
+
+Scrolling commands are bound differently when @samp{--vi-keys} operation
+(@pxref{--vi-keys}) is in effect. These key bindings are designated
+with ``vi-like operation''.
+
address@hidden @asis
address@hidden @key{SPC} (@code{scroll-forward})
address@hidden SPC, in Info windows
address@hidden scroll-forward
+Shift the text in this window up. That is, show more of the node which
+is currently below the bottom of the window. With a numeric argument,
+show that many more lines at the bottom of the window; a numeric
+argument of 4 would shift all of the text in the window up 4 lines
+(discarding the top 4 lines), and show you four new lines at the bottom
+of the window. Without a numeric argument, @key{SPC} takes the bottom
+two lines of the window and places them at the top of the window,
+redisplaying almost a completely new screenful of lines. If you are at
+the end of a node, @key{SPC} takes you to the ``next'' node, so that you can
+read an entire manual from start to finish by repeating @key{SPC}.
+
+The default scroll size is one screen-full, but it can be changed by
+invoking the (@code{scroll-forward-page-only-set-window}) command,
address@hidden under @samp{--vi-keys}, with a numeric argument.
+
address@hidden @key{NEXT} (an arrow key) (@code{scroll-forward-page-only})
address@hidden @key{C-v}
address@hidden @key{C-f}, vi-like operation
address@hidden @key{f}, vi-like operation
address@hidden @key{M-SPC}, vi-like operation
address@hidden NEXT
address@hidden C-v
address@hidden C-f, vi-like operation
address@hidden f, vi-like operation
address@hidden M-SPC, vi-like operation
address@hidden scroll-forward-page-only
+Shift the text in this window up. This is identical to the @key{SPC}
+operation above, except that it never scrolls beyond the end of the
+current node.
+
address@hidden PageDown
+The @key{NEXT} key is known as the @key{PageDown} key on some
+keyboards.
+
address@hidden @key{z} (@code{scroll-forward-page-only-set-window}, vi-like
operation)
address@hidden z, vi-like operation
address@hidden scroll-forward-page-only-set-window
+Scroll forward, like with @key{NEXT}, but if a numeric argument is
+specified, it becomes the default scroll size for subsequent
address@hidden and @code{scroll-backward} commands and their
+ilk.
+
address@hidden @key{DEL} (@code{scroll-backward})
address@hidden DEL, in Info windows
address@hidden scroll-backward
+Shift the text in this window down. The inverse of
address@hidden
+If you are at the start of a node, @key{DEL} takes you to the
+``previous'' node, so that you can read an entire manual from finish to
+start by repeating @key{DEL}. The default scroll size can be changed by
+invoking the (@code{scroll-backward-page-only-set-window}) command,
address@hidden under @samp{--vi-keys}, with a numeric argument.
+
address@hidden @key{PREVIOUS} (arrow key) (@code{scroll-backward-page-only})
address@hidden @key{PRIOR} (arrow key)
address@hidden @key{M-v}
address@hidden @key{b}, vi-like operation
address@hidden @key{C-b}, vi-like operation
address@hidden PREVIOUS
address@hidden M-v
address@hidden b, vi-like operation
address@hidden C-b, vi-like operation
address@hidden scroll-backward-page-only
+Shift the text in this window down. The inverse of
address@hidden Does not scroll beyond the start of
+the current node. The default scroll size can be changed by invoking
+the(@code{scroll-backward-page-only-set-window}) command, @samp{w} under
address@hidden, with a numeric argument.
+
address@hidden @key{w} (@code{scroll-backward-page-only-set-window}, vi-like
operation)
address@hidden w, vi-like operation
address@hidden scroll-backward-page-only-set-window
+Scroll backward, like with @key{PREVIOUS}, but if a numeric argument is
+specified, it becomes the default scroll size for subsequent
address@hidden and @code{scroll-backward} commands.
+
address@hidden @key{C-n} (@code{down-line}, vi-like operation)
address@hidden @key{C-e}, vi-like operation
address@hidden @key{RET}, vi-like operation
address@hidden @key{LFD}, vi-like operation
address@hidden @key{DOWN}, vi-like operation
address@hidden C-n, vi-like operation
address@hidden C-e, vi-like operation
address@hidden RET, vi-like operation
address@hidden LFD, vi-like operation
address@hidden DOWN, vi-like operation
address@hidden down-line
+Scroll forward by one line. With a numeric argument, scroll forward
+that many lines.
+
address@hidden @key{C-p} (@code{up-line}, vi-like operation)
address@hidden @key{UP}, vi-like operation
address@hidden @key{y}, vi-like operation
address@hidden @key{k}, vi-like operation
address@hidden @key{C-k}, vi-like operation
address@hidden @key{C-y}, vi-like operation
address@hidden C-p, vi-like operation
address@hidden UP, vi-like operation
address@hidden y, vi-like operation
address@hidden k, vi-like operation
address@hidden C-k, vi-like operation
address@hidden C-y, vi-like operation
address@hidden up-line
+Scroll backward one line. With a numeric argument, scroll backward that
+many lines.
+
address@hidden @key{d} (@code{scroll-half-screen-down}, vi-like operation)
address@hidden @key{C-d}, vi-like operation
address@hidden d, vi-like operation
address@hidden C-d, vi-like operation
address@hidden scroll-half-screen-down
+Scroll forward by half of the screen size. With a numeric argument,
+scroll that many lines. If an argument is specified, it becomes the new
+default number of lines to scroll for subsequent @samp{d} and @samp{u}
+commands.
+
address@hidden @key{u} (@code{scroll-half-screen-up}, vi-like operation)
address@hidden @key{C-u}, vi-like operation
address@hidden u, vi-like operation
address@hidden C-u, vi-like operation
address@hidden scroll-half-screen-up
+Scroll back by half of the screen size. With a numeric argument,
+scroll that many lines. If an argument is specified, it becomes the new
+default number of lines to scroll for subsequent @samp{u} and @samp{d}
+commands.
address@hidden table
+
address@hidden scrolling through node structure
+The @code{scroll-forward} and @code{scroll-backward} commands can also
+move forward and backward through the node structure of the file. If
+you press @key{SPC} while viewing the end of a node, or @key{DEL} while
+viewing the beginning of a node, what happens is controlled by the
+variable @code{scroll-behavior}. @xref{Variables,
address@hidden, for more information.
+
+The @code{scroll-forward-page-only} and @code{scroll-backward-page-only}
+commands never scroll beyond the current node.
+
address@hidden PageUp
+The @key{PREVIOUS} key is the @key{PageUp} key on many keyboards. Emacs
+refers to it by the name @key{PRIOR}. When you use @key{PRIOR} or
address@hidden to scroll, Info never scrolls beyond the beginning of the
+current node.
+
address@hidden BS (backspace)
+If your keyboard lacks the @key{DEL} key, look for a key called
address@hidden, or @samp{BackSpace}, sometimes designated with an arrow which
+points to the left, which should perform the same function.
+
address@hidden @asis
address@hidden @key{C-l} (@code{redraw-display})
address@hidden C-l
address@hidden redraw-display
+Redraw the display from scratch, or shift the line containing the cursor
+to a specified location. With no numeric argument, @samp{C-l} clears
+the screen, and then redraws its entire contents. Given a numeric
+argument of @var{n}, the line containing the cursor is shifted so that
+it is on the @var{n}th line of the window.
+
address@hidden @kbd{C-x @key{w}} (@code{toggle-wrap})
address@hidden C-w
address@hidden toggle-wrap
+Toggles the state of line wrapping in the current window. Normally,
+lines which are longer than the screen width @dfn{wrap}, i.e., they are
+continued on the next line. Lines which wrap have a @samp{\} appearing
+in the rightmost column of the screen. You can cause such lines to be
+terminated at the rightmost column by changing the state of line
+wrapping in the window with @code{C-x w}. When a line which needs more
+space than one screen width to display is displayed, a @samp{$} appears
+in the rightmost column of the screen, and the remainder of the line is
+invisible. When long lines are truncated, the modeline displays the
address@hidden character near its left edge.
address@hidden table
+
+
address@hidden Node Commands
address@hidden Selecting a Node
address@hidden nodes, selection of
+
+This section details the numerous Info commands which select a new node
+to view in the current window.
+
+The most basic node commands are @samp{n}, @samp{p}, @samp{u}, and
address@hidden Note that the commands to select nodes are mapped differently
+when @samp{--vi-keys} is in effect; these keybindings are designated
+below as ``vi-like operation''.
+
+When you are viewing a node, the top line of the node contains some Info
address@hidden which describe where the next, previous, and up nodes
+are. Info uses this line to move about the node structure of the file
+when you use the following commands:
+
address@hidden @asis
address@hidden @key{n} (@code{next-node})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden @kbd{C-x @key{n}}, vi-like operation
address@hidden n
address@hidden C-NEXT
address@hidden C-x n, vi-like operation
address@hidden next-node
+Select the `Next' node.
+
address@hidden C-PgDn
+The @key{NEXT} key is known as the @key{PgDn} key on some
+keyboards.
+
address@hidden @key{p} (@code{prev-node})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden p
address@hidden C-PREVIOUS
address@hidden prev-node
+Select the `Prev' node.
+
address@hidden C-PgUp
+The @key{PREVIOUS} key is known as the @key{PgUp} key on some
+keyboards.
+
address@hidden @key{u} (@code{up-node})
address@hidden @address@hidden (an arrow key on DOS/Windows only)
address@hidden @kbd{C-x @key{u}}, vi-like operation
address@hidden u
address@hidden C-UP
address@hidden C-x u, vi-like operation
address@hidden up-node
+Select the `Up' node.
address@hidden table
+
+You can easily select a node that you have already viewed in this window
+by using the @samp{l} command -- this name stands for "last", and
+actually moves backwards through the history of visited nodes for this
+window. This is handy when you followed a reference to another node,
+possibly to read about a related issue, and would like then to resume
+reading at the same place where you started the excursion.
+
+Each node where you press @samp{l} is discarded from the history. Thus,
+by the time you get to the first node you visited in a window, the
+entire history of that window is discarded.
+
address@hidden @asis
address@hidden @key{l} (@code{history-node})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden @key{'}, vi-like operation
address@hidden l
address@hidden C-CENTER
address@hidden ', vi-like operation
address@hidden history-node
+Pop the most recently selected node in this window from the node
+history.
address@hidden table
+
+Two additional commands make it easy to select the most commonly
+selected nodes; they are @samp{t} and @samp{d}.
+
address@hidden @asis
address@hidden @key{t} (@code{top-node})
address@hidden @key{M-t}, vi-like operation
address@hidden t
address@hidden M-t, vi-like operation
address@hidden top-node
+Select the node @samp{Top} in the current Info file.
+
address@hidden @key{d} (@code{dir-node})
address@hidden @key{M-d}, vi-like operation
address@hidden d
address@hidden M-d, vi-like operation
address@hidden dir-node
+Select the directory node (i.e., the node @samp{(dir)}).
address@hidden table
+
+Here are some other commands which immediately result in the selection
+of a different node in the current window:
+
address@hidden @asis
address@hidden @key{<} (@code{first-node})
address@hidden @key{g}, vi-like operation
address@hidden <
address@hidden g, vi-like operation
address@hidden first-node
+Selects the first node which appears in this file. This node is most
+often @samp{Top}, but it does not have to be. With a numeric argument
address@hidden, select the @var{N}th node (the first node is node 1). An
+argument of zero is the same as the argument of 1.
+
address@hidden @key{>} (@code{last-node})
address@hidden @key{G}, vi-like operation
address@hidden >
address@hidden G, vi-like operation
address@hidden last-node
+Select the last node which appears in this file. With a numeric argument
address@hidden, select the @var{N}th node (the first node is node 1). An
+argument of zero is the same as no argument, i.e., it selects the last
+node.
+
address@hidden @key{]} (@code{global-next-node})
address@hidden ]
address@hidden global-next-node
+Move forward or down through node structure. If the node that you are
+currently viewing has a @samp{Next} pointer, that node is selected.
+Otherwise, if this node has a menu, the first menu item is selected. If
+there is no @samp{Next} and no menu, the same process is tried with the
address@hidden node of this node.
+
address@hidden @key{[} (@code{global-prev-node})
address@hidden [
address@hidden global-prev-node
+Move backward or up through node structure. If the node that you are
+currently viewing has a @samp{Prev} pointer, that node is selected.
+Otherwise, if the node has an @samp{Up} pointer, that node is selected,
+and if it has a menu, the last item in the menu is selected.
address@hidden table
+
+You can get the same behavior as @code{global-next-node} and
address@hidden while simply scrolling through the file with
address@hidden and @key{DEL}; @xref{Variables, @code{scroll-behavior}}, for
+more information.
+
address@hidden @asis
address@hidden
address@hidden @key{g} (@code{goto-node})
address@hidden @kbd{C-x @key{g}}, vi-like operation
address@hidden g
address@hidden C-x g, vi-like operation
address@hidden goto-node
+Read the name of a node and select it. While reading the node name,
+completion (@pxref{The Echo Area, completion}) is only done for the
+nodes which reside in one of the Info files that were loaded in the
+current Info session; if the desired node resides in some other file,
+you must type the node exactly as it appears in that Info file, and you
+must include the Info file of the other file. For example,
+
address@hidden
address@hidden(emacs)Buffers}
address@hidden example
+
+finds the node @samp{Buffers} in the Info file @file{emacs}.
+
address@hidden
address@hidden @key{O} (@code{goto-invocation}
address@hidden @key{I}
address@hidden O
address@hidden I
address@hidden goto-invocation
address@hidden finding the Invocation node
+Read the name of a program and look for a node in the current Info file
+which describes the invocation and the command-line options for that
+program. The default program name is derived from the name of the
+current Info file. This command does the same as the
address@hidden command-line option (@pxref{--show-options}), but
+it also allows to specify the program name; this is important for those
+manuals which describe several programs.
+
+If you need to find the Invocation node of a program that is documented
+in another Info file, you need to visit that file before invoking
address@hidden For example, if you are reading the Emacs manual and want to
+see the command-line options of the @code{makeinfo} program, type @kbd{g
+(texinfo) @key{RET}} and then @kbd{I makeinfo @key{RET}}. If you don't
+know what Info file documents the command, or if invoking @samp{I}
+doesn't display the right node, go to the @samp{(dir)} node (using the
address@hidden command) and invoke @samp{I} from there.
+
address@hidden @key{G} (@code{menu-sequence})
address@hidden G
address@hidden menu-sequence
address@hidden menu, following, from inside Info
+Read a sequence of menu entries and follow it. Info prompts for a
+sequence of menu items separated by commas. (Since commas are not
+allowed in a node name, they are a natural choice for a delimiter in a
+list of menu items.) Info then looks up the first item in the menu of
+the node @samp{(dir)} (if the @samp{(dir)} node cannot be found, Info
+uses @samp{Top}). If such an entry is found, Info goes to the node it
+points to and looks up the second item in the menu of that node, etc.
+In other words, you can specify a complete path which descends through
+the menu hierarchy of a particular Info file starting at the
address@hidden(dir)} node. This has the same effect as if you typed the menu
+item sequence on Info's command line, see @ref{command-line menu items,,
+Info command-line arguments processing}. For example,
+
address@hidden
+ @kbd{G Texinfo,Overview,Reporting Bugs @key{RET}}
address@hidden example
+
address@hidden
+displays the node @samp{Reporting Bugs} in the Texinfo manual. (You
+don't actually need to type the menu items in their full length, or in
+their exact letter-case. However, if you do type the menu items
+exactly, Info will find it faster.)
+
+If any of the menu items you type are not found, Info stops at the last
+entry it did find and reports an error.
+
address@hidden @kbd{C-x @key{k}} (@code{kill-node})
address@hidden C-x k
address@hidden kill-node
+Kill a node. The node name is prompted for in the echo area, with a
+default of the current node. @dfn{Killing} a node means that Info tries
+hard to forget about it, removing it from the list of history nodes kept
+for the window where that node is found. Another node is selected in
+the window which contained the killed node.
+
address@hidden @kbd{C-x C-f} (@code{view-file})
address@hidden C-x C-f
address@hidden view-file
+Read the name of a file and selects the entire file. The command
address@hidden
address@hidden C-f @var{filename}}
address@hidden example
+is equivalent to typing
address@hidden
address@hidden(@var{filename})*}
address@hidden example
+
address@hidden @kbd{C-x C-b} (@code{list-visited-nodes})
address@hidden C-x C-b
address@hidden list-visited-nodes
+Make a window containing a menu of all of the currently visited nodes.
+This window becomes the selected window, and you may use the standard
+Info commands within it.
+
address@hidden @kbd{C-x @key{b}} (@code{select-visited-node})
address@hidden C-x b
address@hidden select-visited-node
+Select a node which has been previously visited in a visible window.
+This is similar to @samp{C-x C-b} followed by @samp{m}, but no window is
+created.
address@hidden table
+
+
address@hidden Searching Commands
address@hidden Searching an Info File
address@hidden searching
+
+GNU Info allows you to search for a sequence of characters throughout an
+entire Info file, search through the indices of an Info file, or find
+areas within an Info file which discuss a particular topic.
+
address@hidden @asis
address@hidden @key{s} (@code{search})
address@hidden @key{/}
address@hidden s
address@hidden /
address@hidden search
+Read a string in the echo area and search for it. If the string
+includes upper-case characters, the Info file is searched
+case-sensitively; otherwise Info ignores the letter case. With a
+numeric argument of @var{N}, search for @var{N}th occurrence of the
+string. Negative arguments search backwards.
+
address@hidden @key{?} (@code{search-backward}, vi-like operation)
address@hidden ?, vi-like operation
address@hidden search-backward
+Read a string in the echo area and search backward through the Info file
+for that string. If the string includes upper-case characters, the Info
+file is searched case-sensitively; otherwise Info ignores the letter
+case. With a numeric argument of @var{N}, search for @var{N}th
+occurrence of the string. Negative arguments search forward.
+
address@hidden @key{S} (@code{search-case-sensitively}
address@hidden S
address@hidden search-case-sensitively
address@hidden search, case-sensitive
address@hidden case-sensitive search
+Read a string in the echo area and search for it case-sensitively, even
+if the string includes only lower-case letters. With a numeric argument
+of @var{N}, search for @var{N}th occurrence of the string. Negative
+arguments search backwards.
+
address@hidden @kbd{C-x @key{n}} (@code{search-next})
address@hidden @key{n}, vi-like operation
address@hidden C-x n
address@hidden n, vi-like operation
address@hidden search-next
address@hidden repeated search
+Search for the same string used in the last search command, in the same
+direction, and with the same case-sensitivity option. With a numeric
+argument of @var{N}, search for @var{N}th next occurrence.
+
address@hidden @kbd{C-x @key{N}} (@code{search-previous})
address@hidden @key{N}, vi-like operation
address@hidden C-x N
address@hidden n, vi-like operation
address@hidden search-previous
+Search for the same string used in the last search command, and with the
+same case-sensitivity option, but in the reverse direction. With a
+numeric argument of @var{N}, search for @var{N}th previous occurrence.
+
address@hidden @key{C-s} (@code{isearch-forward})
address@hidden C-s
address@hidden isearch-forward
address@hidden incremental search
+Interactively search forward through the Info file for a string as you
+type it. If the string includes upper-case characters, the search is
+case-sensitive; otherwise Info ignores the letter case.
+
address@hidden @key{C-r} (@code{isearch-backward})
address@hidden C-r
address@hidden isearch-backward
+Interactively search backward through the Info file for a string as
+you type it. If the string includes upper-case characters, the search
+is case-sensitive; otherwise Info ignores the letter case.
+
address@hidden @key{i} (@code{index-search})
address@hidden i
address@hidden index-search
address@hidden index, searching
address@hidden searching, in the indices
+Look up a string in the indices for this Info file, and select a node
+where the found index entry points to.
+
address@hidden @key{,} (@code{next-index-match})
address@hidden ,
address@hidden next-index-match
+Move to the node containing the next matching index item from the last
address@hidden command.
+
address@hidden @kbd{M-x index-apropos}
address@hidden index-apropos
+Grovel the indices of all the known Info files on your system for a
+string, and build a menu of the possible matches.
address@hidden table
+
+The most basic searching command is @samp{s} or @samp{/}
+(@code{search}). The @samp{s} command prompts you for a string in the
+echo area, and then searches the remainder of the Info file for an
+occurrence of that string. If the string is found, the node containing
+it is selected, and the cursor is left positioned at the start of the
+found string. Subsequent @samp{s} commands show you the default search
+string within @samp{[} and @samp{]}; pressing @key{RET} instead of
+typing a new string will use the default search string. Under
address@hidden (@pxref{--vi-keys}), using the @samp{n} or @samp{N}
+commands is a faster way of searching for the same string.
+
address@hidden searching} is similar to basic searching, but the
+string is looked up while you are typing it, instead of waiting until
+the entire search string has been specified.
+
address@hidden search, and case-sensitivity
address@hidden case-sensitivity, and search
+Both incremental and non-incremental search by default ignore the case
+of letters when comparing the Info file text with the search string.
+However, an uppercase letter in the search string makes the search
+case-sensitive. You can force a case-sensitive non-incremental search,
+even for a string that includes only lower-case letters, by using the
address@hidden command (@code{search-case-sensitively}). The @samp{n} and
address@hidden commands operate case-sensitively if the last search command
+was @samp{S}.
+
+The most efficient means of finding something quickly in a manual is
+the @samp{i} command (@code{index-search}). This command prompts for
+a string, and then looks for that string in all the indices of the
+current Info manual. If it finds a matching index entry, it displays
+the node to which that entry refers and prints the full text of the
+entry in the echo area. You can press @samp{,}
+(@code{next-index-match}) to find more matches. A good Info manual
+has all of its important concepts indexed, so the @samp{i} command
+lets you use a manual as a reference.
+
+If you don't know what manual documents something, try the @kbd{M-x
+index-apropos}. It prompts for a string and then looks up that string
+in all the indices of all the Info documents installed on your system.
+It can also be invoked from the command line; see @ref{--apropos}.
+
+
address@hidden Xref Commands
address@hidden Selecting Cross References
+
+We have already discussed the @samp{Next}, @samp{Prev}, and @samp{Up}
+pointers which appear at the top of a node. In addition to these
+pointers, a node may contain other pointers which refer you to a
+different node, perhaps in another Info file. Such pointers are called
address@hidden references}, or @dfn{xrefs} for short.
+
address@hidden
+* Parts of an Xref:: What a cross reference is made of.
+* Selecting Xrefs:: Commands for selecting menu or note items.
address@hidden menu
+
address@hidden Parts of an Xref, Selecting Xrefs, , Xref Commands
address@hidden Parts of an Xref
+
+Cross references have two major parts: the first part is called the
address@hidden; it is the name that you can use to refer to the cross
+reference, and the second is the @dfn{target}; it is the full name of
+the node that the cross reference points to.
+
+The target is separated from the label by a colon @samp{:}; first the
+label appears, and then the target. For example, in the sample menu
+cross reference below, the single colon separates the label from the
+target.
+
address@hidden
+* Foo Label: Foo Target. More information about Foo.
address@hidden example
+
+Note the @samp{.} which ends the name of the target. The @samp{.} is
+not part of the target; it serves only to let Info know where the target
+name ends.
+
+A shorthand way of specifying references allows two adjacent colons to
+stand for a target name which is the same as the label name:
+
address@hidden
+* Foo Commands:: Commands pertaining to Foo.
address@hidden example
+
+In the above example, the name of the target is the same as the name of
+the label, in this case @code{Foo Commands}.
+
+You will normally see two types of cross reference while viewing nodes:
address@hidden references, and @dfn{note} references. Menu references
+appear within a node's menu; they begin with a @samp{*} at the beginning
+of a line, and continue with a label, a target, and a comment which
+describes what the contents of the node pointed to contains.
+
+Note references appear within the body of the node text; they begin with
address@hidden, and continue with a label and a target.
+
+Like @samp{Next}, @samp{Prev}, and @samp{Up} pointers, cross references
+can point to any valid node. They are used to refer you to a place
+where more detailed information can be found on a particular subject.
+Here is a cross reference which points to a node within the Texinfo
+documentation: @xref{xref, , Writing an Xref, texinfo, the Texinfo
+Manual}, for more information on creating your own texinfo cross
+references.
+
address@hidden Selecting Xrefs, , Parts of an Xref, Xref Commands
address@hidden Selecting Xrefs
+
+The following table lists the Info commands which operate on menu items.
+
address@hidden @asis
address@hidden @key{1} (@code{menu-digit})
address@hidden @key{2} @dots{} @key{9}
address@hidden @key{M-1}, vi-like operation
address@hidden @key{M-2} @dots{} @key{M-9}, vi-like operation
address@hidden 1 @dots{} 9, in Info windows
address@hidden M-1 @dots{} M-9, vi-like operation
address@hidden 1 @dots{} 9, in Info windows
address@hidden M-1 @dots{} M-9, vi-like operation
address@hidden menu-digit
+Within an Info window, pressing a single digit, (such as @samp{1}),
+selects that menu item, and places its node in the current window.
+For convenience, there is one exception; pressing @samp{0} selects the
address@hidden item in the node's menu. When @samp{--vi-keys} is in
+effect, digits set the numeric argument, so these commands are remapped
+to their @samp{M-} varieties. For example, to select the last menu
+item, press @key{M-0}.
+
address@hidden @key{0} (@code{last-menu-item})
address@hidden @key{M-0}, vi-like operation
address@hidden 0, in Info windows
address@hidden M-0, vi-like operation
address@hidden last-menu-item
+Select the last item in the current node's menu.
+
address@hidden @key{m} (@code{menu-item})
address@hidden m
address@hidden menu-item
+Reads the name of a menu item in the echo area and selects its node.
+Completion is available while reading the menu label. @xref{The Echo
+Area, completion}.
+
address@hidden @kbd{M-x find-menu}
address@hidden find-menu
+Move the cursor to the start of this node's menu.
address@hidden table
+
+This table lists the Info commands which operate on cross references.
+
address@hidden @asis
address@hidden @key{f} (@code{xref-item})
address@hidden @key{r}
address@hidden @key{M-f}, vi-like operation
address@hidden @kbd{C-x @key{r}}, vi-like operation
address@hidden f
address@hidden r
address@hidden M-f, vi-like operation
address@hidden C-x r, vi-like operation
address@hidden xref-item
+Reads the name of a note cross reference in the echo area and selects
+its node. Completion is available while reading the cross reference
+label. @xref{The Echo Area, completion}.
address@hidden table
+
+Finally, the next few commands operate on menu or note references alike:
+
address@hidden @asis
address@hidden @key{TAB} (@code{move-to-next-xref})
address@hidden TAB, in Info windows
address@hidden move-to-next-xref
+Move the cursor to the start of the next nearest menu item or note
+reference in this node. You can then use @key{RET}
+(@code{select-reference-this-line}) to select the menu or note reference.
+
address@hidden @key{M-TAB} (@code{move-to-prev-xref})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden M-TAB, in Info windows
address@hidden move-to-prev-xref
+Move the cursor the start of the nearest previous menu item or note
+reference in this node.
+
address@hidden Shift-TAB, in Info windows
address@hidden BackTab, in Info windows
+On DOS/Windows only, the @address@hidden key is an alias for
address@hidden@key{TAB}}. This key is sometimes called @samp{BackTab}.
+
address@hidden @key{RET} (@code{select-reference-this-line})
address@hidden @key{M-g}, vi-like operation
address@hidden RET, in Info windows
address@hidden M-g, vi-like operation
address@hidden select-reference-this-line
+Select the menu item or note reference appearing on this line.
address@hidden table
+
+
address@hidden Window Commands
address@hidden Manipulating Multiple Windows
address@hidden windows, manipulating
+
+A @dfn{window} is a place to show the text of a node. Windows have a
+view area where the text of the node is displayed, and an associated
address@hidden line}, which briefly describes the node being viewed.
+
+GNU Info supports multiple windows appearing in a single screen; each
+window is separated from the next by its modeline. At any time, there
+is only one @dfn{active} window, that is, the window in which the cursor
+appears. There are commands available for creating windows, changing
+the size of windows, selecting which window is active, and for deleting
+windows.
+
address@hidden
+* The Mode Line:: What appears in the mode line?
+* Basic Windows:: Manipulating windows in Info.
+* The Echo Area:: Used for displaying errors and reading input.
address@hidden menu
+
address@hidden The Mode Line, Basic Windows, , Window Commands
address@hidden The Mode Line
+
+A @dfn{mode line} is a line of inverse video which appears at the bottom
+of an Info window. It describes the contents of the window just above
+it; this information includes the name of the file and node appearing in
+that window, the number of screen lines it takes to display the node,
+and the percentage of text that is above the top of the window. It can
+also tell you if the indirect tags table for this Info file needs to be
+updated, and whether or not the Info file was compressed when stored on
+disk.
+
+Here is a sample mode line for a window containing an uncompressed file
+named @file{dir}, showing the node @samp{Top}.
+
address@hidden
address@hidden
+-----Info: (dir)Top, 40 lines --Top-------------------------------------
+ ^^ ^ ^^^ ^^
+ (file)Node #lines where
address@hidden group
address@hidden example
+
+When a node comes from a file which is compressed on disk, this is
+indicated in the mode line with two small @samp{z}'s. In addition, if
+the Info file containing the node has been split into subfiles, the name
+of the subfile containing the node appears in the modeline as well:
+
address@hidden
+--zz-Info: (emacs)Top, 291 lines --Top-- Subfile: emacs-1.Z-------------
address@hidden example
+
+Truncation of long lines (as opposed to wrapping them to the next
+display line, @pxref{Scrolling Commands, toggle-wrap}) is indicated by a
address@hidden at the left edge of the mode line:
+
address@hidden
+--$--Info: (texinfo)Top, 480 lines --Top-- Subfile: texinfo-1-----------
address@hidden example
+
+When Info makes a node internally, such that there is no corresponding
+info file on disk, the name of the node is surrounded by asterisks
+(@samp{*}). The name itself tells you what the contents of the window
+are; the sample mode line below shows an internally constructed node
+showing possible completions:
+
address@hidden
+-----Info: *Completions*, 7 lines --All---------------------------------
address@hidden example
+
address@hidden Basic Windows, The Echo Area, The Mode Line, Window Commands
address@hidden Window Commands
+
+It can be convenient to view more than one node at a time. To allow
+this, Info can display more than one @dfn{window}. Each window has its
+own mode line (@pxref{The Mode Line}) and history of nodes viewed in that
+window (@pxref{Node Commands, , @code{history-node}}).
+
address@hidden @asis
address@hidden @kbd{C-x @key{o}} (@code{next-window})
address@hidden windows, selecting
address@hidden C-x o
address@hidden next-window
+Select the next window on the screen. Note that the echo area can only be
+selected if it is already in use, and you have left it temporarily.
+Normally, @samp{C-x o} simply moves the cursor into the next window on
+the screen, or if you are already within the last window, into the first
+window on the screen. Given a numeric argument, @samp{C-x o} moves over
+that many windows. A negative argument causes @samp{C-x o} to select
+the previous window on the screen.
+
address@hidden @kbd{M-x prev-window}
address@hidden prev-window
+Select the previous window on the screen. This is identical to
address@hidden o} with a negative argument.
+
address@hidden @kbd{C-x @key{2}} (@code{split-window})
address@hidden windows, creating
address@hidden C-x 2
address@hidden split-window
+Split the current window into two windows, both showing the same node.
+Each window is one half the size of the original window, and the cursor
+remains in the original window. The variable @code{automatic-tiling}
+can cause all of the windows on the screen to be resized for you
+automatically, please @pxref{Variables, , automatic-tiling} for more
+information.
+
address@hidden @kbd{C-x @key{0}} (@code{delete-window})
address@hidden windows, deleting
address@hidden C-x 0
address@hidden delete-window
+Delete the current window from the screen. If you have made too many
+windows and your screen appears cluttered, this is the way to get rid of
+some of them.
+
address@hidden @kbd{C-x @key{1}} (@code{keep-one-window})
address@hidden C-x 1
address@hidden keep-one-window
+Delete all of the windows excepting the current one.
+
address@hidden @kbd{ESC @key{C-v}} (@code{scroll-other-window})
address@hidden ESC C-v, in Info windows
address@hidden scroll-other-window
+Scroll the other window, in the same fashion that @samp{C-v} might
+scroll the current window. Given a negative argument, scroll the
+"other" window backward.
+
address@hidden @kbd{C-x @key{^}} (@code{grow-window})
address@hidden C-x ^
address@hidden grow-window
+Grow (or shrink) the current window. Given a numeric argument, grow
+the current window that many lines; with a negative numeric argument,
+shrink the window instead.
+
address@hidden @kbd{C-x @key{t}} (@code{tile-windows})
address@hidden tiling
address@hidden C-x t
address@hidden tile-windows
+Divide the available screen space among all of the visible windows.
+Each window is given an equal portion of the screen in which to display
+its contents. The variable @code{automatic-tiling} can cause
address@hidden to be called when a window is created or deleted.
address@hidden, , @code{automatic-tiling}}.
address@hidden table
+
address@hidden The Echo Area, , Basic Windows, Window Commands
address@hidden The Echo Area
address@hidden echo area
+
+The @dfn{echo area} is a one line window which appears at the bottom of
+the screen. It is used to display informative or error messages, and to
+read lines of input from you when that is necessary. Almost all of the
+commands available in the echo area are identical to their Emacs
+counterparts, so please refer to that documentation for greater depth of
+discussion on the concepts of editing a line of text. The following
+table briefly lists the commands that are available while input is being
+read in the echo area:
+
address@hidden @asis
address@hidden @key{C-f} (@code{echo-area-forward})
address@hidden @key{RIGHT} (an arrow key)
address@hidden @key{M-h}, vi-like operation
address@hidden C-f, in the echo area
address@hidden RIGHT, in the echo area
address@hidden M-h, in the echo area, vi-like operation
address@hidden echo-area-forward
+Move forward a character.
+
address@hidden @key{C-b} (@code{echo-area-backward})
address@hidden @key{LEFT} (an arrow key)
address@hidden @key{M-l}, vi-like operation
address@hidden LEFT, in the echo area
address@hidden C-b, in the echo area
address@hidden M-l, in the echo area, vi-like operation
address@hidden echo-area-backward
+Move backward a character.
+
address@hidden @key{C-a} (@code{echo-area-beg-of-line})
address@hidden @key{M-0}, vi-like operation
address@hidden C-a, in the echo area
address@hidden M-0, in the echo area, vi-like operation
address@hidden echo-area-beg-of-line
+Move to the start of the input line.
+
address@hidden @key{C-e} (@code{echo-area-end-of-line})
address@hidden @key{M-$}, vi-like operation
address@hidden C-e, in the echo area
address@hidden M-$, vi-like operation
address@hidden echo-area-end-of-line
+Move to the end of the input line.
+
address@hidden @key{M-f} (@code{echo-area-forward-word})
address@hidden @address@hidden (DOS/Windows only)
address@hidden @key{M-w}, vi-like operation
address@hidden M-f, in the echo area
address@hidden M-w, in the echo area, vi-like operation
address@hidden echo-area-forward-word
+Move forward a word.
+
address@hidden C-RIGHT, in the echo area
+On DOS/Windows, @address@hidden moves forward by words.
+
address@hidden @key{M-b} (@code{echo-area-backward-word})
address@hidden @address@hidden (DOS/Windows only)
address@hidden M-b, in the echo area
address@hidden echo-area-backward-word
+Move backward a word.
+
address@hidden C-LEFT, in the echo area
+On DOS/Windows, @address@hidden moves backward by words.
+
address@hidden @key{C-d} (@code{echo-area-delete})
address@hidden @key{M-x}, vi-like operation
address@hidden C-d, in the echo area
address@hidden M-x, in the echo area, vi-like operation
address@hidden echo-area-delete
+Delete the character under the cursor.
+
address@hidden @key{DEL} (@code{echo-area-rubout})
address@hidden DEL, in the echo area
address@hidden echo-area-rubout
+Delete the character behind the cursor.
+
+On some keyboards, this key is designated @key{BS}, for
address@hidden Those keyboards will usually bind @key{DEL} in the
+echo area to @code{echo-area-delete}.
+
address@hidden @key{C-g} (@code{echo-area-abort})
address@hidden @key{C-u}, vi-like operation
address@hidden C-g, in the echo area
address@hidden C-u, in the echo area, vi-like operation
address@hidden echo-area-abort
+Cancel or quit the current operation. If completion is being read, this
+command discards the text of the input line which does not match any
+completion. If the input line is empty, it aborts the calling function.
+
address@hidden @key{RET} (@code{echo-area-newline})
address@hidden RET, in the echo area
address@hidden echo-area-newline
+Accept (or forces completion of) the current input line.
+
address@hidden @key{C-q} (@code{echo-area-quoted-insert})
address@hidden @key{C-v}, vi-like operation
address@hidden C-q, in the echo area
address@hidden C-v, in the echo area, vi-like operation
address@hidden echo-area-quoted-insert
+Insert the next character verbatim. This is how you can insert control
+characters into a search string, for example, or the @samp{?} character
+when Info prompts with completion.
+
address@hidden @var{printing character} (@code{echo-area-insert})
address@hidden printing characters, in the echo area
address@hidden echo-area-insert
+Insert the character. Characters that have their 8th bit set, and not
+bound to @samp{M-} commands, are also inserted verbatim; this is useful
+for terminals which support Latin scripts.
+
address@hidden @key{M-TAB} (@code{echo-area-tab-insert})
address@hidden @address@hidden (on DOS/Windows only)
address@hidden M-TAB, in the echo area
address@hidden Shift-TAB, in the echo area
address@hidden echo-area-tab-insert
+Insert a TAB character.
+
address@hidden Shift-TAB, in the echo area
address@hidden BackTab, in the echo area
+On DOS/Windows only, the @address@hidden key is an alias for
address@hidden@key{TAB}}. This key is sometimes called @samp{BackTab}.
+
address@hidden @key{C-t} (@code{echo-area-transpose-chars})
address@hidden C-t, in the echo area
address@hidden echo-area-transpose-chars
+Transpose the characters at the cursor.
address@hidden table
+
+The next group of commands deal with @dfn{killing}, and @dfn{yanking}
address@hidden
+Some people are used to calling these operations @dfn{cut} and
address@hidden, respectively.}. For an in depth discussion of killing and
+yanking, @pxref{Killing, , Killing and Deleting, emacs, the GNU Emacs
+Manual}
+
address@hidden @asis
address@hidden @key{M-d} (@code{echo-area-kill-word})
address@hidden @key{M-X}, vi-like operation
address@hidden M-d, in the echo area
address@hidden M-X, in the echo area, vi-like operation
address@hidden echo-area-kill-word
+Kill the word following the cursor.
+
address@hidden @key{M-DEL} (@code{echo-area-backward-kill-word})
address@hidden @address@hidden
address@hidden M-DEL, in the echo area
address@hidden echo-area-backward-kill-word
+Kill the word preceding the cursor.
+
address@hidden M-BS, in the echo area
+On some keyboards, the @code{Backspace} key is used instead of
address@hidden, so @address@hidden has the same effect as
address@hidden@key{DEL}}.
+
address@hidden @key{C-k} (@code{echo-area-kill-line})
address@hidden C-k, in the echo area
address@hidden echo-area-kill-line
+Kill the text from the cursor to the end of the line.
+
address@hidden @kbd{C-x @key{DEL}} (@code{echo-area-backward-kill-line})
address@hidden C-x DEL, in the echo area
address@hidden echo-area-backward-kill-line
+Kill the text from the cursor to the beginning of the line.
+
address@hidden @key{C-y} (@code{echo-area-yank})
address@hidden C-y, in the echo area
address@hidden echo-area-yank
+Yank back the contents of the last kill.
+
address@hidden @key{M-y} (@code{echo-area-yank-pop})
address@hidden M-y, in the echo area
address@hidden echo-area-yank-pop
+Yank back a previous kill, removing the last yanked text first.
address@hidden table
+
address@hidden completion
+Sometimes when reading input in the echo area, the command that needed
+input will only accept one of a list of several choices. The choices
+represent the @dfn{possible completions}, and you must respond with one
+of them. Since there are a limited number of responses you can make,
+Info allows you to abbreviate what you type, only typing as much of the
+response as is necessary to uniquely identify it. In addition, you can
+request Info to fill in as much of the response as is possible; this
+is called @dfn{completion}.
+
+The following commands are available when completing in the echo area:
+
address@hidden @asis
address@hidden @key{TAB} (@code{echo-area-complete})
address@hidden @key{SPC}
address@hidden TAB, in the echo area
address@hidden SPC, in the echo area
address@hidden echo-area-complete
+Insert as much of a completion as is possible.
+
address@hidden @key{?} (@code{echo-area-possible-completions})
address@hidden ?, in the echo area
address@hidden echo-area-possible-completions
+Display a window containing a list of the possible completions of what
+you have typed so far. For example, if the available choices are:
+
address@hidden
address@hidden
+bar
+foliate
+food
+forget
address@hidden group
address@hidden example
+
address@hidden
+and you have typed an @samp{f}, followed by @samp{?}, Info will pop up a
+window showing a node called @samp{*Completions*} which lists the
+possible completions like this:
+
address@hidden
address@hidden
+3 completions:
+foliate food
+forget
address@hidden group
address@hidden example
+
address@hidden
+i.e., all of the choices which begin with @samp{f}. Pressing @key{SPC}
+or @key{TAB} would result in @samp{fo} appearing in the echo area, since
+all of the choices which begin with @samp{f} continue with @samp{o}.
+Now, typing @samp{l} followed by @samp{TAB} results in @samp{foliate}
+appearing in the echo area, since that is the only choice which begins
+with @samp{fol}.
+
address@hidden @key{ESC C-v} (@code{echo-area-scroll-completions-window})
address@hidden ESC C-v, in the echo area
address@hidden echo-area-scroll-completions-window
+Scroll the completions window, if that is visible, or the "other"
+window if not.
address@hidden table
+
+
address@hidden Printing Nodes
address@hidden Printing Nodes
address@hidden printing
+
+In general, we recommend that you use @TeX{} to format the document and
+print sections of it, by running @code{tex} on the Texinfo source file.
+However, you may wish to print out the contents of a node as a quick
+reference document for later use, or if you don't have @TeX{} installed.
+Info provides you with a command for doing this.
+
address@hidden @asis
address@hidden @kbd{M-x print-node}
address@hidden print-node
address@hidden INFO_PRINT_COMMAND, environment variable
+Pipe the contents of the current node through the command in the
+environment variable @code{INFO_PRINT_COMMAND}. If the variable does not
+exist, the node is simply piped to @code{lpr} (on DOS/Windows, the
+default is to print the node to the local printer device, @file{PRN}).
+
address@hidden printing nodes to the local printer
address@hidden local printer device
+The value of @code{INFO_PRINT_COMMAND} may begin with the @samp{>}
+character, as in @samp{>/dev/printer}, in which case Info treats the
+rest as the name of a file or a device. Instead of piping to a command,
+Info opens the file, writes the node contents, and closes the file,
+under the assumption that text written to that file will be printed by
+the underlying OS.
address@hidden table
+
+
address@hidden Miscellaneous Commands
address@hidden Miscellaneous Commands
+
+GNU Info contains several commands which self-document GNU Info:
+
address@hidden @asis
address@hidden @kbd{M-x describe-command}
address@hidden functions, describing
address@hidden commands, describing
address@hidden describe-command
+Read the name of an Info command in the echo area and then display a
+brief description of what that command does.
+
address@hidden @kbd{M-x describe-key}
address@hidden keys, describing
address@hidden describe-key
+Read a key sequence in the echo area, and then display the name and
+documentation of the Info command that the key sequence invokes.
+
address@hidden @kbd{M-x describe-variable}
+Read the name of a variable in the echo area and then display a brief
+description of what the variable affects.
+
address@hidden @kbd{M-x where-is}
address@hidden where-is
+Read the name of an Info command in the echo area, and then display
+a key sequence which can be typed in order to invoke that command.
+
address@hidden @key{C-h} (@code{get-help-window})
address@hidden @key{?}
address@hidden @key{F1} (on DOS/Windows only)
address@hidden h, vi-like operation
address@hidden C-h
address@hidden ?, in Info windows
address@hidden F1
address@hidden h, vi-like operation
address@hidden get-help-window
+Create (or Move into) the window displaying @code{*Help*}, and place
+a node containing a quick reference card into it. This window displays
+the most concise information about GNU Info available.
+
address@hidden @key{h} (@code{get-info-help-node})
address@hidden @key{M-h}, vi-like operation
address@hidden h
address@hidden M-h, vi-like operation
address@hidden get-info-help-node
+Try hard to visit the node @code{(info)Help}. The Info file
address@hidden distributed with GNU Info contains this node. Of
+course, the file must first be processed with @code{makeinfo}, and then
+placed into the location of your Info directory.
address@hidden table
+
+Here are the commands for creating a numeric argument:
+
address@hidden @asis
address@hidden @key{C-u} (@code{universal-argument})
address@hidden numeric arguments
address@hidden C-u
address@hidden universal-argument
+Start (or multiply by 4) the current numeric argument. @samp{C-u} is
+a good way to give a small numeric argument to cursor movement or
+scrolling commands; @samp{C-u C-v} scrolls the screen 4 lines, while
address@hidden C-u C-n} moves the cursor down 16 lines. @samp{C-u} followed
+by digit keys sets the numeric argument to the number thus typed:
address@hidden 1 2 0} sets the argument to 120.
+
address@hidden @key{M-1} (@code{add-digit-to-numeric-arg})
address@hidden @key{1}, vi-like operation
address@hidden @key{M-2} @dots{} @key{M-9}
address@hidden @key{2} @dots{} @key{9}, vi-like operation
address@hidden @key{M-0}
address@hidden @key{0}, vi-like operation
address@hidden M-0 @dots{} M-9
address@hidden 0 @dots{} 9, vi-like operation
address@hidden add-digit-to-numeric-arg
+Add the digit value of the invoking key to the current numeric
+argument. Once Info is reading a numeric argument, you may just type
+the digits of the argument, without the Meta prefix. For example, you
+might give @samp{C-l} a numeric argument of 32 by typing:
+
address@hidden
address@hidden 3 2 C-l}
address@hidden example
+
address@hidden
+or
+
address@hidden
address@hidden 2 C-l}
address@hidden example
+
address@hidden @key{M--} (@code{add-digit-to-numeric-arg}
address@hidden @key{-}
address@hidden M--
address@hidden -
address@hidden negative arguments
address@hidden arguments, negative
address@hidden numeric arguments, negative
+To make a negative argument, type @kbd{-}. Typing @kbd{-} alone makes a
+negative argument with a value of -1. If you continue to type digit or
+Meta-digit keys after @kbd{-}, the result is a negative number produced
+by those digits.
+
address@hidden doesn't work when you type in the echo area, because you need to
+be able to insert the @samp{-} character itself; use @kbd{M--} instead,
+if you need to specify negative arguments in the echo area.
address@hidden table
+
address@hidden is used to abort the reading of a multi-character key
+sequence, to cancel lengthy operations (such as multi-file searches) and
+to cancel reading input in the echo area.
+
address@hidden @asis
address@hidden @key{C-g} (@code{abort-key})
address@hidden @key{C-u}, vi-like operation
address@hidden cancelling typeahead
address@hidden cancelling the current operation
address@hidden C-g, in Info windows
address@hidden C-u cancels typeahead, vi-like operation
address@hidden abort-key
+Cancel current operation.
address@hidden table
+
+The @samp{q} command of Info simply quits running Info. Under
address@hidden (@pxref{--vi-keys}), you can also exit with @samp{:q}
+or @samp{ZZ}.
+
address@hidden @asis
address@hidden @key{q} (@code{quit})
address@hidden @kbd{C-x C-c}
address@hidden @kbd{:q}, vi-like operation
address@hidden @kbd{ZZ}, vi-like operation
address@hidden quitting
address@hidden q
address@hidden C-x C-c
address@hidden ZZ, vi-like operation
address@hidden quit
+Exit GNU Info.
address@hidden table
+
+If the operating system tells GNU Info that the screen is 60 lines tall,
+and it is actually only 40 lines tall, here is a way to tell Info that
+the operating system is correct.
+
address@hidden @asis
address@hidden @kbd{M-x set-screen-height}
address@hidden set-screen-height
address@hidden screen, changing the height of
+Read a height value in the echo area and set the height of the
+displayed screen to that value.
address@hidden table
+
+On MS-DOS/MS-Windows, this command actually tries to change the
+dimensions of the visible screen to the value you type in the echo
+area.
+
+Finally, Info provides a convenient way to display footnotes which might
+be associated with the current node that you are viewing:
+
address@hidden @asis
address@hidden @key{ESC C-f} (@code{show-footnotes})
address@hidden ESC C-f
address@hidden show-footnotes
address@hidden footnotes, displaying
+Show the footnotes (if any) associated with the current node in another
+window. You can have Info automatically display the footnotes
+associated with a node when the node is selected by setting the variable
address@hidden @xref{Variables, , @code{automatic-footnotes}}.
address@hidden table
+
+
address@hidden Variables
address@hidden Manipulating Variables
+
+GNU Info contains several @dfn{variables} whose values are looked at by
+various Info commands. You can change the values of these variables,
+and thus change the behavior of Info to more closely match your
+environment and Info file reading manner.
+
+There are two ways to set the value of a variable: interactively, using
+the @code{set-variable} command described below, or in the @code{#var}
+section of the @code{.infokey} file. @xref{Custom Key Bindings}.
+
address@hidden @asis
address@hidden @kbd{M-x set-variable}
address@hidden variables, setting
address@hidden set-variable
+Read the name of a variable, and the value for it, in the echo area and
+then set the variable to that value. Completion is available when
+reading the variable name (@pxref{The Echo Area, completion}); often,
+completion is available when reading the value to give to the variable,
+but that depends on the variable itself. If a variable does @emph{not}
+supply multiple choices to complete over, it expects a numeric value.
+
address@hidden @kbd{M-x describe-variable}
address@hidden variables, describing
address@hidden describe-variable
+Read the name of a variable in the echo area and then display a brief
+description of what the variable affects.
address@hidden table
+
+Here is a list of the variables that you can set in Info.
+
address@hidden @code
address@hidden automatic-footnotes
address@hidden automatic-footnotes
+When set to @code{On}, footnotes appear and disappear automatically.
+This variable is @code{On} by default. When a node is selected, a
+window containing the footnotes which appear in that node is created,
+and the footnotes are displayed within the new window. The window that
+Info creates to contain the footnotes is called @samp{*Footnotes*}. If
+a node is selected which contains no footnotes, and a @samp{*Footnotes*}
+window is on the screen, the @samp{*Footnotes*} window is deleted.
+Footnote windows created in this fashion are not automatically tiled so
+that they can use as little of the display as is possible.
+
address@hidden automatic-tiling
address@hidden automatic-tiling
+When set to @code{On}, creating or deleting a window resizes other
+windows. This variable is @code{Off} by default. Normally, typing
address@hidden 2} divides the current window into two equal parts. When
address@hidden is set to @code{On}, all of the windows are
+resized automatically, keeping an equal number of lines visible in each
+window. There are exceptions to the automatic tiling; specifically, the
+windows @samp{*Completions*} and @samp{*Footnotes*} are @emph{not}
+resized through automatic tiling; they remain their original size.
+
address@hidden errors-ring-bell
address@hidden errors-ring-bell
+When set to @code{On}, errors cause the bell to ring. The default
+setting of this variable is @code{On}.
+
address@hidden gc-compressed-files
address@hidden gc-compressed-files
+When set to @code{On}, Info garbage collects files which had to be
+uncompressed. The default value of this variable is @code{Off}.
+Whenever a node is visited in Info, the Info file containing that node
+is read into core, and Info reads information about the tags and nodes
+contained in that file. Once the tags information is read by Info, it
+is never forgotten. However, the actual text of the nodes does not need
+to remain in core unless a particular Info window needs it. For
+non-compressed files, the text of the nodes does not remain in core when
+it is no longer in use. But de-compressing a file can be a time
+consuming operation, and so Info tries hard not to do it twice.
address@hidden tells Info it is okay to garbage collect the
+text of the nodes of a file which was compressed on disk.
+
address@hidden ISO-Latin
address@hidden ISO Latin characters
address@hidden ISO-Latin
+When set to @code{On}, Info accepts and displays ISO Latin characters.
+By default, Info assumes an ASCII character set. @code{ISO-Latin} tells
+Info that it is running in an environment where the European standard
+character set is in use, and allows you to input such characters to
+Info, as well as display them.
+
address@hidden scroll-behavior
address@hidden scroll-behavior
+Control what happens when forward scrolling is requested at the end of
+a node, or when backward scrolling is requested at the beginning of a
+node. The default value for this variable is @code{Continuous}. There
+are three possible values for this variable:
+
address@hidden @code
address@hidden Continuous
+Try to get the first item in this node's menu, or failing that, the
address@hidden node, or failing that, the @samp{Next} of the @samp{Up}.
+This behavior is identical to using the @samp{]}
+(@code{global-next-node}) and @samp{[} (@code{global-prev-node})
+commands.
+
address@hidden Next Only
+Only try to get the @samp{Next} node.
+
address@hidden Page Only
+Simply give up, changing nothing. If @code{scroll-behavior} is
address@hidden Only}, no scrolling command can change the node that is being
+viewed.
address@hidden table
+
address@hidden scroll-step
address@hidden scroll-step
+The number of lines to scroll when the cursor moves out of the window.
+Scrolling happens automatically if the cursor has moved out of the
+visible portion of the node text when it is time to display. Usually
+the scrolling is done so as to put the cursor on the center line of the
+current window. However, if the variable @code{scroll-step} has a
+nonzero value, Info attempts to scroll the node text by that many lines;
+if that is enough to bring the cursor back into the window, that is what
+is done. The default value of this variable is 0, thus placing the
+cursor (and the text it is attached to) in the center of the window.
+Setting this variable to 1 causes a kind of "smooth scrolling" which
+some people prefer.
+
address@hidden show-index-match
address@hidden show-index-match
+When set to @code{On}, the portion of the matched search string is
+highlighted in the message which explains where the matched search
+string was found. The default value of this variable is @code{On}.
+When Info displays the location where an index match was found,
+(@pxref{Searching Commands, , @code{next-index-match}}), the portion of the
+string that you had typed is highlighted by displaying it in the inverse
+case from its surrounding characters.
+
address@hidden visible-bell
address@hidden visible-bell
+When set to @code{On}, GNU Info attempts to flash the screen instead of
+ringing the bell. This variable is @code{Off} by default. Of course,
+Info can only flash the screen if the terminal allows it; in the case
+that the terminal does not allow it, the setting of this variable has no
+effect. However, you can make Info perform quietly by setting the
address@hidden variable to @code{Off}.
+
address@hidden table
+
+
address@hidden Custom Key Bindings
address@hidden Customizing Key Bindings and Variables
+
address@hidden default key bindings, overriding
address@hidden overriding default key bindings
address@hidden customizing key bindings
address@hidden key bindings, customizing
address@hidden infokey
address@hidden .info
address@hidden .infokey
address@hidden _info file (MS-DOS)
+
+For those whose editor/pager of choice is not Emacs and who are not
+entirely satisfied with the --vi-keys option (@pxref{--vi-keys}), GNU
+Info provides a way to define different key-to-command bindings and
+variable settings from the defaults described in this document.
+
+On startup, GNU Info looks for a configuration file in the invoker's
+HOME directory called @address@hidden to the limitations of
+DOS filesystems, the MS-DOS version of Info looks for a file
address@hidden instead. If the @env{HOME} variable is not defined, Info
+additionally looks in the current directory.}. If it is present, and
+appears to contain Info configuration data, and was created with the
+current version of the @code{infokey} command, then Info adopts the
+key bindings and variable settings contained therein.
+
+The @file{.info} file contains compact, non-textual data for reasons of
+efficiency and because its design was lifted wholesale from the GNU Less
+program, which also does it that way. It must be created by compiling a
+textual source file using the @code{infokey} command.
+
address@hidden
+* Invoking infokey::
+* infokey source format::
address@hidden menu
+
+
address@hidden Invoking infokey
address@hidden Invoking @command{infokey}
+
address@hidden invoking infokey
address@hidden infokey, invoking
address@hidden _infokey file (MS-DOS)
+
address@hidden compiles a source file
+(@file{$HOME/address@hidden file is named @file{_infokey} in
+the MS-DOS version, and is looked for in the current directory if
address@hidden is undefined.} by default) containing Info customizations
+into a binary format (@file{$HOME/.info} by default). GNU Info reads
+the binary file at startup to override the default key bindings and
+variable definitions. Synopsis:
+
address@hidden
+infokey address@hidden@dots{}] address@hidden
address@hidden example
+
+Besides the standard @option{--help} and @option{--version}, the only
+option is @option{--output @var{file}}. This tells @command{infokey} to
+write the binary data to @var{file} instead of @file{$HOME/.info}.
+
+
address@hidden infokey source format
address@hidden @command{infokey} source format
+
address@hidden infokey source format
address@hidden .infokey source format
address@hidden format of .infokey source
+
+The format of the source file read by @command{infokey} is most easily
+illustrated by example. For instance, here is a sample @file{.infokey}
+source file suitable for aficionados of @command{vi} or @command{less}:
+
address@hidden
+#info
+j next-line
+k prev-line
+l forward-char
+h backward-char
+\kd next-line
+\ku prev-line
+\kr forward-char
+\kl backward-char
+\ scroll-forward
+\kD scroll-forward-page-only
+b scroll-backward
+\kU scroll-backward-page-only
+g beginning-of-node
+\kh beginning-of-node
+G end-of-node
+\ke end-of-node
+\t select-reference-this-line
+- history-node
+n next-node
+p prev-node
+u up-node
+t top-node
+d dir-node
+#var
+scroll-step=1
address@hidden example
+
+The source file consists of one or more @dfn{sections}.
+Each section starts with a line that identifies the type of section.
+Possible sections are:
+
address@hidden @code
address@hidden #info
+Key bindings for Info windows.
+The start of this section is indicated by a line containing just
address@hidden by itself. If this is the first section in the source
+file, the @code{#info} line can be omitted. The rest of this section
+consists of lines of the form:
+
address@hidden
address@hidden whitespace @var{action} [ whitespace [ # comment ] ] newline
address@hidden example
+
+Whitespace is any sequence of one or more spaces and/or tabs. Comment
+is any sequence of any characters, excluding newline. @var{string} is
+the key sequence which invokes the action. @var{action} is the name of
+an Info command. The characters in @var{string} are interpreted
+literally or prefixed by a caret (@code{^}) to indicate a control
+character. A backslash followed by certain characters specifies input
+keystrokes as follows:
+
address@hidden @code
address@hidden \b
+Backspace
address@hidden \e
+Escape (ESC)
address@hidden \n
+Newline
address@hidden \r
+Return
address@hidden \t
+Tab
address@hidden \ku
+Up arrow
address@hidden \kd
+Down arrow
address@hidden \kl
+Left arrow
address@hidden \kr
+Right arrow
address@hidden \kU
+Page Up
address@hidden \kD
+Page Down
address@hidden \kh
+HOME
address@hidden \ke
+END
address@hidden \kx
+Delete (DEL)
address@hidden address@hidden
address@hidden where @var{x} is any character as described above.
address@hidden table
+
+Backslash followed by any other character indicates that character is to
+be taken literally. Characters which must be preceded by a backslash
+include caret, space, tab, and backslash itself.
+
address@hidden #echo-area
+Key bindings for the echo area.
+The start of this section is indicated by a line containing just
address@hidden by itself. The rest of this section has a syntax
+identical to that for the key definitions for the Info area, described
+above.
+
address@hidden #var
+Variable initializations.
+The start of this section is indicated by a line containing just
address@hidden by itself. Following this line is a list of variable
+assignments, one per line. Each line consists of a variable name
+(@xref{Variables},) followed by @code{=} followed by a value.
+There may be no white space between the variable name and the @code{=},
+and all characters following the @code{=}, including white space,
+are included in the value.
address@hidden table
+
+Blank lines and lines starting with @code{#} are ignored, except for
+the special section header lines.
+
+Key bindings defined in the @file{.info} file take precedence over GNU
+Info's default key bindings, whether or not @samp{--vi-keys} is used. A
+default key binding may be disabled by overriding it in the @file{.info}
+file with the action @code{invalid}. In addition, @emph{all} default
+key bindings can be disabled by adding this line @emph{anywhere} in the
+relevant section:
+
address@hidden
+#stop
address@hidden example
+
+This will cause GNU Info to ignore all the default key commands for that
+section.
+
+Beware: @code{#stop} can be dangerous. Since it disables all default
+key bindings, you must supply enough new key bindings to enable all
+necessary actions. Failure to bind any key to the @code{quit} command,
+for example, can lead to frustration.
+
+The order in which key bindings are defined in the @file{.info} file is
+not important, except that the command summary produced by the
address@hidden command only displays the @emph{first} key that
+is bound to each command.
+
+
address@hidden the following is incomplete
+
+
address@hidden Copying This Manual
address@hidden Copying This Manual
+
address@hidden
+* GNU Free Documentation License:: License for copying this manual.
address@hidden menu
+
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
+
address@hidden FDL, GNU Free Documentation License
address@hidden Version 1.1, March 2000
+
address@hidden
+Copyright @copyright{} 2000 Free Software Foundation, Inc.
+59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
address@hidden display
+
address@hidden 0
address@hidden
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+written document @dfn{free} in the sense of freedom: to assure everyone
+the effective freedom to copy and redistribute it, with or without
+modifying it, either commercially or noncommercially. Secondarily,
+this License preserves for the author and publisher a way to get
+credit for their work, while not being considered responsible for
+modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
address@hidden
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work that contains a
+notice placed by the copyright holder saying it can be distributed
+under the terms of this License. The ``Document'', below, refers to any
+such manual or work. Any member of the public is a licensee, and is
+addressed as ``you''.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (For example, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, whose contents can be viewed and edited directly and
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is
+not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
address@hidden without markup, Texinfo input format, address@hidden input
format,
address@hidden or @acronym{XML} using a publicly available
address@hidden, and standard-conforming simple @acronym{HTML} designed
+for human modification. Opaque formats include PostScript,
address@hidden, proprietary formats that can be read and edited only by
+proprietary word processors, @acronym{SGML} or @acronym{XML} for which
+the @acronym{DTD} and/or processing tools are not generally available,
+and the machine-generated @acronym{HTML} produced by some word
+processors for output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
address@hidden
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
address@hidden
+COPYING IN QUANTITY
+
+If you publish printed copies of the Document numbering more than 100,
+and the Document's license notice requires Cover Texts, you must enclose
+the copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols. If you use the latter
+option, you must take reasonably prudent steps, when you begin
+distribution of Opaque copies in quantity, to ensure that this
+Transparent copy will remain thus accessible at the stated location
+until at least one year after the last time you distribute an Opaque
+copy (directly or through your agents or retailers) of that edition to
+the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
address@hidden
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
address@hidden A
address@hidden
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
address@hidden
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has less than five).
+
address@hidden
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
address@hidden
+Preserve all the copyright notices of the Document.
+
address@hidden
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
address@hidden
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
address@hidden
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
address@hidden
+Include an unaltered copy of this License.
+
address@hidden
+Preserve the section entitled ``History'', and its title, and add to
+it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
address@hidden
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
address@hidden
+In any section entitled ``Acknowledgments'' or ``Dedications'',
+preserve the section's title, and preserve in the section all the
+substance and tone of each of the contributor acknowledgments
+and/or dedications given therein.
+
address@hidden
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
address@hidden
+Delete any section entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
address@hidden
+Do not retitle any existing section as ``Endorsements''
+or to conflict in title with any Invariant Section.
address@hidden enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
address@hidden
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections entitled ``History''
+in the various original documents, forming one section entitled
+``History''; likewise combine any sections entitled ``Acknowledgments'',
+and any sections entitled ``Dedications''. You must delete all sections
+entitled ``Endorsements.''
+
address@hidden
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
address@hidden
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, does not as a whole count as a Modified Version
+of the Document, provided no compilation copyright is claimed for the
+compilation. Such a compilation is called an ``aggregate'', and this
+License does not apply to the other self-contained works thus compiled
+with the Document, on account of their being thus compiled, if they
+are not themselves derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one quarter
+of the entire aggregate, the Document's Cover Texts may be placed on
+covers that surround only the Document within the aggregate.
+Otherwise they must appear on covers around the whole aggregate.
+
address@hidden
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License provided that you also include the
+original English version of this License. In case of a disagreement
+between the translation and the original English version of this
+License, the original English version will prevail.
+
address@hidden
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
address@hidden
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
address@hidden://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
address@hidden enumerate
+
address@hidden
address@hidden ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
address@hidden
address@hidden
+ Copyright (C) @var{year} @var{your name}.
+ 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 the Invariant Sections being @var{list their titles}, with the
+ Front-Cover Texts being @var{list}, and with the Back-Cover Texts being
@var{list}.
+ A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
address@hidden group
address@hidden smallexample
+
+If you have no Invariant Sections, write ``with no Invariant Sections''
+instead of saying which ones are invariant. If you have no
+Front-Cover Texts, write ``no Front-Cover Texts'' instead of
+``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
address@hidden Local Variables:
address@hidden ispell-local-pdict: "ispell-dict"
address@hidden End:
+
+
+
address@hidden Index
address@hidden Index
+
address@hidden cp
+
address@hidden
Index: res_info/texi_mini_ker/mini_ker.texi.first
===================================================================
RCS file: res_info/texi_mini_ker/mini_ker.texi.first
diff -N res_info/texi_mini_ker/mini_ker.texi.first
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ res_info/texi_mini_ker/mini_ker.texi.first 2 Aug 2009 13:11:05 -0000
1.1
@@ -0,0 +1,4311 @@
+\input texinfo @c -*-texinfo-*-
address@hidden mini_ker.info
address@hidden UPDATED 28 March 2002
address@hidden UPDATED-MONTH March 2002
address@hidden EDITION 4.2
address@hidden VERSION 4.2
+
address@hidden @set myversion @value{VERSION}
address@hidden myversion 102
+
address@hidden myurl
@url{http://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}
+
address@hidden Minik{}
+Miniker
address@hidden macro
+
address@hidden Miniker 102 manual
+
address@hidden fn vr
+
address@hidden Miscellaneous
address@hidden
+* Miniker: (mini_ker). The mini_ker modeling tool.
address@hidden direntry
+
+
+
+
address@hidden Top
address@hidden Miniker 102 manual
+
+
address@hidden @insertcopying
+
address@hidden Miniker 102 manual
+
address@hidden: The TEF Collaboration}
+
address@hidden Copyright (C) 2004, 2005, 2006, 2007 Alain address@hidden
+Copyright (C) 2004, 2005, 2006, 2007 Patrice address@hidden
+Copyright (C) 2004, St@'ephane Hallegatte
+
address@hidden
+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 no Front-Cover text and with no Back-Cover Text.
+A copy of the license is included in the section entitled ``GNU Free
+Documentation License.''
address@hidden quotation
+
+
address@hidden
+* Introduction::
+* TEF overview::
+* A model with Miniker::
+* Advanced programming::
+* Dynamic system analysis::
+* Advanced use of Miniker with make::
+
+Indices
+
+* Concepts index::
+* Variables macros and functions index::
+
+Appendices
+
+* Installation::
+* Cmz directives reference::
+* Copying This Manual:: The GNU Free Documentation License.
address@hidden menu
+
address@hidden
+
address@hidden Introduction
address@hidden Introduction
+
address@hidden TEF
address@hidden cells
address@hidden transfers
address@hidden ZOOM
address@hidden mortran
+
+ Miniker is a modeling tool, built especially in order to implement
+models written following the @acronym{TEF,Transfer Evolution Formalism}
+formalism, a mathematical framework for system analysis and
+simulation. Miniker allows for timewise simulation, system analysis,
+adjoint computation, Kalman filtering and more.
+
+Miniker uses a fortran preprocessor, @command{mortran}, designed in the
+1970's, to ease model writing using dedicated specific languages.
+For example partial derivatives are
+symbolicaly determined by @command{mortran} macros in Miniker.
+For the selection of
+another compile-time features, another set of preprocessor directives,
+the @dfn{cmz directives}, are used. In most cases the user does not need to
+know anything about that preprocessing that occurs behind the scene,
+he simply writes down the equations of his model and he is done.
+
address@hidden All partial derivatives needed to solve the TEF system are
automatically
address@hidden determined during the pre-compilation stage.
address@hidden Once all models written down and initial conditions
address@hidden given using a pseudo-Fortran type of language, the model is
ready to run.
+
address@hidden The language developed to get automatic symbolic partial
derivatives
address@hidden uses the Fortran pre-compiler @command{mortran}, designed in the
1970's.
+
+A comprehensive description
+of the @acronym{TEF} formalism in available on
address@hidden://www.lmd.jussieu.fr/ZOOM/doc/tef-GB-partA5.pdf}).
+The Miniker software is a reduced version of
address@hidden://www.lmd.jussieu.fr@//zoom,@strong{ZOOM}},
+that can only handle a hundreds of variables, but is much easier to use.
+
address@hidden
+* Intended audience::
+* Reading guide::
+* Other Manuals and documentation::
address@hidden menu
+
address@hidden Intended audience
address@hidden Intended audience
+
+The reader should have notions in system dynamics.
address@hidden and understand the basis of the TEF.
+Moreover a minimal knowledge of programmation and fortran is
+required. What is required is a basic understanding of variable types,
+affectation and fortran expressions.
+
address@hidden Reading guide
address@hidden Reading guide
+
+The first chapter is a brief overview of the @acronym{TEF}.
+The following describes how to write, compile and run a model in Miniker
+in its basic and comprehensive syntax.
address@hidden Reading the sections of this chapter up to the section
address@hidden @emph{Symbolic model description} is required to know the
address@hidden syntax of model description in @Minik{}.
+Reading up to the section
address@hidden the run} is required to be able to use Miniker.
+In this section it is assumed that Miniker is properly setup. The
+installation instructions are in the appendix at
address@hidden
+
address@hidden 2 programming environment to compile the model are available,
with cmz
address@hidden and make, you can skip the method description you are not
interested in.
address@hidden A reference for the usefull cmz directives is also in the
appendix
address@hidden (@pxref{Cmz directives reference}).
+
address@hidden You should also
address@hidden read the following section, @emph{Symbolic model description}
which presents an
address@hidden alternate syntax for model description, such that you can choose
what you
address@hidden prefer.
+
+The next chapter describes advanced features, first a general introduction to
+features settings and then a description of other model description related
+features.
+
+The next chapter describes system analysis tools available with Miniker. The
+sections are independant and each describes how to use a specific feature. If
+you plan on using these features, you should also read
address@hidden features, , Overview of feature setting}.
+
+A final chapter describes advanced features in a development environment
+using make,
+
+In the appendix the instructions for the installation are described
+(@pxref{Installation}).
+
address@hidden Other Manuals and documentation
address@hidden Other Manuals and documentation
+
+A programmers'Manual is available (in French), and can be asked for to
+any member of the collabration. See additional documents in
+ @url{http://www.lmd.jussieu.fr/Zoom/doc} or ask for Research
+texts and articles to members.
+
address@hidden TEF overview
address@hidden An overview of the @acronym{TEF} formalism
+
+The @acronym{TEF, Transfer Evolution Formalism} is based on partitionning
+and recoupling of model subsystems. It allows the study of the coupling
+between subsystems by the means of linearization and time discretization.
+
address@hidden
+* Cell and Transfer::
+* Linearization and discretization::
address@hidden menu
+
address@hidden Cell and Transfer
address@hidden Cell and Transfer equations
+
+In the @acronym{TEF}, a model is
+mathematically represented by a set of equations corresponding
+to two kinds objects:
+
address@hidden
address@hidden Cells which are elementary models and correspond to evolution
equations
+such as:
address@hidden
+$$\partial_t \eta (t) = g(\eta(t),\varphi(t))$$
address@hidden tex
+
address@hidden @math{d eta(t)/d t = g(eta(t),phi(t))}
+
+
+Vector @math{\eta} represent the state variables of cells and
+the vector @math{\varphi} represent the dependent
+boundary conditions, @i{i.e.} the
+variables considered as boundary conditions by a cell, but depending upon
+the complete model state. This dependent boundary conditions are
+required to make the cells correspond to well-posed problems.
address@hidden FIXME acceptable?
+These variables are often called state variables, and prognostic
+variables in meteorology.
+
+
address@hidden Transfers which are determined by constraint equations such as:
address@hidden
+$$
+\varphi(t) = f(\eta(t),\varphi(t))
+$$
address@hidden tex
+
address@hidden @math{phi(t) = f(eta(t),phi(t))}
+
+These equations are often called algebraic equations, and in meteorology
+diagnostic equations.
address@hidden enumerate
+
address@hidden Linearization and discretization
address@hidden Linearization and discretization in the @acronym{TEF}
+
+The relations between sub-systems is excessively difficult to exhibit when
+having to cope with non-linear system. In the @acronym{TEF}, the
address@hidden, Tangent Linear System} is constructed along the trajectory.
+One considers the system over a small portion along the trajectory, say
+between @math{t} and @math{t + \delta t}. The variation @math{\delta \eta}
+of @math{\eta} and @math{\delta \varphi} of @math{\varphi} is obtained
+through a Pad@'e approximation of the state-transition matrix. The final
+form of the algebraic system is closed to the classical Crank-Nicolson scheme:
+
address@hidden FIXME PAd'e? od Taylor?
address@hidden through a Taylor expansion followed by time integration.
address@hidden A time scheme is then applied to the @acronym{TLS} (a
Crank-Nicholson scheme),
address@hidden to obtain an algebraic system describing the relationships
between
address@hidden variations of transfers and cells variables:
+
+
+
address@hidden
+$$\pmatrix{A & B\cr
+-C^+ & I-D\cr} \pmatrix{\delta \eta\cr
+\delta \varphi\cr} = \pmatrix{\Gamma\cr
+\Omega\cr}$$
address@hidden tex
+
+The blocks appearing in the Jacobian matrix are constructed with partial
derivative
+of @math{f} and @math{g}, and with @math{\delta t}. From this system the
+elimination of @math{\delta \eta} leads to another formulation giving
+the coupling between transfers, and allows for the @math{\delta \varphi}
+computation. The @math{\delta \varphi} value is then substitued in
address@hidden \eta} to complete the time-step solving process.
+
address@hidden A model with Miniker
address@hidden Miniker model programming
+
address@hidden sequences
+
+Miniker works by combining the model specification code given by
+the user and other source files provided in the package. The code is
+assembled, preprocessed, compiled, linked and the resulting program
+can be run to produce the model trajectory and dynamic analysis.
+
+The code provided in the package contains a principal program, some usefull
+subroutines and pieces of code called @dfn{sequences} combined with the
+different codes. Among these sequences some hold the code describing the model
+and are to be written by the user (sequences are similar to
+Fortran include files).
+
address@hidden
+* Structure of the code::
+* A model description::
+* Setting and running a model::
+* Controlling the run::
address@hidden menu
+
address@hidden Structure of the code
address@hidden General structure of the code
+
address@hidden sequence
address@hidden zinit, general
+
+The sequences used to enter model description hold the @c vector dimensions,
+mathematical formulae for each cell and transfer component, dedicated
+derived computations, and time-step
+steering. During the code generation stage,
+cmz directives are preprocessed, then the user pseudo-Fortran
+instructions are translated by @command{mortran} using macros designed to
+generate in particular all Fortran instructions that compute the Jacobian
+matrices used in @acronym{TEF} modelling.
+
address@hidden A first users' sequence to program is: @file{dimetaphi} where
the model
address@hidden dimensions are given, for the two vector-array @code{eta(.)} for
cells
address@hidden and @code{ff(.)} for transfers (@pxref{Model size,,Entering
model size}).
+
+The sequence @file{zinit} contains the mathematical formulation of the model
+(@pxref{Model equation and parameters, Entering model equation and
parameters}).
+Another sequence, @file{zsteer}, is merged at
+the end of the time step advance of the simulation, where the user can
+monitor the time step values and printing levels, and perform particular
+computations etc.
+(@pxref{End of time step, ,Executing code at the end of each time step}).
+
address@hidden A model description
address@hidden Miniker programming illustrated
+
address@hidden TEF
+
+The general @acronym{TEF} system writes:
address@hidden
+$$\eqalign{\partial_t \eta (t) &= g(\eta(t),\varphi(t))\cr
+\varphi(t) &= f(\eta(t),\varphi(t))\cr
+}$$
address@hidden tex
+
address@hidden @math{d eta(t)/d t = g(eta(t),phi(t))@*
+phi(t) = f(eta(t),phi(t))}
+
+
+To illustrate the model description in Miniker a simple predator-prey
+model of Lotka-Volterra is used.
+This model can be written in the following @acronym{TEF} form:
+
address@hidden
+$$\left\{\eqalign{\partial_t \eta _{prey} &= a \eta _{prey} - a \varphi
_{meet} \cr
+\partial_t \eta _{pred} &= -c \eta _{pred} + c \varphi _{meet}\cr}\right.$$
address@hidden tex
address@hidden
+$$\varphi _{meet} = \eta _{prey}\eta _{pred}$$
address@hidden tex
address@hidden @math{d eta_prey(t)/d t = a * eta_prey - a * address@hidden
+d eta_pred(t)/d t = -c * eta_pred +c * phi_meet}
+
address@hidden @math{phi_meet = eta_prey * eta_pred}
+
+with two cell equations, @i{i.e}. state evolution of the prey and predator
+groups, and one transfer accounting for the meeting of individuals of
+different group.
+
address@hidden
+* A note about mortran and cmz directives::
+* Model equation and parameters::
address@hidden menu
+
address@hidden A note about mortran and cmz directives
address@hidden All you need to know about mortran and cmz directives
+
address@hidden mortran
+
+The first stage of code generation consists in cmz directives preprocessing.
+Cmz directives are used for conditional selection of features, and sequence
+inclusion. At that point you don't need to know anything about these
+directives. They are only usefull if you want to take advantage of advanced
+features
+(@pxref{Programming with cmz directives}).
+
+The code in sequences is written in Mortran and the second stage of code
+generation consists in mortran macro expansion. The mortran language is
+described
+in its own manual, here we only explain the very basics which is all you need
+to know to use Miniker. Mortran basic instructions are almost Fortran,
+the differences are the following:
+
address@hidden @bullet
address@hidden The code is free-form, and each statement should end with a
semi-colon
address@hidden;}.
address@hidden Comments may be introduced by an exclamation mark @code{!} at
the
+beginning of a line, or appear within double quotes @code{"} in a single line.
address@hidden It is possible to use blocs, for @code{do} or @code{if}
statement
+for example, and they are enclosed within brackets @samp{<} and @samp{>}.
+To be in the safe side, a semi-colon @code{;} should be added after a
+closng bracket @code{>}.
address@hidden itemize
+
+The following fictious code is legal mortran:
+
address@hidden
+real
+ param;
+param = 3.; ff(1) = ff(3)**eta(1); "a comment"
+! a line comment
+do inode=1,n_node <eta_move(inode)=0.01; eta_speed(inode)=0.0;>;
address@hidden example
+
+Thanks to mortran the model code is very simply specified, as you'll
+see next.
+
+
address@hidden Model equation and parameters
address@hidden Entering model equation and parameters
+
address@hidden @file{zinit}
address@hidden dt
address@hidden time
address@hidden nstep
address@hidden modzprint
+
+The model equation and parameters and some Miniker parameters are entered in
+the @file{zinit} sequence. The whole layout of the model is given
+before detailing the keywords.
+
address@hidden
+!%%%%%%%%%%%%%%%%%%%%%%
+! Parameters
+!%%%%%%%%%%%%%%%%%%%%%%
+ real apar,bpar; "optional Fortran type declaration"
+
+! required parameters
+ dt=.01; "initial time-step"
+ nstep=10 000; "number of iterations along the trajectory"
+ time=0.; "time initialisation "
+
+! model parameters
+ apar = 1.5;
+ cpar = 0.7;
+
+! misceallaneous parameters
+ modzprint = 1000; "printouts frequency"
+
+print*,'***************************************';
+print*,'Lotka-Volterra model with parameters as:';
+z_pr: apar,bpar;
+print*,'***************************************';
+
+!%%%%%%%%%%%%%%%%%%%%%%
+! Transfer definition
+!%%%%%%%%%%%%%%%%%%%%%%
+! rencontre (meeting)
+set_Phi
+< var: ff_interact, fun: f_interact = eta_prey*eta_pred;
+>;
+
+!%%%%%%%%%%%%%%%%%%%%%%
+! Cell definition
+!%%%%%%%%%%%%%%%%%%%%%%
+
+set_eta
+< var: eta_prey, fun: deta_prey = apar*eta_prey - apar*ff_interact;
+ var: eta_pred, fun: deta_pred = - cpar*eta_pred + cpar*ff_interact;
+>;
+
+
+!%%%%%%%%%%%%%%%%%%%%%%
+! Initial states
+!%%%%%%%%%%%%%%%%%%%%%%
+ eta_prey = 1.;
+ eta_pred = 1.;
+;
+ OPEN(50,FILE='title.tex',STATUS='UNKNOWN'); "title file"
+ write(50,5000) apar,cpar;
+5000;format('Lotka-Volterra par:',2F4.1);
address@hidden example
+
address@hidden Variables and model parameters
+
+The following variables are mandatory:
+
address@hidden @code
address@hidden dt
+The time step.
address@hidden time
+Model time initialisation.
address@hidden nstep
+Number of iterations along the trajectory.
address@hidden table
+
+There are no other mandatory variables. Some optional variables are used
+to monitor the printout and ouput of results of the code.
+As an example, the variable @code{modzprint} is used to set
+the frequency of the printout of the model matrix and vectors during the
+run (@pxref{Controlling the printout and data output}).
+
+User's defined variable and Fortran or Mortran instructions can always be
+added for intermediate calculus. To avoid conflict with the variables of the
+Miniker code, the rule is that a users symbol must not have characters
address@hidden
+in the first two symbol characters.
+
+In the predator-prey example there are two model parameters. The fortran
+variables are called here @code{apar} for @math{a} and @code{cpar} for
@math{c}.
+If a Fortan type definition is needed, it should be set at the very beginning
+of @file{zinit}. The predator-prey code variable initializations finally reads
+
address@hidden
address@hidden
+!%%%%%%%%%%%%%%%%%%%%%%
+! Parameters
+!%%%%%%%%%%%%%%%%%%%%%%
+ real apar,bpar; "optional Fortran type declaration"
+
+ dt=.01;
+ nstep=10 000;
+ time=0.;
+
+! model parameters
+ apar = 1.5;
+ cpar = 0.7;
+
+ modzprint = 1000;
address@hidden group
address@hidden example
+
address@hidden Model equations
address@hidden equations}
+
address@hidden set_Phi
address@hidden set_eta
address@hidden var:
address@hidden fun:
address@hidden eqn:
+
+The model equations for cells and model equations for transferts are
+entered in two mortran blocks, one for the transferts, the other for the
+cell components. The model equations for cells are entered into a
address@hidden block, and the transfer equations are entered into a
address@hidden block.
+
+In each block the couples variable-function are specified. For
+transfers the function defines the transfer itself while for cells
+the function describes the cell evolution. The variable is specified
+with @code{var:}, the function is defined with @code{fun:}.
+
+In the case of the predator-prey model, the transfer variable
+associated with @math{\varphi_{meet}} could be called @code{ff_interact}
+and the transfer definition would be given by:
address@hidden
+set_Phi
+< var: ff_interact, fun: f_interact = eta_prey*eta_pred;
+>;
address@hidden example
+
+The two cell equations of the predator-prey model, with name
address@hidden for the prey (@math{\eta_{prey}}) and @code{eta_pred}
+for the predator (@math{\eta_{pred}}) are:
+
address@hidden
+set_eta
+< var: eta_prey, fun: deta_prey = apar*eta_prey - apar*ff_interact;
+ var: eta_pred, fun: deta_pred = - cpar*eta_pred + cpar*ff_interact;
+>;
address@hidden example
+
+The @samp{;} at the end of the mortran block is important.
+
address@hidden
+The whole model equations are setup with:
+
address@hidden
address@hidden
+!%%%%%%%%%%%%%%%%%%%%%%
+! Transfer definition
+!%%%%%%%%%%%%%%%%%%%%%%
+! rencontre (meeting)
+set_Phi
+< var: ff_interact, fun: f_interact = eta_prey*eta_pred;
+>;
+
+!%%%%%%%%%%%%%%%%%%%%%%
+! Cell definition
+!%%%%%%%%%%%%%%%%%%%%%%
+
+set_eta
+< var: eta_prey, fun: deta_prey = apar*eta_prey - apar*ff_interact;
+ var: eta_pred, fun: deta_pred = - cpar*eta_pred + cpar*ff_interact;
+>;
address@hidden group
address@hidden example
+
+Whenever the user is not concerned with giving a specific name to a
+function, it is possible to specify the equation only with
address@hidden:}. Therefore the user may replace an instruction as:
address@hidden
+ var: ff_dump,
+ fun: f_dump = - rd*(eta_speed - eta_speed_limiting);
address@hidden example
+with:
address@hidden
+ eqn: ff_dump = - rd*(eta_speed - eta_speed_limiting);
address@hidden example
+
+In that case, the unnamed function will take the name of the defined
+variable preceded by the @samp{$} sign: @code{$ff_dump}.
+
address@hidden Starting points
+
address@hidden starting point
+
+The cells equations require state initial conditions. In some case, the
+transfers may also need starting points although they are determined from
+the cell values.
+
+In the predator-prey model the starting points for cells are:
address@hidden
+! initial state
+! -------------
+ eta_prey = 1.;
+ eta_pred = 1.;
address@hidden example
+
+When there is a non trivial implicit relationship between the transfers
+in the model, it may be usefull or even necessary to set some
+transfers to non-zero values. This difficulty is only relevant for the very
+first step of the simulation and will be used as a
+first guess of @math{\varphi}. The uninitialized transfers having
+a default compiler-dependant (often zero) value, an initialization
+to another value may help avoiding singular functions or matrix and
+ensure convergence in the Newton algorithm used to solve the transfer implicit
+equation.
+
+
address@hidden The cell and transfer arrays
+
address@hidden eta(.)
address@hidden ff(.)
address@hidden mp
address@hidden np
+
+Sometime it is easier to iterate over an array than to use the
+cell or transfer variable name. This is possible because there is a
+correspondence between the variable names
+and the fortran array @code{eta(.)} for the cell variables and
+the fortran array @code{ff(.)} for the transfer address@hidden fact
+the variables names are transformed into fortran array elements
+by mortran generated macros, so the symbolic names defined in the
+mortran blocks never appears in the generated fortran code, they are
+replaced by the fortran arrays.}.
+
+The index of the variable is determined by the order of appearance in
+the variable definition blocks. It is reminded in the output, as
+explained later (@pxref{Simulation and output}).
+
+The number of cells is in the integer @code{np} variable, and the
+number of transfer is in the integer @code{mp} variable.
+
address@hidden title file
+
address@hidden file}
address@hidden title file
address@hidden @file{title.tex}
+
+For some graphics generation, a file with name @file{title.tex} is required
+which sets the title. The following instructions take care of that:
+
address@hidden
+ OPEN(50,FILE='title.tex',STATUS='UNKNOWN');
+ write(50,5000) apar,cpar;
+5000;format('Lotka-Volterra par:',2F4.1);
+
+ close(50);
address@hidden example
+
+In that case the parameter values are written down, to differenciate between
+different runs. This step is in general not needed.
+
address@hidden The correspondence with basic components are printed out at
execution
address@hidden time as explained in @ref{Simulation and output,,
address@hidden Running a simulation and using the output}. Also, a
@file{Model.hlp} is
address@hidden generated that recalls the basic names and equations of the
model.
address@hidden It may be noted that whenever
address@hidden the order of variable-functions is the same between indexed
declaration and
address@hidden symbolic, the two generated Fortran code are almost identical.
+
address@hidden Setting and running a model
address@hidden Setting and running a model
+
+In this section it is assumed that a programming environment has been
+properly setup. This environment may use either cmz or make to drive
+the preprocessing and compilation.
+You can skip the part related with the environment you don't intend to use.
+
+For instructions regarding the
+installation, see @ref{Installation}.
+
+
address@hidden
+* Setting up a model with cmz::
+* Setting up a model with make::
+* Simulation and output::
+* Graphics::
address@hidden menu
+
address@hidden Setting up a model with cmz
address@hidden Setup a model and compile with cmz
+
address@hidden @command{mod}
address@hidden @file{$zinit}
address@hidden @file{$dimetaphi}
+
+The user defined sequences are @samp{KEEP} in the
+cmz world. The most common organization is to have a cmz file in a
+subdirectory of the directory containing the @file{mini_ker.cmz}
+cmz file. In this
+cmz file there should be a @samp{PATCH} called @samp{zinproc}
+with the KEEPs within the patch. The KEEP must be called @file{$zinit}.
address@hidden and @file{$dimetaphi}.
+
+From within cmz in the directory of your model the source extraction,
+compilation and linking will be triggered by a @command{mod} command. This
macro
+uses the @file{selseq.kumac} information to find the @file{mini_ker.cmz}
+cmz file.
address@hidden
+shall create a directory with the same name than the cmz file,
address@hidden/} in our example. In this directory there is another
+directory @file{cfs/} containing the sources extracted from the cmz file.
+
+The file @file{mymodel_o.tmp} contains all the mortran code generated
+by cmz with the sequences substituted, including the @file{$zinit}. @c and
address@hidden @file{$dimetaphi} sequences (assembled code).
+The fortran produced by the preprocessing and
+splitting of this file is in files with the traditional @samp{.f} suffix.
+The principal program is in @file{principal.f}. An efficient way of getting
+familiar with mini_ker methods is looking at the @file{mymodel_o.tmp} where
+all sequences and main Mortran instructions are gathered. Symbolic derivation
address@hidden FIXME pas ici la symbolic derivation
+is noted as @code{F_D(expression)(/variable)}, and the resulting Fortran code
+is in @file{principal.f}.
+
address@hidden also triggers compilation and linking. The object files are in
+the same @file{cfs/} directory and the executable is in the @file{mymodel/}
+directory, with name @file{mymodel.exe}.
+
address@hidden Setting up a model with make
address@hidden Setup a model and compile with make
+
address@hidden compilation
address@hidden @cindex @file{dimetaphi.mti}
address@hidden @file{zinit.mti}
address@hidden model_file_name
+
+With make, the sequences are files ending with @samp{.mti} (for
+mortran include files),
+called, for example, @file{zinit.mti}.
address@hidden and @file{dimetaphi.mti}.
+They are included by
address@hidden in other source files. You also need a @file{Makefile}
+to drive the compilation of the model.
+
+If you don't need additional code or libraries to be linked with your
+model you have two alternatives.
+
address@hidden
address@hidden
+The simplest alternative is to run
+the @command{start_miniker} script with the model file name as argument.
+It should copy a @file{zinit.mti} file
+ready to be edited and a Makefile ready to compile the model. For
+the predator prey model, for example, you could run
+
address@hidden
+$ start_miniker predator
address@hidden example
+
address@hidden
+Otherwise you can copy the Makefile from @file{template/Makefile}
+in the directory containing the sequences. You should then change the compiled
+model file name, by changing the value of the
address@hidden variable to the name of your choice
+in the Makefile. It is set to @file{mymodel} in the template. For the
+predator-prey model, it could be set like
+
address@hidden
+model_file_name = predator
address@hidden example
+
+If you want the executable model file to be built in another directory, you
could
+set
+
address@hidden
+model_file_name = some_dir/predator
address@hidden example
+
+The other items set in the default Makefile should be right.
address@hidden enumerate
+
+The preprocessing and the compilation are launched with
+
address@hidden
+make all
address@hidden example
+
+The mortran files are generated by the cmz directive preprocessor
+from files found in the package source directories. The mortran files
+end with @samp{.mtn} for the main files and @samp{.mti} for
+include files. They are output in the current directory.
+The mortran preprocessor then preprocess these mortran files and includes
+the sequences. The resulting fortran code is also in the current directory,
+in files with a @samp{.f} suffix.
+Some fortran files ending with @samp{.F} may also be
+created by the cmz directive preprocessor.
+The object files resulting from the compilation of all the
+fortran files (generated from mortran or directly from fortran files) are
+there too.
+
+In case you want to override the default sequences or a subroutine file
+you just have to create it in your working directory along with the
address@hidden @c and @file{dimetaphi.mti}.
+For example you could want to
+create or modify a @file{zsteer.mti} file (@pxref{End of time step,,
+Executing code at the end of each time step}), a @file{zcmd_law.mti} file
+(@pxref{Control laws}), a @file{monitor.f} file
+(@pxref{Turning the model into a subroutine}) to take advantage of
+features presented later in this manual.
+
+More in-depth discussion of using make to run Miniker is covered in
address@hidden use of Miniker with make}.
+For example it is also possible to create files that are to be
+preprocessed by the cmz directive
+preprocessor and separate source files and generated files.
+This advanced use is more precisely covered in
address@hidden with cmz directives}.
+
address@hidden
address@hidden Simulation and output
address@hidden Running a simulation and using the output
+
address@hidden running model
+
+Once compiled the model is ready to run, it only has to be executed. On
+standard output informations about the states, transfers, tangent linear
+system and other jacobian matrices are printed.
+For example the predator-prey model could be executed with:
+
address@hidden
+./predator > result.lis
address@hidden example
+
address@hidden output file
address@hidden dEta(.)
address@hidden @file{res.data}
address@hidden @file{dres.data}
address@hidden @file{tr.data}
address@hidden @file{aspha.data}
address@hidden @file{Model.hlp}
+
address@hidden In case of a model entered symbolically
address@hidden (@pxref{Symbolic model description})
+The correspondance
+between the symbolic variables and the basic vectors and functions
+are printed at run time:
+
address@hidden
+ ---------------- Informing on Phi definition -----------------
+ Var-name, Function-name, index in ff vector
+ ff_interact f_interact 1
+ ----------------------------------------------------
+
+ --------------- Informing on Eta definition ------------------
+ Var-name, Function-name, index in eta vector
+ eta_prey deta_prey 1
+ eta_pred deta_pred 2
address@hidden example
+
+A summary of the model equations are in @file{Model.hlp} file. For
+the same example:
+
address@hidden
+======================= set_Phi
+
+ 1 ff_interact f_interact eta_pray*eta_pred
+======================= set_Eta
+
+ 1 eta_pray deta_pray apar*eta_pray-apar*ff_interact
+ 2 eta_pred deta_pred -cpar*eta_pred+cpar*ff_interact
address@hidden example
address@hidden FIXME never talked about that. Certainly not here
+when other general functions are specified with @code{f_set}, it can appear
+also in the same help file when replaced by @code{fun_set}.
+
+As far as possible, all data printed in the listing are associated
+with a name related to a variable. Here is an extract:
+
address@hidden
+ Gamma :-8.19100E-02-1.42151E-01 3.87150E-02
+ eta_courant eta_T_czcx eta_T_sz
+ ------------------------------------------------
+ Omega : 0.00000E+00 0.00000E+00 0.00000E+00 0.00000E+00
+ courant_L T_czcx Psi_Tczc Psi_Tsz
+ ------------------------------------------------
address@hidden example
+for the two known vectors of the system, and:
address@hidden
+ >ker : Matrice de couplage 4 4 4 4
+courant_L Raw(1,j=1,4): 1.000 -9.9010E-03 0.000 0.000
+T_czcx Raw(2,j=1,4): -2.7972E-02 1.000 0.000 9.9900E-04
+Psi_Tczcx Raw(3,j=1,4): 0.1605 9.7359E-02 1.000 -5.7321E-03
+Psi_Tsz Raw(4,j=1,4): 0.000 -0.1376 5.7225E-03 1.000
+ Var-Name courant_L T_czcx Psi_Tczc Psi_Tsz
+ ----------------------------------------------------------
address@hidden example
+
+where the @code{couplage} (coupling matrix) is given that corresponds
+to the matrix coupling the four transfer components after @math{\delta\eta}
+has been eliminated from system. It is computed in the subprogram
address@hidden (for kernel) which solves the system.
+
+Basic results are output in a set of @samp{.data} files.
+The first line (or two lines) describes the column with a @samp{#}
+character used to mark the lines as comments (for @command{gnuplot}
+for example).
+In the @samp{.data} files, the data are simply separated with spaces.
+Each data file has the @code{time} variable values as first column.
address@hidden@file{dres.data} has another time related variable as second
column:
address@hidden @file{dres.data}
address@hidden dt
address@hidden, the time step that can vary in the course of a simulation.}.
+Following columns give the values of @code{eta(.)} in @file{res.data},
address@hidden(.)} in @file{dres.data} -- the step by step variation of
address@hidden(.)} -- and @code{ff(.)} in @file{tr.data}.
+
+Along the simulation the @acronym{TEF} Jacobian matrices are computed.
+A transfer variables elimination process also leads to the definition
+of the classical state advance matrix of the system
+(the corresponding array is @code{aspha(.,.)} in the code).
+This matrix is output in the file @file{aspha.data} that is used to
+post-run dynamics analyses. The matrix columns are written column wise on each
+record.
address@hidden of fastest modes,,Stability analysis of fastest modes}.
address@hidden TLS,,Generalized
+tangent linear system analysis}. It is not used in the solving process.
+
+Other @samp{.data} files will be described later.
+
address@hidden FIXME already said
address@hidden At the begining of a run, the help file @file{Model.hlp} is
generated for
address@hidden global checkiing of the model. In the example, it is:
+
address@hidden @example
address@hidden ======================= set_Phi
address@hidden 1 ff_interact f_interact eta_pray*eta_pred
address@hidden ======================= set_Eta
address@hidden 1 eta_pray deta_pray
apar*eta_pray-apar*ff_interact
address@hidden 2 eta_pred deta_pred
-cpar*eta_pred+cpar*ff_interact
address@hidden @end example
+
+
address@hidden Graphics
address@hidden Doing graphics
+
address@hidden graphics
address@hidden graphics with @command{gnuplot}
address@hidden graphics with @command{PAW}
+
address@hidden The format of the @samp{.data} files are coherent with GNU
graphics, that is
address@hidden the data are simply separated with spaces.
+Since the data are simply separated with spaces, and comment lines
+begin with @samp{#}, the
+files can be vizualised with many programs.
+With @command{gnuplot}, for example, to plot @code{eta(@var{n})},
+the @command{gnuplot} statement could be:
+
address@hidden
+plot "res.data" using 1:(@var{n}+1)
address@hidden example
+
+The similar one for @code{ff(@var{n})}:
address@hidden
+plot "tr.data" using 1:(@var{n}+1)
address@hidden example
+
+For people using @command{PAW}, the CERN graphical computer code,
+Miniker prepares
+kumacs that allow to read process the @samp{.data} files in the form of
address@hidden (see the @cite{PAW manual} for more information).
+In that cas, the flag @code{sel paw} has to be gievn in the
@file{selsequ.kumac}.
+The generated n-tuples are ready to use only
+for vector dimension of at most 10 (including the variable @code{time}).
+These kumacs are overwritten each time the model is run. Usaually, gnuplot has
+to be preferred, but when using surfaces and histograms, PAW is better.
+The @file{gains.f} (and @file{go.xqt} is provided as an example in the
+Miniker files.
+
address@hidden Controlling the run
address@hidden Controlling the run
+
address@hidden controlling the run
+
+It is possible to add code that will be executed at the end of each time
+step. It is also possible to specify which time step leads to a printout on
+standard output. For maximal control, the code running te model may be
+turned into a subroutine to be called from another fortran (or C)
+program, this possibility is covered in @ref{Calling the model code}.
+
address@hidden
+* End of time step::
+* Controlling the printout and data output::
address@hidden menu
+
address@hidden End of time step
address@hidden Executing code at the end of each time step
+
address@hidden @file{zsteer}
address@hidden @file{zsteer.inc}
+
+The code in the sequence @file{zsteer} is executed at the end of each time
+step. It is possible to change the time step length (variable @code{dt})
+verify that the non linearity are not too big, or perform
+discontinuous modifications of the states. One available variable @code{res}
+might be usefull for time step monitoring. At the end of the time step,
+as soon as @math{\varphi} has been computed, a numerical test is applied
+on a pseudo relative quadratic residual between
address@hidden(\eta(t-dt)+d\varphi} (@code{ ffl}), where @math{d\varphi}
+is given by the system resolution in @code{ker},and
address@hidden(\eta),\varphi)}, Fortran variable (@code{ff}):
+
address@hidden
+! ========================================================
+! test linearite ffl - ff
+! ========================================================
+if (istep.gt.1)
+< res=0.; <io=1,m; res = res +(ffl(io)-ff(io))**2/max(one,ff(io)*ff(io)); >;
+ if (res .gt. TOL_FFL)
+ < print*,'*** pb linearite : res > TOL_FFL a istep',istep,res,' > ',TOL_FFL;
+ do io=1,m < z_pr: io,ff(io),ff(io)-ffl(io); >;
+ >;
+>;
address@hidden verbatim
+
+This test hence applies only for non linearities in tranfer models.
Nevertheless,
address@hidden might be usefull to monitor the time step @code{dt} in
@code{ZSTEER}
+and eventually go backward one step (@code{goto :ReDoStep:}).
+This can more appropriatly be coded in the (empty in default case)
+sequence @code{zstep}, inserted just before time-advancing
+states and @code{time} variables in @file{principal}.
address@hidden ffl(.)
address@hidden @code{ffl} (linearity test)
address@hidden linearity test
+
+It is also possible to fix the value of the criterium @code{TOL_FFL} in
address@hidden different from its default value of @math{10^{-3}} --
+independent of the Fortran precision.
+
+
+Many other variables are available, including
address@hidden @code
address@hidden istep
+The step number;
address@hidden couplage(.)
+The @acronym{TEF} coupling matrix between transfers;
address@hidden H
+The Jacobian matrix corresponding with:
address@hidden \varphi(t) &= f(\eta(t),\varphi(t))\cr
address@hidden \frac{\partial g(\eta(t),\varphi(t))}{\partial \eta(t)}
address@hidden
+$$\partial_{\eta} g(\eta(t),\varphi(t));
+$$
address@hidden tex
+g_1(eta,phi);
address@hidden Bb
+The Jacobian matrix corresponding with:
address@hidden
+$$\partial_{\varphi} g(\eta(t),\varphi(t));
+$$
address@hidden tex
+g_2(eta,phi);
address@hidden Bt
+The Jacobian matrix corresponding with:
address@hidden
+$$\partial_{\eta} f(\eta(t),\varphi(t));
+$$
address@hidden tex
+f_1(eta,phi);
address@hidden D
+The Jacobian matrix corresponding with:
address@hidden
+$$\partial_{\varphi} f(\eta(t),\varphi(t));
+$$
address@hidden tex
+f_2(eta,phi);
+
address@hidden aspha
+The state advance matrix;
address@hidden dneta
address@hidden dphi
+the variable increments;
address@hidden vtable
+One should be aware of that the linearity test concerns the preceding step.
+We have yet no example of managing the time-step.
+
address@hidden
address@hidden Controlling the printout and data output
address@hidden Controlling the printout and data output
+
address@hidden printing
address@hidden zprint
address@hidden modzprint
+
+The printout on standard output is performed if the variable @code{zprint}
+of type @code{logical} is true. Therefore it is possible to control this
+printout by setting @code{zprint} false or true. For example the following
+code, in sequence @file{zsteer}, triggers printing for every
address@hidden time step and the two following time steps:
+
address@hidden
+ZPRINT = mod(istep+1,modzprint).eq.0;
+Zprint = zprint .or. mod(istep+1,modzprint).eq.1;
+Zprint = zprint .or. mod(istep+1,modzprint).eq.2;
address@hidden example
+
+The data output to @file{.data} files described in @ref{Simulation and output,,
+Running a simulation and using the output} is performed if the
address@hidden variable @code{zout} is true. For example the following
+code, in @file{zsteer}, triggers output to @file{.data} files every
address@hidden step.
+
address@hidden
+Zout = mod(istep,modzout).eq.0;
address@hidden example
+
address@hidden Advanced programming
address@hidden Advanced Miniker programming
+
address@hidden
+* Selecting features::
+* Calling the model code::
+* 1D gridded model::
+* Double precision::
+* Partial Derivatives::
+* Rule of programming non continuous models::
+* Parameters::
+* Observations and data::
+* Explicit model size::
+* Programming with cmz directives::
address@hidden menu
+
address@hidden Selecting features
address@hidden Overview of additional features setting
+
address@hidden feature setting
address@hidden select flag
address@hidden logical flags
address@hidden @file{selseq.kumac}
+
+It is possible to enable some features by selecting which code should
+be part of the principal program. Each of these optionnal features are
+associated with a @dfn{select flag}.
+For example
address@hidden the optimisation with minuit is associated with the select
address@hidden flag @samp{minuik},
+double precision is used instead of simple precision with
+the @samp{double} select flag,
+the model is a subroutine with the select flag @samp{monitor},
+the Kalman filter code is set with @samp{kalman} and the 1D gridded
+model capabilities are associated with @samp{grid1d}.
address@hidden Currently it is only possible
address@hidden to select features in cmz.
+To select a given feature the cmz statement @code{sel @var{select_flag}} should
+be written down in the @file{selseq.kumac} found in the model directory.
+With make either the corresponding variable should be set to 1 or it
+should be added to the @code{SEL} make variable, depending on the feature.
+
+Other features don't need different or additional code to be used.
+Most of the features are enabled by setting specific logical variables to
address@hidden This is the case for
address@hidden for the adjoint model, @code{zcommand} if the command is in a
file
+and @code{zlaw} if it is a function and @code{zkalman} for the Kalman filter.
+These select and logical flags are described in the corresponding sections.
+
+In cmz an alternative of writing select flags to @file{selseq.kumac} is to
+drive the compilation with @code{smod @var{sel_flag}}. In that case the
address@hidden is selected and the files and executable goes to a directory
+named @file{sel_flag}.
+
+The select flags are taken into account during cmz directives preprocessing.
+Therefore you have the possibility to use these flags to conditionnaly
+include pieces of code. In most cases you don't need to include code
conditionally
+yourself though, but if you want to, this is covered in
address@hidden with cmz directives}.
+
address@hidden Calling the model code
address@hidden Calling the model code
+
+When the model code is a subroutine, it can be called from another fortran
+program unit (or another program), and the model will be
+run each time the subroutine is called.
+This technique could be used, for example to perform optimization
+(@pxref{Adjoint model and optimisation,,Adjoint model and optimisation
+with Miniker}), or to run the model with different parameters.
+
address@hidden
+* Turning the model into a subroutine::
+* The model subroutine::
address@hidden menu
+
address@hidden Turning the model into a subroutine
address@hidden Turning the model into a subroutine
+
address@hidden This feature is allready enabled with @command{make}, and to
address@hidden override the default program a file called @file{monitor.f} has
to be created
address@hidden in the working directory. The default program simple calls the
model
address@hidden subroutine.
+
+With cmz, one has to do a
address@hidden
+sel monitor
address@hidden example
+in the @file{selseq.kumac} file and create the KEEP that call the
+model code. @xref{Selecting features, Overview of additional features
+setting}.
+
+With make @samp{monitor} should be added to the @code{SEL} variable in
+the @file{Makefile}, for example:
+
address@hidden
+SEL = monitor
address@hidden example
+
+A file that call the principal subroutine should also be written, using
+the prefered language of the user. The additional object files should
+then be linked with the Miniker objects. To that aim they may be added
+to the @code{miniker_user_objects} variable.
+
address@hidden The model subroutine
address@hidden Calling the model subroutine
+
+The model subroutine is called @samp{principal} and is called with the
+following arguments:
+
address@hidden Subroutine principal (Cost, ncall, integer_flag, file_suffix,
info, idxerror)
+Where @var{Cost} is a real number, @code{real} or @code{double precision},
+and is set by the @code{principal}
+subroutine. It holds the value of the cost function if such function has been
+defined (the use and setting of a cost function is covered later,
+see @ref{Cost function coding and adjoint modeling}).
address@hidden is an integer which corresponds with the number of
+call to @code{principal} done so far, it should be initialized to 0 and
+its value should not be changed, as it is changed in the @code{principal}
+subroutine.
address@hidden is an integer that can be set by the user to be accessed
+in the @code{principal} subroutine. For example its value could be used to
+set some flags in the @file{zinit} sequence.
address@hidden is a character string, that is suffixed to the output files
+names instead of @samp{.data}. If the first character is the null character
address@hidden(0)}, the default suffix, @samp{.data} is appended.
address@hidden and @var{idxerror} are integer used for error reporting.
address@hidden value is 0 if there was no error. It is negative for
+an alert, positive for a very serious error. The precise value determines
+where the error occured.
address@hidden is an integer holding more precise information about the
+error. It is usually the information value from lapack.
+The precise meaning of these error codes is in @ref{tab:error_codes}.
address@hidden deffn
+
address@hidden table, tab:error_codes
address@hidden {kalman analysis state matrix advance in phase space,
@math{(I-D)} inversion} {inversion} address@hidden
address@hidden Source of error or warning @tab @code{info} @tab @code{idxerror}
address@hidden @item @code{} @tab @file{.data} @tab @tab
address@hidden state matrix inversion in ker @tab inversion @tab 1
address@hidden time advance system resolution in ker @tab system @tab 2
address@hidden transfer propagator, @math{(I-D)} inversion @tab inversion @tab 3
address@hidden kalman analysis state matrix advance in phase space,
@math{(I-D)} inversion @tab inversion @tab 21
address@hidden kalman analysis variance covariance matrix non positive @tab
Choleski @tab 22
address@hidden kalman analysis error matrix inversion @tab inversion @tab 23
address@hidden kalman error matrix advance @tab system @tab 24
address@hidden transfers determination linearity problem for transfers @tab
@tab -1
address@hidden transerts determination Newton D_loop does not converge @tab
@tab -2
address@hidden multitable
address@hidden of error codes returned by principal.}
address@hidden float
+
+In general more information than the provided arguments has to be passed
+to the @code{principal} subroutine, in that case a @code{common} block,
+to be written in the @file{zinit} sequence can be used.
+
address@hidden
address@hidden 1D gridded model
address@hidden Describing 1D gridded model
+
+Specific macros have been built that allow generic description of 1D gridded
models.
+Because of the necessity of defining left and right limiting conditions, the
models
+are partitionned in three groups for cell and transfer components. In the
following example,
+a chain of masselottes linked by springs and dumps is bounded to a wall on the
left,
+and open at right. The @acronym{TEF} formulation of the problem is written in
the phase space (position-shift, velocity)
+for node @math{k}, with bounding conditions:
address@hidden
+$$\left\{\eqalign{\partial_t \eta _{k} ^{pos} &= \eta _{k} ^{vel} \cr
+\partial_t \eta _{k} ^{vel} &= ( \varphi_k ^{spr} -\varphi _{k+1} ^{spr} +
\varphi _{k} ^{dmp}-\varphi _{k+1} ^{dmp})\,/m_k \cr}\right.$$
+$$\left\{\eqalign{
+\varphi_k ^{spr} &= -k_k (\eta _{k} ^{pos}- \eta _{k-1} ^{pos})\cr
+\varphi_k ^{spr} &= -d_k (\eta _{k} ^{vel}- \eta _{k-1} ^{vel})
+\cr}\right.$$
+$$\left\{\eqalign{\eta ^{pos}_{0} &= 0\cr
+\eta ^{vel}_{0} &= 0\cr
+\varphi ^{spr}_{N+1} &= 0\cr
+\varphi ^{dmp}_{N+1} &= 0\cr}\right.$$
address@hidden tex
+
+States:@*
address@hidden @math{d position(t,k)/d t = velocity(t,k)@*
+d velocity (t,k)/d t =(spring(t,k) - spring(t,k+1)+ dump(t,k)-
dump(t,k+1))/m_k}
+
+Transfers:@*
address@hidden @math{spring(t,k) = -k_k (position(t,k)- position(t,k-1))@*
+dump(k,t) &= -d_k (velocity(t,k)- velocity(t,k-1))}
+
+Bounding conditions:@*
address@hidden @math{position(t,0) = address@hidden
+velocity(t,0) = address@hidden
+spring(t,N+1) = address@hidden
+dump(t,N+1) =0}
+
+
address@hidden down node
address@hidden up node
+
+where @math{m_k} is the mass of node @math{k}, @math{r_k} and @math{d_k}
+the rigidity of springs and dumping coefficients. There are @math{N} nodes
+in the grid, from 1 to @math{N}, and two nodes outside of the grid,
+a limiting node 0, and a limiting node @math{N+1}. The limiting node
+corresponding with node 0 is called the @dfn{down} node, while the limiting
+node corresponding with node @math{N+1} is called the @dfn{up} node.
+Other models not part of the 1D grid may be added if any.
+
+To enable 1D gridded models, one should set the select flag @samp{grid1d}.
+In cmz it is achieved setting the select flag in
address@hidden, like
+
address@hidden
+sel grid1d
address@hidden example
+
+With make, the @code{SEL} variable should contain @code{grid1d}. For example
+to select @code{grid1d} and @code{monitor}, it could be
address@hidden
+SEL = grid1d,monitor
address@hidden example
+
+
address@hidden
+* 1D gridded Model size::
+* 1D gridded model code::
address@hidden menu
+
address@hidden 1D gridded Model size
address@hidden Setting dimensions for 1D gridded model
+
address@hidden FIXME grid1d sans dimetaphi?
+In that case the number of nodes, the number of states and tranferts
+per node, and the number of limiting transfers and states are required.
+These dimensions has to be entered in the
address@hidden sequence. The parameters for cells are
address@hidden @code
address@hidden n_node
+Number of cell nodes in the 1D grid.
address@hidden n_dwn
+Number of limiting cells with index -1, @i{i.e.} number of cells in the
+limiting down node.
address@hidden n_up
+Number of limiting cells with index +1, @i{i.e.} number of cells in the
+limiting up node.
address@hidden n_mult
+Number of cells in each node (multiplicity).
address@hidden vtable
+
address@hidden m_node
address@hidden m_dwn
address@hidden m_up
address@hidden m_mult
+The parameters for transfers, are similarly
address@hidden, @code{m_dwn}, @code{m_up}, @code{m_mult}.
+The layout of their declaration should be respected as
+the precompiler matches the line. Also this procedure is tedious, it
+should be selected for debuging processes (use the flag @code{sel dimetaphi}
+in ``selsequ.kumac''. Otherwise, the dimensioning sequence will be automaticaly
+generated, which is smart but can lead to diffculty in interpreting syntax
errors.
+Once a model is correctly entred, turn off the sel flag and further
modifications
+will automatically generate the proper dimensions. The correctness of
dimensionning
+should nevertheless always be checked in @code{principal.f}, where you can also
+check that null valued parameters as @code{lp, mobs, nxp} will suppress parts
+of the code - this is signaled as Fortran comment cards.
+
+In our example, there are three grids of cell and
+transfer variables (@code{n_node=m_node=3}).
+There are two cells and two transfers in each node
+(@code{n_mult=2} and @code{m_mult=2}). There is no limiting condition
+for the states in the down node therefore @code{n_up=0}.
+There is no transfer for the first limiting node, and
+therefore @code{m_dwn=0}.
+There are two states in the limiting node 0, the down node,
address@hidden, and two transfers in the limiting last node the node up,
+and @code{m_up=2}:
+
address@hidden
+! ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+! nodes parameters, and Limiting Conditions (Low and High)
+! ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+ parameter (n_node=3,n_dwn=2,n_up=0,n_mult=2);
+ parameter (m_node=3,m_dwn=0,m_up=2,m_mult=2);
+! ________________________________________________________
address@hidden example
+
+
address@hidden 1D gridded model code
address@hidden 1D gridded Model coding
+
+The model code and parameters go in the @file{zinit} sequence.
+
address@hidden Parameters
+
+A value for the Miniker parameters and the model parameters should be given in
address@hidden, in our example we have
+
address@hidden
+!%%%%%%%%%%%%%%%%%%%%%%
+! Parameters
+!%%%%%%%%%%%%%%%%%%%%%%
+real rk(n_node),rd(n_node),rmassm1(n_node);
+
+data rk/n_node*1./;
+data rd/n_node*0.1/;
+data rmassm1/n_node*1./;
+ dt=.01;
+ nstep=5 000;
+ modzprint = 1000;
+ time=0.;
address@hidden example
+
address@hidden Limiting conditions
+
address@hidden limiting conditions
+
address@hidden The limiting states and transfer variables and the corresponding
equations are
address@hidden declared using
address@hidden the symbolic model description
address@hidden (@pxref{Symbolic model description}).
+There are four mortran blocks for @code{node} and @code{up} and @code{down},
both
+for states and transfers:
+
address@hidden set_dwn_eta
address@hidden set_dwn_phi
address@hidden set_up_eta
address@hidden set_up_phi
+
address@hidden @code
address@hidden set_dwn_eta
+down node cells
address@hidden set_up_eta
+up node cells
address@hidden set_dwn_phi
+down node transfers
address@hidden set_up_phi
+up node transfers
address@hidden table
+
+The following scheme illustrates the example:
address@hidden
+!%%%%%%%%%%%%%%%%%%%%%%%%%%================================================
+! Maillage convention inode
+!%%%%%%%%%%%%%%%%%%%%%%%%%% Open ended
+!(2 Down Phi Eta (n_node)
+! Eta) \| .-----. .-----. .-----. /
+! wall \|-\/\/\-| |-\/\/\-| | . . . -| |-\/\/\- |dummy
+! pos \|--***--| 1 |--***--| 2 | . . . -| n |--***-- |Phis
+! speed \| 1 |_____| 2 |_____| n |_____| n+1 \(2 Up Phi)
+!
address@hidden smallexample
+
+Two states are associated with the down node, they correspond to the position
+and speed of the wall. As the wall don't move these states are initialized to
+be 0, and the cells are stationnary cells, therefore these values remain 0.
+
address@hidden
+! Down cells (wall)
+! -----------------
+eta_pos_wall = 0; eta_speed_wall = 0.;
+
+set_dwn_eta
+< var: eta_pos_wall, fun: deta_pos_wall = 0.;
+ var: eta_speed_wall, fun: deta_speed_wall= 0.;
+>;
address@hidden example
+
+There are 2 limiting transfers in the up node. They correspond with an open
+end and are therefore set to 0.
+
address@hidden
+! limiting Transfers : dummy ones
+! -------------------------------
+set_Up_Phi
+< var:ff_dummy_1, fun: f_dummy_1=0.;
+ var:ff_dummy_2, fun: f_dummy_2=0.;
+>;
address@hidden example
+
address@hidden Starting points
+
+The cell node state values are initialized. They are in an array
+indexed by the @code{inode} variable. In the example the variable
+corresponding with position is @code{eta_move} and the variable corresponding
+with speed is @code{eta_speed}. Their initial values are set with the
+following mortran code
+
address@hidden
+!---------------
+! Initialisation
+!---------------
+;
+do inode=1,n_node <eta_move(inode)=0.01; eta_speed(inode)=0.0;>;
address@hidden example
+
+If any transfer needs to be given a first-guess value, this is also done
+using @code{inode} as the node index.
+
address@hidden Grid node equations
+
address@hidden set_node_Phi
address@hidden set_node_eta
address@hidden equations, grid
+
+Each node is associated with an index @code{inode}. It allows to refer to the
+preceding node, with @code{inode-1} and the following node @code{inode+1}.
+The node states are declared in @code{set_node_Eta} block and the transfers are
+in @code{set_node_Phi} blocks.
+
+In the example, the cells are declared with
+
address@hidden
+! node cells
+! ----------
+;
+set_node_Eta
+< var: eta_move(inode), fun: deta_move(inode) = eta_speed(inode);
+ var: eta_speed(inode),
+ fun: deta_speed(inode) = rmassm1(inode)
+ *( - ff_spring(inode+1) + ff_spring(inode)
+ - ff_dump(inode+1) + ff_dump(inode)
+ );
+>;
address@hidden example
+Note that the @code{inode} is dummy in the @code{var:} definition and can as
+well be written as: @code{var: eta_move(.)}.
+
+
+The transfers are (@code{ff_spring} corresponds with springs and
address@hidden with dumps):
+
address@hidden
+!%%%%%%%%%%%%%%%%%%%%%%
+! Transfer definition
+!%%%%%%%%%%%%%%%%%%%%%%
+! node transfers
+! --------------
+! convention de signe spring : comprime:= +
+set_node_Phi
+< var: ff_spring(.),
+ fun:
+ f_spring(inode)= -rk(inode)*(eta_move(inode) - eta_move(inode-1));
+ var: ff_dump(.),
+ fun:
+ f_dump(inode) = -rd(inode)*(eta_speed(inode) - eta_speed(inode-1));
+>;
address@hidden example
+
+The limiting states and transfers are associated with the states or transfers
+with index @code{inode+1} or @code{inode-1} appearing in node cell and
+transfer equations (@code{inode-1} for down limiting conditions and
address@hidden for up limiting conditions) in their order of appearance.
+In our example, in the @code{eta_speed} state node equation
address@hidden(inode+1)} appears before @code{ff_dump(inode+1)} and is
+therefore associated with @code{ff_dummy_1} while @code{ff_dump(inode+1)} is
+associated with the @code{ff_dummy_2} limiting transfer, as @code{ff_dummy_1}
+appears before @code{ff_dummy_2} in the limiting up transfers definitions.
+Verification of the grid index coherence should be eased with the following
+help printed in the listing header:
+
address@hidden
+
+
+
+
+ --------------- Informing on Dwn Eta definition ---------------
+ Var-name, Function-name, index in eta vector
+ eta_pos_wall deta_pos_wall 1 [
+ eta_speed_wall deta_speed_wall 2 [
+
+ -------------- Informing on Eta Nodes definition --------------
+ Var-name, Function, k2index of (inode: 0 [ 1,...n_node ] n_node+1)
+ eta_move deta_move 1 [ 3 ... 7 ] 9
+ eta_speed deta_speed 2 [ 4 ... 8 ] 10
+
+ ---------------- Informing on Up Phi definition -------------
+ Var-name, Function-name, index in ff vector
+ ff_dummy_1 f_dummy_1 ] 7
+ ff_dummy_2 f_dummy_2 ] 8
+ ff_move_sum f_move_sum ] 9
+ ff_speed_sum f_speed_sum ] 10
+ ----------------------------------------------------
+
+ -------------- Informing on Phi Nodes definition ---------------
+ Var-name, Function, k2index of (inode: 0 [ 1,...m_node ] m_node+1)
+ ff_spring f_spring -1 [ 1 ... 5 ] 7
+ ff_dump f_dump 0 [ 2 ... 6 ] 8
+ ----------------------------------------------------
address@hidden example
+
+All variable names and functions are free but has to be
+different.
+Any particular node-attached variable @math{k} is referred to as:
@samp{(inode:k)},
+where @math{k} has to be a Fortran expression allowed in arguments. The symbol
address@hidden is
+reserved. As usual other Fortran instructions can be written within the
+Mortran block @samp{< >} of each @code{set_} block.
+
address@hidden Double precision
address@hidden Double precision
+
+The default for real variables is the @code{real} Fortran type. It is possible
to
+use double precision instead. In that case all the occurences of @samp{real@ }
+in mortran code is substituted with @samp{double precision@ } at
+precompilation stage,
+and the Lapack subroutine names are replaced by the double precision names.
+Eventual users'declaration of @code{complex@ } Fortran variables is also
+changed to @code{double complex@ }.
+
+This feature is turned on by @code{sel double} in @file{selseq.kumac} with cmz
+and @code{double = 1} in the @file{Makefile} with make.
+
+In order for the model to run as well in double as in simple precision,
+some care should be taken to use the generic intrinsic functions, like
address@hidden and not @code{dsin}. No numerical constant should be passed
directly
+to subroutines or functions, but instead a variable with the right type should
+be used to hold the constant value, taking advantage of the implicit casts
+to the variable type.
+
address@hidden Partial Derivatives
address@hidden Partial Derivatives
+
+The partial derivative rules are included in a @code{Mortran} macro series
+in @file{Derive_mac} of Miniker files. When using an anusual function,
+one should verify that the corersponding rules are in that file.
+It is easy to understand and add new rules in analogy with the already
existing ones.
+
+For instance, suppose one wants to use the intrinsic Fortran function @code{
abs()}.
+Its derivatives uses the other function @code{sign()} this way:
+
address@hidden
+ &'(ABS(#))(/#)' = '((#1)(/#2)*SIGN(1.,#1))'
address@hidden example
+
+In such cases when one is adding a new rule, it is important to use the
generic function names
+only (i.e. @code{sin} not @code{dsin}), because when compilating Miniker in
the double precision
+version, or complex version, the generic names will correctly handle the
different variable
+types - which is not the case when coding with specific function names.
+
address@hidden
+* Derivating a power function::
address@hidden menu
+
address@hidden Derivating a power function
address@hidden Derivating a power function
+
+Partial derivative of a function in exponent is not secure in its Fortran form
address@hidden(x,y)**(f(y))}. It should be replaced by @code{power(g,f)} of
+the Miniker @file{mathlib},
+or by the explicit form @code{exp(f(y)*log(g(x,y)))}.
+
+Its derivative will have the following form:
+
+
address@hidden
+$$\eqalign{\partial_x f^g &= g f^{g-1}\partial_x f + f^g \log f\partial_x g\cr
+ &= f^{g-1}(g\partial_x f + f\partial_x g)\cr}$$
address@hidden tex
+
+and is in the macros list already defined in: @file{DERIVE_MAC}.
+
address@hidden Rule of programming non continuous models
address@hidden Rule of programming non continuous models
+
+Some models may originally be non continuous, as the ones using a Fortran
instruction @code{IF}.
+Some may use implicitly a step function on a variable. In such cases, the
model has to be
+set in a derivable form, and use a ``smooth step'' instead.
+ One should be aware of that this apparently mathematical treatment currently
+indeed leads to a physical question about the macroscopic form of a physical
law.
+At a macroscipic level, a step function is usually a nonsense.
address@hidden Heaviside function
+Taking
+the example of phase-change, a fluid volume does not change phase at once, and
a ``smooth
+change of state'' is a correct macroscopic model.
+
+Miniker provides with the smooth step function
address@hidden@footnote{This naming is a joke
+for ``Inert'' Heaviside function.} in the Miniker @file{mathlib}:
+
address@hidden
+ Delta = -1."K";
+ A_Ice = heavyside("in:" (T_K-Tf), Delta, "out:" dAIce_dT);
address@hidden example
+
+in this example, @code{Tf} is the ice fusion-temperature, @code{A_ice}
+gives the ice-fraction
+of the mesh-volume of water at temperature @code{T_k}.
+The smooth-step function is a quasi
+hyperbolic tangent function of @math{x/\Delta},
+normalised from 0 to 1, with a maximum slope
+of 2.5, see figure @ref{heavy}.
+
address@hidden Figure, heavy
address@hidden
address@hidden function and derivative}
address@hidden float
+
+For @code{Mortran} to be able to symbolicaly compute the partial derivarives,
the rule
+is in the table of macros as:
+
address@hidden
+&'(HEAVYSIDE(#,#,#))(/#)' = '((#1)(/#4)*HEAVYDELTA(#1,#2,#3))'
address@hidden example
+
+which uses the Foratn entry point @code{HeavyDelta} in the Fortrsan function
@code{heavyside}.
+
+Another type of problem arises when coding a
address@hidden(f(x),g(x))} Fortran instruction.
+In such a case one does not want a derivative and one will code:
+
address@hidden
+var = HeavySide(f(x)-g(x),Delta,dum)*g(x) +
(1.-HeavySide(f(x)-g(x),Delta,dum)*f(x);
address@hidden example
+
+or equivalently:
+
address@hidden
+var = HeavySide(f(x)-g(x),Delta,dum)*g(x) +
HeavySide(g(x)-f(x),-Delta,dum)*f(x);
address@hidden example
+
address@hidden: the value of the argument @var{Delta} is important because
+it will fix the maximum
+slope of the function that will appear as a coefficient in the
+Jacbian matrices.
+
address@hidden Parameters
address@hidden Parameters
+
+It is possible to specify some Fortran variables as specific model parameters.
+Model parameters
+may be used in sensitivity studies (@pxref{Sensitivity to a parameter})
+and in the adjoint model (@pxref{Sensitivity of cost function to parameters}).
+Nothing special is done with parameters with Kalman filtering.
+
+
address@hidden Free_parameter
+
+The parameters are fortran variables that should be initialized somewhere
+in @file{zinit}. For a variable to be considered as a parameter, it should
+be passed as an
+argument to the @code{Free_parameters} macro. For example if
address@hidden and @code{cpar} (from the predator example) are to be considered
+as parameters, @code{Free_parameters} should be called with:
+
address@hidden
+Free_parameter: apar, cpar;
address@hidden example
+
address@hidden Forward sensitivities are explained later (@pxref{Sensitivity to
a parameter}),
address@hidden the syntax only is described here.
+
+
+When used with grid1d models (@pxref{1D gridded model,,
+Describing 1D gridded model}) the @code{inode} number may appear in
+parenthesis:
+
address@hidden
+Free_parameter: rd(1), rk(2);
address@hidden example
+
address@hidden Observations and data
address@hidden Observations and data
+
+Some support for observations and interactions with data is available.
+The observations are functions of the model variables. They don't have
+any action on the model result, but they may (in theory) be observed
+and measured. The natural use of these observations is to be compared
+with data that correspond with the values from real measurements.
+They are used in the Kalman filter (@pxref{Kalman filter}).
+
+The (model) observation vector is noted @math{\omega}
address@hidden FIXME is seems untrue?
address@hidden in this section ($\mu$ elsewhere,
+and the observation function is noted @math{h}:
+
address@hidden
+$$
+\omega = h ( \eta , \varphi)
+$$
address@hidden tex
+
address@hidden @math{omega(t) = h(eta(t), phi(t))}
+
+
address@hidden
+* Observations::
+* Data::
address@hidden menu
+
address@hidden Observations
address@hidden Observations
+
address@hidden mobs
+
+The observation functions are set in a @code{set_probe} block in
+the @file{zinit} sequence.
+
address@hidden observation function
+
address@hidden FIXME doesn't exist anymore
address@hidden @defmac eqn: Obs_tef(@var{i}) = f(eta(.),ff(.))
address@hidden This macro defines the observation equation as usual in a
@code{set_block<}.
address@hidden @code{f} is a fortran
address@hidden expression which may be function of cell state variables,
address@hidden @samp{eta(1)address@hidden@samp{eta(np)} and transfers
address@hidden @samp{ff(1)address@hidden@samp{ff(mp)}, or of course their
symbolic names.
address@hidden @end defmac
+
+For example suppose that, in the predator-prey model, we only
+have access to the total population of preys and predators, we would have:
+
address@hidden
+set_probe
+< eqn: pop = eta_pred + eta_pray;
+>;
address@hidden example
+
address@hidden it is always turned on, now
address@hidden The corresponding code is used with @code{sel obs} in
@file{selseq.kumac}
address@hidden with cmz and @code{obs = 1} in @file{Makefile} with make. And
the feature
address@hidden is turned on and off at run time with the logical flag
@code{zobs} corresponding
address@hidden to an available data from measurement
+
address@hidden @vindex etaobs(.)
address@hidden @file{obs.data}
+
+The number of observations is put in the integer variable @code{mobs}.
+The observation vector corresponds with the part of the @code{ff(.)}
+array situated past the regular transferts, @code{ff(mp+.)}, and is output
+in the file @file{obs.data}.
+
address@hidden @vindex obetad(.,.)
address@hidden @vindex obephid(.,.)
address@hidden @vindex obspha(.,.)
+
address@hidden Data
address@hidden Data
+
address@hidden zgetobs
address@hidden vobs(.)
address@hidden @file{data.data}
+
+Currently this code is only used if the Kalman code is activated. This
+may be changed in the future.
+
+The convention for data is that whenever some data are available, the
+logical variable @code{zgetobs} should be set to @samp{.true.}. And the
address@hidden(.)} vector should be filled with the data values. This
+vector has the same dimension than the observation
+vector and each coordinate is meant to correspond with one
+coordinate of the observation vector.
+
+This feature is turned on by setting the logical variable @code{zdata}
+to @samp{.true.}, and the @code{zgetobs} flag is typically set in the
address@hidden sequence (@pxref{End of time step,,Executing code at
+the end of each time step}).
+Every instant data are available (@code{zgetobs} is true) the observations
+are written to the file @file{data.data}. With the Kalman filter more
+informations are output to the @file{data.data} file,
+see @ref{Kalman filter results}.
+
+
address@hidden Explicit model size
address@hidden Entering model size explicitely
+
+It is possible to enter the model dimensions explicitely, instead of
+generating them automatically, as it was done previously.
+This feature is turned on by @code{sel dimetaphi}
+in @file{selseq.kumac} with cmz
+and @code{dimetaphi} added to the @code{SEL} variable in
+the @file{Makefile} with make.
+
address@hidden
+* Size sequence::
+* Model with explicit size::
address@hidden menu
+
address@hidden Size sequence
address@hidden The explicit size sequence
+
address@hidden dimetaphi
address@hidden model size
address@hidden np
address@hidden mp
address@hidden maxstep
address@hidden @file{dimetaphi}
+
+The dimension of the model is entered in the sequence @file{dimetaphi},
+using the fortran @code{parameter np} for @code{eta(.)} and
address@hidden for @code{ff(.)}.
+For the Lotka-Volterra model, we have two cell components and only one
transfer.
+
address@hidden
+parameter (np=2,mp=1);
address@hidden example
+
+You should not change the layout of the parameter statement as the
+mortran preprocessor matches the line.
+
+You also have to provide other parameters even if you don't have any
+use for them. If you don't it will trigger fortran errors.
+It includes the @code{maxstep} parameter that can have any value but 0,
address@hidden and @code{mobs} that should be 0 in the example, and @code{nxp},
address@hidden and @code{nzp} that should also be 0.
+The layout is the following:
+
address@hidden
+parameter (np=2,mp=1);
+parameter (mobs=0);
+
+parameter (nxp=0,nyp=0,nzp=0);
+parameter (lp=0);
+parameter (maxstep=1);
address@hidden example
+
+If there are observations, (@pxref{Observations}), the
+size of the observation vector is set in the @file{dimetaphi} sequence
+by the @code{mobs} parameter. For example if there is one observation:
+
address@hidden
+parameter (mobs=1);
address@hidden example
+
+To specify parameters (@pxref{Parameters}), the number of such parameters
+has to be declared in @file{dimetaphi} with the parameter @code{lp}.
+Then, if there are two parameters, they are first declared with
+
address@hidden
+parameter (lp=2);
address@hidden example
+
address@hidden Model with explicit size
address@hidden Entering the model equations, with explicit sizes
+
address@hidden model equations
address@hidden Phi_tef(.)
address@hidden deta_tef(.)
address@hidden eta(.), explicit sizes
address@hidden ff(.), explicit sizes
+
+When sizes are explicit, another possibility exists for entering
+the model equations. The use of symbolic names, as described in
address@hidden equations} is still possible, and it also becomes possible to
+set directly the equations associated with the @code{eta(.)}
+and @code{ff(.)} vectors.
+
+In case the symbolic names are not used,
+the model equations for cells and transfers are entered using a mortran macro,
address@hidden@address@hidden, or equivalently @code{f_set}, is a
+general mortran macro associating a symbol with a fortran expression.
+Here, it is the name of the symbol (@code{eta}) that has a particular meaning
+for the building of the model.}, setting the @code{eta(.)} evolution with
address@hidden(.)}
+and the transfer definitions @code{ff(.)} with @code{Phi_tef(.)}.
+
address@hidden f_set Phi_tef(@var{i}) = f(eta(.),ff(.))
+This macro defines the transfer @var{i} static equation.
address@hidden is a fortran
+expression which may be function of cell state variables,
address@hidden(1)address@hidden@samp{eta(np)} and transfers
address@hidden(1)address@hidden@samp{ff(mp)}.
address@hidden defmac
+
+In the case of the predator-prey model, the transfer definition for
address@hidden is:
address@hidden
+f_set Phi_tef(1) = eta(1)*eta(2);
address@hidden example
+
address@hidden f_set deta_tef(@var{i}) = g(eta(@var{i}),ff(.))
+This macro defines the cell state component @var{i} time evolution model.
address@hidden is a expression which may be function of cell state variables,
address@hidden(1)address@hidden@samp{eta(np)} and transfers
address@hidden(1)address@hidden@samp{ff(mp)}.
address@hidden defmac
+
+The two cell equations of the predator-prey model are, with index 1 for the
+prey (@math{\eta_{prey}}) and index 2 for the predator (@math{\eta_{pred}}):
+
address@hidden
+f_set deta_tef(1) = apar*eta(1)-apar*ff(1);
+f_set deta_tef(2) = - cpar*eta(2) + cpar*ff(1);
address@hidden example
+
+The whole model is:
+
address@hidden
+!%%%%%%%%%%%%%%%%%%%%%%
+! Transfer definition
+!%%%%%%%%%%%%%%%%%%%%%%
+! rencontres (meeting)
+ f_set Phi_tef(1) = eta(1)*eta(2);
+
+!%%%%%%%%%%%%%%%%%%%%%%
+! Cell definition
+!%%%%%%%%%%%%%%%%%%%%%%
+! eta(1) : prey
+! eta(2) : predator
+
+ f_set deta_tef(1) = apar*eta(1)-apar*ff(1);
+ f_set deta_tef(2) = - cpar*eta(2) + cpar*ff(1);
address@hidden example
+
+The starting points for cells are entered like:
address@hidden
+! initial state
+! -------------
+ eta(1) = 1.;
+ eta(2) = 1.;
address@hidden example
+
+If there are observations, they are entered as special transferts with
+index above @code{mp}, for example:
+
address@hidden
+f_set Phi_tef(mp+1) = ff(1) ;
address@hidden example
+
address@hidden Programming with cmz directives
address@hidden Programming with cmz directives
+
address@hidden
+* Cmz directives used with Miniker::
+* Using cmz directives in Miniker::
address@hidden menu
+
address@hidden Cmz directives used with Miniker
address@hidden Cmz directives used with Miniker
+
+The main feature of cmz directive is to use code conditionnaly for a given
+select flag. For example when the double precision is selected
+(@pxref{Double precision}) the use of the conditionnal
address@hidden flag may be required in case there is a different subroutine
+name for different types. If, for example, the user use the subroutine
address@hidden for simple precision and @code{dmysub} for double
+precision the following code is an example of what could appear in the
+user code:
+
address@hidden
++IF,double
+ call dmysub(eta);
++ELSE
+ call smysub(eta);
++ENDIF
address@hidden verbatim
+
+For a complete reference on cmz directives see the appendix
address@hidden directives reference}.
+
address@hidden Using cmz directives in Miniker
address@hidden Using cmz directives in Miniker
+
+In cmz the KEEP and DECK have their cmz directives preprocessed as part
+of the source files extraction. And the +KEEP and +DECK
+directives are automatically
+set when creating the KEEP or DECK. With make, files with these directives
+has to be created within the files that are to be preprocessed by the
+cmz directives preprocessor.
+
+To be processed by make, a file that contains cmz directives
+should have a file suffix corresponding
+with the language of the resulting file and with the normal file suffix of
+that language. More precisely @samp{cm} should be added before the normal
+file suffix and after the @samp{.}. Therefore if the resulting file language
+is associated with a suffix @address@hidden, the file with cmz directives
+should have a @address@hidden suffix. The tradition is to have
+a different suffix for main files and include files.
+To add directories searched for @dfn{cmfiles} (files with cmz directives)
+they should be added to the @code{CMFDIRS} makefile variable, separated
+by @samp{:}.
+
+Rules for preprocessing of the files are defined in the file
address@hidden for the file types described in
address@hidden:cmfile_suffix}:
+
address@hidden table, tab:cmfile_suffix
address@hidden {fortran preprocessed} {include/keep} {cmfile suffix} {suffix}
{language}
address@hidden language @tab file type @tab cmfile suffix @tab suffix @tab
language
address@hidden fortran @tab main/deck @tab .cmf @tab .f @tab ftn
address@hidden fortran preprocessed @tab main/deck @tab .cmF @tab .F @tab f77
address@hidden fortran preprocessed @tab include/keep @tab .cminc @tab .inc
@tab f77
address@hidden mortran @tab main/deck @tab .cmmtn @tab .mtn @tab mtn
address@hidden mortran @tab include/keep @tab .cmmti @tab .mti @tab mtn
address@hidden multitable
address@hidden between file language, file type, file suffixes and
+language identifier in cmz directives. A main file is called a @dfn{deck}
+in cmz and an include file is called a @dfn{keep}.}
address@hidden float
+
address@hidden Dynamic system analysis
address@hidden Dynamic analysis of systems in Miniker
+
address@hidden
+* Sensitivities::
+* Adjoint model and optimisation::
+* Kalman filter::
+* Feedback gain::
+* Stability of fastest modes::
+* Generalized TLS::
address@hidden menu
+
address@hidden Sensitivities
address@hidden Automatic sensitivity computation
+
address@hidden sensitivities
+
+An obvious advantage of having acces to the Jacobian matrices along the
+system trajectory concerns automatic sensitivity analyses, as either:
address@hidden @bullet
address@hidden the sensitivity of all variables to perturbation in the initial
condition
+ of one state variable;
address@hidden the same sensitivities to an initial pulse (or step) on a
transfer;
address@hidden the same sensitivities to a series of pulses (or steps) on a
transfer;
address@hidden the same for a change in a parameter, eventually during the run;
address@hidden the sensitivity of the matrix of advance in state space to a
change
+ in a parameter.
address@hidden itemize
+
+This is declared in Zinit as:
+
address@hidden
+! -------------
+! Sensitivities
+! -------------
+Sensy_to_var
+< var: eta_pray, pert: INIT;
+ var: eta_pred, pert: INIT;
+>;
address@hidden example
+
+Each variable at origin of a perturbation is declared as @code{var:},
+and the type of perturbation in @code{pert:}. Here, INIT conditions are
+only allowed because the two variables are states variables. For transfers,
address@hidden: pulse} corresponds to an initial pulse, @code{pert: step_resp}
+and @code{pert: step_eff} to initial steps, the difference between
address@hidden (response form)
+and @code{_eff} (effect form) concerns the
+diagonal only of the sensitivity matrix
+(see Feedback gains in non-linear models).
+
+Non initial perturbation can also be asked for:
+
address@hidden
+ Sensy_to_var
+ <
+!* var: eta_courant_L, pert: init at 100;
+!* var: ff_T_czcx, pert: pulse at 100 every 20;
+!* var: ff_Psi_Tczcx, pert: step_eff;
+!* var: ff_Psi_Tczcx, pert: step_Resp at 10 every 100;
+! *** premiers tests identiques a lorhcl.ref
+ var: ff_courant_L , pert: step_eff;
+ var: ff_T_czcx , pert: step_eff;
+ var: ff_Psi_Tczcx , pert: step_eff;
+ var: ff_Psi_Tsz , pert: pulse at 100 every 50;
+ >;
address@hidden example
+
+In this example taken from @file{lorhcl}, a sensitivity can increase so as to
+trespass the Fortran capacity, so that each sensitivity vector (matrix column)
+can be reset at some time-increment @code{at III every JJJ;}
+
+It is noteworthy that these sensitivity analyses are not based
+on difference between two runs with different initial states or
+parameter values, but on the formal derivatives of the model. This method
+is not only numerically robust, but is also rigorously funded as based on
+the TLS of the address@hidden a short introduction to automatic
+sensitivity analysis, see the document:@*
address@hidden://lmd.jussieu.fr/zoom/doc/sensibilite.ps}, in French,
+or ask for the more complete research document to a member of the TEF-ZOOM
+collaboration}.
+
+If the @code{dimetaphi} sequence is built by the users, he should declare
+the number of perturbing variables as @code{nxp=}:
+
address@hidden
+ parameter (nxp=np,nyp=0,nzp=0);
address@hidden example
+here, all state variables are considered as perturbing variables.
+
address@hidden sensitivity, output
address@hidden output, sensitivity
address@hidden @file{sens.data}
address@hidden @file{sigma.data}
+
+The sensitivity vectors are output in the result files @file{sens.data} for
+cells and @file{sigma.data} for transfers. In those files the first column
+corresponds again with time, and the other columns are relative sensitivities
of the cell
+states (in @file{sens.data}) and transfers (in @file{sigma.data})
+with respect to the initial value of the perturbed state.
+
+In our predator-prey example, the second column of @file{sens.data} will
contain
+the derivative of @math{\eta_1(t)} with respect to @math{\eta_1(t=0)}.
+Drawing the
+second column of @file{sens.data} against the first one
+gives the time evolution of the sensitivity of @code{eta-pred}
+to a change in the initial value of @code{eta-pray}. One can check
+in that it is set to 1 at @math{t=0}:
+
address@hidden
+# Sensy_to: eta_pray 3 eta_pred 5
+# time \\ of: eta_pray eta_pred eta_pray eta_pred
+ 0.00000E+00 1.00000E+00 0.00000E+00 0.00000E+00 1.00000E+00
+ 1.00000E-02 9.90868E-01 1.11905E-02 -1.26414E-02 9.98859E-01
address@hidden example
+The two last columns are the state sensitivity to a change in initial
conditions
+of the number of predators.
+
+In the same way, the @var{j+1}th column of @file{sigma.data} will be the
+derivative of @math{\phi_{j}(t)} with respect to @math{\eta_i(t=0)}. Here:
address@hidden
+# Sensy_to: eta_pray eta_pred
+# time \\ of: ff_interact ff_interact
+ 0.00000E+00 1.60683E+00 8.47076E-01
+ 1.00000E-02 1.59980E+00 8.18164E-01
address@hidden example
+
+the unique transfer variable gives rise to two sensitivity columns.
+
+Sensitivity studies are usefull to assess the
+predictability properties of the corresponding system.
+
address@hidden
address@hidden * Initial state sensitivity::
address@hidden * Sensitivity to a pulse or a step on transfer::
address@hidden * Extended Sensitivity studies::
+* Sensitivity to a parameter::
+* Advance matrix sensitivity::
address@hidden menu
+
+
+
address@hidden Sensitivity to a parameter
address@hidden Sensitivity to a parameter
+
+A forward sensitivity to a parameter will be computed when specified as
+described in @ref{Parameters}. For example, suppose that
+the sensitivity to an initial change in the @code{apar} parameter of
+the predator model is of interest.
address@hidden In that case the number of
address@hidden parameters should be set to 1 in @file{dimetaphi}:
address@hidden
address@hidden @example
address@hidden parameter (lp=2);
address@hidden @end example
+
+The sensitivity calculs is turned on as a forward
+parameter specified on the @code{Free_parameter} list:
+
address@hidden
+Free_parameter: [fwd: apar, cpar];
address@hidden example
+
+The result are in @file{sensp.data} for cells and @file{sigmap.data}
+for transfers.
+
address@hidden
+# Sensy_to: pi_prandtl 3 4 pi_rayleigh_ 6
+# time \\ of: eta_courant_ eta_T_czcx eta_T_sz eta_courant_ eta_T
+ 0.00000E+00 0.00000E+00 0.00000E+00 0.00000E+00 0.00000E+00 0.000
+ 2.00000E-03 -4.77172E-03 -3.99170E-05 3.55971E-05 -9.94770E-05 -1.004
address@hidden example
+In the above example from @file{lorhcl} sensitivity of the three states with
respect
+to an initial change in two parameters are independantly given (first line
also numbers
+the column to easy gnuplot using).
+
address@hidden Advance matrix sensitivity
address@hidden Advance matrix sensitivity
+
+
+It is possible to look at the sensitivity of the matrix of advance in
+states space (the matrix @code{aspha}) with regard to a parameter.
+The parameter must be accounted for in the parameter number and be in the
+parameter list, flagged as the matrix @code{mx} parameter, like in
address@hidden
+Free_parameter: [mx: apar], cpar;
address@hidden example
+
address@hidden d_pi_aspha(.,.)
+
+This feature is associated with a selecting flag, @samp{dPi_aspha}. One gets
+the result in the matrix @code{d_pi_aspha(.,.)} of dimension
+(@code{np},@code{np}).
+
+This matrix may be used to compute other quantities, for example
+it may be used to compute the sensitivity of the eigenvalues of
+the state-advance matrix with regard to the @code{[fwd]} parameter.
+These additional computations have to be programmed by the user in
address@hidden with matrices declared and initialized in
address@hidden An example is given in the example @file{lorhcl}
+provided with the Miniker installation files, following a method proposed
+by Stephane Blanco.
+
address@hidden Adjoint model and optimisation
address@hidden Adjoint model and optimisation with Miniker
+
+In the following a possible use of Miniker for optimisation is discussed.
+More precisely the use of adjoint and control laws in Miniker are presented.
+Optimisation isn't the only application of these tools, but it is the most
+common one. In that case the adjoint may be used to determine the gradient of a
+functional to perturbations in the control laws, and an optimisation process
+can use this
+information to search for the optimum.
+Another application of the adjoint is to compute the sensitivity of a
+cost function to parameters (the ones declared in the @code{free_parameters:}'
list.
+Note that the cost function can be sensitive to probe's variables, even if
these are
+uncoupled with standard variables in the forward calculations; this is the case
+when minimizing a quadratic distance function between probes (from the model)
+and the corresponding measurements.
+
+The code is close transcription of the mathematical calculus described
address@hidden @url{http://www.lmd.jussieu.fr/ZOOM/doc/Adjoint.pdf} . It
essentialy reverse time and
+transpose the four Jacobian matrices: states and transfers are saved in array
dimensionned
+with @code{maxstep} Fortran parameter.
address@hidden
+* Overview of optimisation with Miniker::
+* Control laws::
+* Cost function coding and adjoint modeling::
+* Sensitivity of cost function to parameters::
address@hidden menu
+
address@hidden Overview of optimisation with Miniker
address@hidden Overview of optimisation with Miniker
+
address@hidden adjoint
address@hidden optimisation
+
+In the proposed method, Miniker is run twice, one time forward and then
+backward to determine the trajectory and the adjoint model. After that the
+control laws are modified by a program external to Miniker. The same steps
+are repeated until convergence. More pecisely,
+
address@hidden @strong
address@hidden forward
+The command law @math{h(t)} is given (by an explicit law or taken from a file).
+The trajectory is computed in a classical way, with the additionnal computation
+of the functional to be optimised, @math{J}, prescribed with specific
address@hidden macros. The states, transfers and control laws are stored.
address@hidden backward
+The adjoint variable is computed from the last time @math{T} backward. The
+time increment is re-read as it could have changed during the forward
+simulation. The system is solved by using the same technics as in the forward
+simulation, but with a negative time step.
address@hidden external phase
+Now the command should be corrected. This step isn't covered here, but, for
+example, minuit the optimisation tool from the CERN could be used.
+In order to ease such a use of Miniker, the principal program has to be
+compiled as a subroutine to be driven by an external program
+(@pxref{Calling the model code}).
address@hidden table
+
+The functionnal @math{J} to be optimised is defined as
+
address@hidden
+$$
+J = \psi[\eta(T),\varphi(T) ,h(T)] + \int_0 ^T
{l[\eta(\tau),\varphi(\tau),h(\tau)]}\, d\tau
+$$
address@hidden tex
address@hidden @math{J = psi(eta(T),phi(T),h(T)) + int_0^T
l(eta(tau),phi(tau),h(tau)) d tau}
+
address@hidden final cost
address@hidden integrand cost
+
+Where @math{\psi} is the final cost function, @math{l} is the integrand
+cost function and @math{h} represents the control laws variations.
+
+The general use of the adjoint model of a system is the determination of the
+gradient of this @math{J} functional to be optimised, with respect to
perturbations
+of the original conditions of the reference trajectory, that is, along its
address@hidden Tangent Linear System, i.e. the TLS circulating along a
trajectory.
+See the explanation in the document
address@hidden://www.lmd.jussieu.fr/Zoom/doc/Adjoint.pdf} (in French).}.
+
address@hidden Control laws
address@hidden Control laws
+
address@hidden zcommand
address@hidden command law
+
+Each control law is associated with one cell or transfer equation, meaning
that a command
+associated with an equation does not appear in any other equation.
+It is still possible
+to add commands acting anywhere by defining a transfer equal to that command.
+
+
+The control laws associated with states are in the @code{ux_com(.)} array,
+control laws associated with transfers are in the @code{uy_com(.)} array.
+The control laws may be prescribed even when there is no adjoint computed,
+nor any optimisation, and they are used during simulation, in which case they
will
+act as external sources. To enable
+the use of commands, the logical flag @code{Zcommand} should be @code{.true.}.
+
address@hidden @file{uxcom.data}
address@hidden @file{uycom.data}
+
+The command can be given either as:
address@hidden
address@hidden a table of numerical
+values in the files @file{uxcom.data} and @file{uycom.data}.
address@hidden a function
address@hidden zlaw
address@hidden @file{zcmd_law}
address@hidden @file{zcmd_law.inc}
+of the problem variables. To turn that feature on the logical flag
address@hidden should be set to @code{.true.} in @file{zinit}. The sequence
address@hidden should hold
+the code filling the @code{ux_com(.)} and @code{uy_com(.)} arrays, as the code
+from that sequence is used whenever the control laws are needed.
+In that case the files @file{uxcom.data} and @file{uycom.data} will
+be filled by the command values generated by the function along the trajectory.
address@hidden enumerate
+
+For example in the Lotka-Volterra model, the parameter @code{apar} could
+be a control variable.
+In that case, @code{apar} would be defined as the variable @code{ux_com(1)},
+and either entered as a law
+in the sequence @file{zcmd_law} , either written in the file @file{uxcom.data}
+step by step. In that case, there must be a perfect corresponodence between
time
+of the commands and time of the run.
+
address@hidden Cost function coding and adjoint modeling
address@hidden Cost function coding and adjoint modeling
+
address@hidden zback
address@hidden cout_Psi
address@hidden cout_l
+
+First of all the flag @code{zback} should be set to @code{.true.} in order to
+allow adjoint model computation:
+
address@hidden
+Zback=.true.;
address@hidden example
+
+The two functions @code{cout_Psi} corresponding with the final cost and
address@hidden corresponding with the integrand cost are set up with the
address@hidden macros.
+
address@hidden f_set cout_Psi = f(eta(.),ff(.),ux_com(.),uy_com(.))
+This macro defines the final cost function.
address@hidden is a fortran
+expression which may be function of cell state variables,
address@hidden(1)address@hidden@samp{eta(np)}, transfers
address@hidden(1)address@hidden@samp{ff(mp)},
+state control laws
address@hidden(1)address@hidden@samp{ux_com(np)}, and transfer control laws
address@hidden(1)address@hidden@samp{uy_com(mp)}.
address@hidden defmac
+
address@hidden f_set cout_l = f(eta(.),ff(.),ux_com(.),uy_com(.))
+This macro defines the integrand cost function.
address@hidden is a fortran
+expression which may be function of cell state variables,
address@hidden(1)address@hidden@samp{eta(np)}, transfers
address@hidden(1)address@hidden@samp{ff(mp)},
+state control laws
address@hidden(1)address@hidden@samp{ux_com(np)}, and transfer control laws
address@hidden(1)address@hidden@samp{uy_com(mp)}.
address@hidden defmac
+
+For example, the following code sets a cost function for the masselottes
+model:
+
address@hidden
+! Initialisation
+ F_set cout_Psi = eta_move(inode:1);
+!and f_set cout_l integrand in the functionnal
+ F_set cout_l = 0.;
address@hidden example
+
+In that example the functional is reduced to the final value
+of the first state component.
+Here, the adjoint vector will correspond to the final sensitivity
+(at @math{t=0}) of
+that component (here the first masselotte position) to a perturbation in
+all initial address@hidden detailed explanation of the adjoint model,
+see the document in
address@hidden://www.lmd.jussieu.fr/@/ZOOM/doc/Adjoint.pdf,pdf}
+or @uref{http://www.lmd.jussieu.fr/@/ZOOM/doc/Adjoint.pdf,.ps.gz}}.
+
address@hidden In the code, the variables @code{v_adj(.)} and @code{w_adj(.)}
address@hidden are respectively adjoint to @code{eta(.)} and @code{ff(.)}. They
are written in the
address@hidden two files: @file{vadj.data} and @file{wadj.data}.
+The following variables are set during the backward phase, and output
+in the associated files:
+
+
address@hidden address@hidden(.)}} address@hidden {time increment, hamiltonian,
cost function increment}
address@hidden var @tab file @tab explanation
address@hidden @item @code{} @tab @file{.data} @tab @tab
address@hidden @code{v_adj(.)} @tab @file{vadj.data} @tab adjoint to
@code{eta(.)}
address@hidden @code{w_adj(.)} @tab @file{wadj.data} @tab adjoint to
@code{ff(.)}
address@hidden @code{wadj(mp+.)} @tab @file{gradmuj.data} @tab adjoint to
@code{ff(mp+.)}
address@hidden @code{graduej(.)} @tab @file{gradxj.data} @tab adjoint to
@code{ux_com(.)}
address@hidden @code{gradufj(.)} @tab @file{gradyj.data} @tab adjoint to
@code{uy_com(.)}
address@hidden @code{hamilton} @tab @file{hamilton.data} @tab time increment,
hamiltonian, cost function increment
address@hidden multitable
+
address@hidden Sensitivity of cost function to parameters
address@hidden Sensitivity of cost function to parameters
+
address@hidden @file{gradpj.data}
+
+The sensitivity of the cost function to all the parameters given as
+arguments of @code{Free_parameters} is computed. For the
+predator model the sensitivity of a cost function consisting in
+the integral of the predator population with respect with
address@hidden an @code{cpar} is obtained with a number of parameters
+set to 2 in @file{dimetaphi}:
+
address@hidden
+parameter (lp=2);
address@hidden example
+
+And the cost function and @code{Free_parameters} list in @file{zinit}:
+
address@hidden
+f_set cout_Psi = eta(2);
+f_set cout_l = eta(2);
+Free_parameters: apar,cpar;
address@hidden example
+
address@hidden and @code{cpar} also have to be given a value.
+The result is output in @file{gradpj.data}.
+
address@hidden Kalman filter
address@hidden Kalman filter
+
address@hidden Kalman filter
address@hidden variance-covariance matrices, general
address@hidden observations, general
+
+The Kalman filter allows for data assimilation along the model run. In
+that case it is assumed that there is a real-world model with stochastic
+perturbations on the states, and that noisy observations are available.
+The situation implemented in Miniker corresponds to a continuous
+stochastic perturbation on the state, and discrete noisy observations.
+In the @acronym{TEF} this leads to:
+
address@hidden
+$$\eqalign{
+\partial_t \eta (t) &= g(\eta(t),\varphi(t)) + W(t) \mu\cr
+\varphi(t) &= f(\eta(t),\varphi(t))\cr
+\omega(t) &= h ( \eta(t) , \varphi(t)) + \nu\cr
+}$$
address@hidden tex
+
address@hidden @math{d eta(t)/d t = g(eta(t),phi(t)) + W(t) address@hidden
+phi(i) = f(eta(t),phi(t))@*
+omega(t) = h(eta(t), phi(t)) + nu }
+
+
address@hidden FIXME partout omega
address@hidden (notice that in this paragraph, $\omega$ stands for the probe
vector $\mu$ elsewhere,
address@hidden and $\mu$ is here a noise source.
+
+The observations @math{\omega} are available at discrete time steps
@math{t=s_i}. The
+stochastic perturbation on state, @math{\mu} is characterized by a
+variance-covariance matrix @math{Q} and the noise on the observation,
address@hidden has a variance-covariance matrix @math{R}. @math{W} relates
states
+with stochastic perturbations. At each time step the Kalman filter recomputes
+an estimation of the state and the variance-covariance matrix of the state.
+
+In the following we use the example of a linear model with perturbation
+on state and observation of state. The model has 3 states and 3 corresponding
+transfers (equal to the states), but the error on the state is of dimension
+2. The 3 states are observed. The corresponding equations read:
+
address@hidden
+$$\left\{\eqalign{
+\partial_t \eta_1 &= a_{11} \eta_1 + a_{12} \varphi_2 + a_{13} \varphi_3 +
W_{11} \mu_1 + W_{12} \mu_2\cr
+\partial_t \eta_2 &= a_{21} \varphi_1 + a_{22} \eta_2 + a_{23} \varphi_3 +
W_{21} \mu_1 + W_{22} \mu_2\cr
+\partial_t \eta_3 &= a_{31} \varphi_1 + a_{32} \varphi_2 + a_{33} \eta_3 +
W_{31} \mu_1 + W_{32} \mu_2
+}\right.$$
+$$\left\{\eqalign{
+\varphi _1 &= \eta _1\cr
+\varphi _2 &= \eta _2\cr
+\varphi _3 &= \eta _3
+}\right.$$
+$$\left\{\eqalign{
+\omega _1 &= \varphi _1 + \nu_1\cr
+\omega _2 &= \eta _2 + \nu_2 \cr
+\omega _3 &= \eta _3 + \nu_3
+}\right.$$
address@hidden tex
+
+
+Cells:@*
address@hidden @math{d eta_1/dt = a_11 eta_1 + a_12 phi_2 + a_13 phi_3 + W_11
mu_1 + W_12 address@hidden
+d eta_2/dt = a_21 phi_1 + a_22 eta_2 + a_23 phi_3 + W_21 mu_1 + W_22
address@hidden
+d eta_3/dt = a_31 phi_1 + a_32 phi_2 + a_33 eta_3 + W_31 mu_1 + W_32 mu_2}
+
+Transfers:@*
address@hidden @math{phi_1 = address@hidden
+phi_2 = address@hidden
+phi_3 = eta_3}
+
+Observations:@*
address@hidden @math{omega_1 = phi_1 + address@hidden
+omega_2 = eta_2 + address@hidden
+omega_3 = eta_3 + nu_3}
+
+
address@hidden
+* Coding the Kalman filter::
+* Kalman filter run and output::
+* Executing code after the analysis::
address@hidden menu
+
address@hidden Coding the Kalman filter
address@hidden Coding the Kalman filter
+
address@hidden zkalman
+
+First of all the Kalman filter code should be activated. The observations
+code is also required (@pxref{Observations}).
+If cmz is used the code
+should be selected with the select flag kalman
+in the @file{selseq.kumac}:
+
address@hidden
+sel kalman
address@hidden example
+
+With make the @code{kalman} variable should be set to 1:
+
address@hidden
+kalman = 1
address@hidden example
+
+The kalman code is actually used by setting the flag
address@hidden to @code{.true.}, for example in the @file{zinit}:
+
address@hidden
+zkalman = .True.;
address@hidden example
+
address@hidden This will set the @code{zobs} and @code{zdata} flags to
@code{.true.}
address@hidden (@pxref{Observations and data}).
+
+With the Kalman filter the dimension of estimated states, of the error
+on the state and of the
+observation, the @math{W} matrix, the observation function,
+the initial
+variance-covariance matrices on the state and the variance-covariance matrices
+of errors have to be given.
+
address@hidden
+* Kalman filter vectors dimensions::
+* Error and observation matrices::
address@hidden menu
+
address@hidden Kalman filter vectors dimensions
address@hidden Kalman filter vectors dimensions
+
address@hidden error vector dimension
address@hidden @file{dimetaphi}, Kalman filter
+
+These dimensions should be set in the @file{zinit} sequence.
+The size of the estimated states is given by the parameter @code{nkp}.
+You can set this to @code{np} if all the states are estimated, but in case
+there are some deterministic state variables, @code{nkp} may be less than
address@hidden In that case the first @code{nkp} elements of @code{eta(.)}
+will be estimated using the Kalman filter.
+
+The error on state dimension is associated with the parameter @code{nerrp}
+and the size of the observations vector is @code{mobs}
+(@pxref{Observations}). In our example the dimensions are set with:
+
address@hidden
+parameter (nkp=np);
+parameter (mobs=3);
+parameter (nerrp=2);
address@hidden example
+
+All the states are estimated,
+there are 3 observation functions and the error on the state vector is of
+dimension 2.
+
+If the sizes are set explicitely, the parameters should be set in
address@hidden
+
address@hidden Error and observation matrices
address@hidden Error and observation matrices
+
address@hidden variance-covariance matrices
address@hidden observations
address@hidden @file{zinit}, Kalman filter
+
address@hidden Initial variance-covariance matrix on the state
+
address@hidden initial variance-covariance on states
address@hidden covfor(.,.)
+
+The variance-covariance on the state matrix is @code{covfor(.,.)}. The initial
+values have to be given for this matrix, as in our example:
+
address@hidden
+covfor(1,1) = 1000.; covfor(1,2) = 10.; covfor(1,3) = 10.;
+covfor(2,1) = 10.; covfor(2,2) = 5000.; covfor(2,3) = 5.;
+covfor(3,1) = 10.; covfor(3,2) = 5.; covfor(3,3) = 2000.;
address@hidden example
+
+This matrix is updated by the filter at each time step because the states
+are pertubated by some noise, and when assimilation takes place as new
+information reduce the error.
+
address@hidden Observations and error on state matrix
+
address@hidden variance-covariance matrix on state
address@hidden mereta(.,.)
+
+The matrix that relates errors on states vector components to states,
+corresponding with @math{W} is @code{mereta(.,.)}. In our example it is
+set by:
+
address@hidden
+mereta(1,1) = 1.; mereta(1,2) = 0.;
+mereta(2,1) = 0.; mereta(2,2) = 1.;
+mereta(3,1) = 0.5; mereta(3,2) = 0.5;
address@hidden example
+
+The observation functions are set by a @code{f_set} macro with
address@hidden(.)} as described in @ref{Observations}.
+In our example the observation functions are set by:
+
address@hidden
+f_set Obs_tef(1) = ff(1) ;
+f_set Obs_tef(2) = eta(2);
+f_set Obs_tef(3) = eta(3);
address@hidden example
+
address@hidden Error variance-covariance matrices
+
address@hidden variance-covariance error
address@hidden covobs(.,.)
+
+The variance-covariance matrix on observation noise is @code{covobs(.,.)}
+set, in our example, by:
+
address@hidden
+covobs(1,1) = 0.3; covobs(1,2) = 0.; covobs(1,3) = 0.;
+covobs(2,1) = 0.; covobs(2,2) = 0.1; covobs(2,3) = 0.;
+covobs(3,1) = 0.; covobs(3,2) = 0.; covobs(3,3) = 0.2;
address@hidden example
+
address@hidden coveta(.,.)
+The variance-covariance matrix on state noise is @code{coveta(.,.)}
+set, in our example, by:
+
address@hidden
+coveta(1,1) = 0.2; coveta(1,2) = 0.001;
+coveta(2,1) = 0.001; coveta(2,2) = 0.1;
address@hidden example
+
+These matrices are not changed during the run of the model as part
+of the filtering process. They may be changed by the user in @file{zsteer}.
+
address@hidden Kalman filter run and output
address@hidden Kalman filter run and output
+
address@hidden
+* Feeding the observations::
+* Kalman filter results::
address@hidden menu
+
address@hidden Feeding the observations
address@hidden Feeding the observations to the model
+
address@hidden vobs(.)
address@hidden zgetobs
address@hidden @file{zsteer}, Kalman filter
+
+The observations must be made available to the model during the run. These
+observations are set in the @code{vobs(.)} array, and the assimilation
+(also called the analysis step of the filter) takes
+place if the logical variable @code{zgetobs} is @code{.true.}
+(@pxref{Data}).
+
+These steps are
+typically performed in the @file{zsteer} sequence. In this sequence there
should
+be some code such that when there are data ready to
+be assimilated, @code{zgetobs} is set to @code{.true.} and the data is
+stored in @code{vobs(.)}, ready for the next step processing.
+
address@hidden Kalman filter results
address@hidden Kalman filter results
+
address@hidden results, Kalman filter
address@hidden Kalman filter results
address@hidden output, Kalman filter
address@hidden Kalman filter output
address@hidden @file{data.data}
+
+The estimated states and transfers are still in the same @samp{.data} files,
address@hidden and @file{tr.data} and there is the additional file with
+observations, called @file{obs.data} (@pxref{Observations}).
+Each time @code{zgetobs} is @code{.true.} the data, and the optimally
+weighted innovations are output
+in the file associated with data, @file{data.data} (@pxref{Data}).
+
address@hidden Executing code after the analysis
address@hidden Executing code after the analysis
+
+The analysis takes place before the time step advance when @code{zgetobs}
+is @code{.true.}. It may be usefull to add some code after the analysis
+and before the time step advance. For example the analysis may lead to
+absurd values for some states or parameters, it could be usefull to correct
+them in that case. The sequence included after the analysis is called
address@hidden At this point, in addition to the usual variables
+the following variables could be usefull:
+
address@hidden @code
address@hidden etafor(.)
+The state before the analysis.
address@hidden kgain(.)
+The Kalman gain.
address@hidden innobs(.)
+The innovation vector (observations coherent with the states minus data
+values).
address@hidden covana(.,.)
+The variance-covariance error matrix after the analysis.
address@hidden vtable
+
+At each time step the derivative of the observation function with respect
+to transfer and cells variables are recomputed. The elimination of
+transfers is also performed to get the partial derivative of the observation
+function of the equivalent model, with states only, with respect to the
+states. In other words, the Kalman filter does not follow the TEF formalism,
because
+the advance of the var-covar matrix could not yet be set in the TEF form.
address@hidden There is a corresponding additional matrix:
+
address@hidden @code
address@hidden @item obetad(.,.)
address@hidden derivative of observation function with respect to transfers.
address@hidden @item obphid(.,.)
address@hidden derivative of observation function with respect to cell
variables.
address@hidden obspha(.,.)
+derivative of observation function in state space with respect to
+cell variables.
address@hidden vtable
+
+
address@hidden Feedback gain
address@hidden Feedback gain
+
+
address@hidden Borel sweep
address@hidden Feedback gain
+
+The feedback dynamic gain associated with a feedback loop
+can be expressed as the inverse Borel
+transform of the coefficient of the reduced scalar
+coupling matrix, @math{g(\tau)},
+associated with a transfer.
+A Borel sweep provides this @math{g(\tau)}. Therefore it is
+an interesting tool for the characterization of the feedback address@hidden
+More generally, the Borel sweep allows
+the numerical study of the dependency in @math{\tau} of the Borel transform
+of various coefficients in the system coupling matrix.}.
+
+As explained in the
+ZOOM web page document
address@hidden://www.lmd.jussieu.fr/@/ZOOM/doc/@/Feedback_Gain.pdf},
+this allows for the calculation of the
+dynamic gain and factor of any feedback that goes through a unique
+transfer variable. An example of the conclusions that can be drawn from such
+an analysis is provided in the same document.
+
+
+
+For linear systems -- whose GTLS are autonomous along the whole trajectory --
+the @math{\tau} function of the
+feedback gain is independent of the position on the system trajectory.
+But in general it is dependant, and one can analyse the function
address@hidden(\tau;t)} defined on a segment @math{t} of the trajectory.
+
+The document introducing the TEF-ZOOM technique explains how a Crank-Nicolson
+scheme for the time discretisation
+symbolically gives the solution of the Borel transform of the system. One can
+identify the @code{dt} variable with the Borel @math{\tau} within a
+factor @math{2}. Hence, to numerically study the @math{\tau} dependency of
+the transform of various coefficients in the system coupling matrix at one
+point in time, one can calculate the Borel transform of the TLS solutions
+by making a time-step sweep.
+
+The function @math{g(\tau;t)} is simply output for the feedback gain
+attached to a unique @code{ff(k)} transfer variable.
+All the relevant informations should be entered in the @file{zinit} sequence.
+
address@hidden
+* Specifying the Borel sweep::
+* Borel sweep results::
address@hidden menu
+
address@hidden Specifying the Borel sweep
address@hidden Specifying the Borel sweep
+
address@hidden ZBorel
+
+First of all the logical flag @code{ZBorel} should be raised:
+
address@hidden
+ZBorel=.true.;
address@hidden example
+
address@hidden index_ff_gain
+The index of the studied transfer is given in the @code{index_ff_gain}
+variable
address@hidden
+index_ff_gain=7;
address@hidden example
+
+At each time step a Borel sweep may be performed. The time steps of interest
+are
+specified with three variables, one for the first step, one for the last step
+and one for the number of steps between two Borel sweeps:
+
address@hidden @code
address@hidden istep_B_deb
+First time step for the Borel sweep.
address@hidden istep_B_fin
+Last time step for the Borel sweep.
address@hidden istep_B_inc
+Number of time steps between Borel sweeps.
address@hidden vtable
+
+In the following examples Borel sweeps are performed from the
+time step 1000 up to the time step 1200, with a sweep at each time step:
address@hidden
+istep_B_deb=1000;
+istep_B_fin=1200;
+istep_B_inc=1;
address@hidden example
+
+
+For each Borel sweep, the range of the @math{\tau} variable should be
+set. As this is a multiplicative variable the initial value, a multiplicative
+factor and the number of values are to be given.
+
address@hidden @code
address@hidden tau_B_ini
+Initial value for @math{\tau}.
address@hidden tau_B_mult
+Multiplicative factor for sweep in @math{tau}.
address@hidden itau_max
+Number of @math{\tau} values.
address@hidden vtable
+
+For example, in the following, at each time step, the Borel
+transform will be computed for @math{\tau} values
+starting at @math{0.2} and then multiplied a hundred times by
@math{\sqrt{\sqrt{2}}}
+
address@hidden
+tau_B_ini=0.2;
+tau_B_mult=sqrt(sqrt(2.));
+itau_max=100;
address@hidden example
+
+When the initial value of @math{\tau} is set to a negative value
+(@i{i.e.} @code{tau_B_ini=-0.2;}),
+the Borel sweep will first be applied with @code{itau_max} negative values
+for @code{-0.2}, @code{tau_B_mult*(-0.2)},..., then for the zero value,
+and finally for the symetric positive values, resulting in @code{2*itau_max+1}
+values for @math{\tau}.
+
+The whole example reads
+
address@hidden
+! -------------------
+! Feedback gain
+! Borel
+! -------------------
+ZBorel=.true.;
+if ZBorel
+< istep_B_deb=1000;
+ istep_B_fin=1200;
+ istep_B_inc=1;
+;
+ index_ff_gain=7;
+ tau_B_ini=0.2;
+ tau_B_mult=sqrt(sqrt(2.));
+ itau_max=100;
+ z_pr/Borel/:tau_B_mult,tau_B_ini*(tau_B_mult)**itau_max;
+>;
address@hidden example
+
address@hidden zborel for
+
+Instead of using the index of the transfer in @code{index_ff_gain} it is
+possible to specify the name of the address@hidden , whenever
address@hidden the symbolic model description is used (@pxref{Symbolic model
description}).
+In that case the transfer is specified
+by the @code{zborel for} macro. For example if the transfer selected for the
+feedback gain computation is @var{b_transfer}, it can be selected
+with:
+
address@hidden
+zborel for: @var{b_transfer};
address@hidden example
+
address@hidden Borel sweep results
address@hidden Borel sweep results
+
address@hidden Borel sweep results
address@hidden results, Borel sweep
address@hidden Borel sweep graphics
address@hidden graphics, Borel sweep
+
+The file @file{tau_Borel.data} gives the @math{\tau} values of the @var{tau}
sweep,
+and the file @file{gains.data} records the feedback gain function values of
address@hidden(\tau)}, with
+one line for each sweep along the trajectory. In the 1.01 version, a new
+feature is also provided giving the poles and residuals of the Borel
+transform in the file @file{vpgains.data}. Consult the subroutine
address@hidden
+for (not definitive) output description.
+
+One can easily obtain the surface contours of @math{g(t,\tau)} using
+the Fortran program provided as @file{gains.f} and its compilation shell
address@hidden,
+that builds 2D histograms for PAW, in which one uses the
address@hidden provided kumac.
+
address@hidden Stability of fastest modes
address@hidden Stability analysis of fastest modes
+
address@hidden SVD
address@hidden Singular Value Decomposition
address@hidden state matrix
address@hidden @file{sltc.exe}
+
+The preceding analyses are done along with a simulation. One has also the
+possibility of using in a more classical fashion the state advance matrix
address@hidden, after the end of the simulation. Code to perform the
address@hidden, Singular Value Decomposition} of the state matrix @math{A_{st}}
+and also of @math{A_{st} + A_{st}^\dagger} is provided with Miniker.
+The singular elements of these two matrices correspond to the most
+rapid modes of instability of the perturbed system.
+
+The Singular value decomposition of a matrix is noted
+
address@hidden
+$$
+ U w V^\dagger
+$$
address@hidden tex
+
address@hidden @math{U w V^t}
+
+
+An executable file, @file{sltc.exe} is generated and running this file will
+produce the corresponding results.
+
address@hidden
+* SVD with cmz::
+* SVD with make::
+* SVD run and output::
address@hidden menu
+
address@hidden SVD with cmz
address@hidden Singular Value Decomposition with cmz
+
address@hidden @command{smod}
+
+The cmz macro @code{smod SLTC} prepares a main program
+(@file{circul} of +PATCH SLTC), provided as a base for user's own analysis,
+in the directory @file{sltc/}.
+
address@hidden SVD with make
address@hidden Singular Value Decomposition with make
+
address@hidden @file{Makefile.sltc}
+
+To compile the singular value decomposition executable with @command{make} you
+can do
address@hidden
+make sltc.exe
address@hidden example
+
+If you want to have a separate directory for the SVD, you should copy
+the sequence @file{dimetaphi.inc} (or make a link to that file) to the
+directory. You should also copy the file @file{Makefile.sltc} from the
address@hidden/} directory in this directory, rename it @file{Makefile}
+and set the Miniker directory path in the
address@hidden variable. For
+example, if the Miniker directory is in @file{/u/src/mini_ker}:
+
address@hidden
+miniker_dir = /u/src/mini_ker
address@hidden example
+
address@hidden SVD run and output
address@hidden Singular Value Decomposition run and output
+
address@hidden SVD run
address@hidden run, SVD
address@hidden SVD output
address@hidden output, SVD
address@hidden @file{sltc.exe}
address@hidden @file{title.tex}, SVD
address@hidden @file{aspha.data}, SVD
+
+As it is, the @file{sltc.exe} executable generated by the compilation
+determines the SVD. This program requires @file{title.tex} (@pxref{Title
file}) to
+transmit a title for output and graphics, and @file{aspha.data}
+(@pxref{Simulation and output,,Running a simulation and using the output})
+to access the
+state matrix. To get access to these files (in case they are not in the current
+directory) it is possible to make a link to
+the corresponding files in the model directory. Once it is done
+the program may be run:
+
address@hidden
+./sltc.exe
address@hidden example
+
+The files @file{u.data}, @file{w.data}, and @file{v.data} holds the singular
elements
+for @math{A_{st}} (@math{U}, @math{w} and @math{V}),
+and @file{us.data}, @file{ws.data}, and @file{vs.data}
+holds the singular elements of @math{A_{st} + A_{st}^\dagger}.
+The corresponding macros @samp{.kumac} for address@hidden in
+the research paper about SLTC (Al1 2003) available on request.}
+are also generated.
+
address@hidden Generalized TLS
address@hidden Generalized linear tangent system analysis
+
address@hidden Generalized linear tangent system
address@hidden GTLS
address@hidden propagator
address@hidden Lyapunov exponents
address@hidden @file{sltcirc.exe}
+
+The state matrix @math{A_{st}} may also be used to compute the
+GTLS propagator (or state transition matrix applied to perturbation), after
the simulation.
+The algorithm is a finite product of
+5th order development of
address@hidden(t+\delta t,t)=\exp{A_{st} \delta t}}.
+Numerous element of analysis are given, in particular the determination
+of the Lyapunov exponents of the system.
+
+An executable file, @file{sltcirc.exe} is generated and running this file will
+produce the corresponding results.
+
address@hidden
+* GTLS with cmz::
+* GTLS with make::
+* GTLS run and output::
address@hidden menu
+
address@hidden GTLS with cmz
address@hidden Generalized tangent linear system with cmz
+
address@hidden @command{smod}
+
+The cmz macro @code{smod SLTCIRC} prepares a main program
+(@file{circule} of +PATCH SLTCIRC), in the directory @file{sltcirc/}.
+
address@hidden GTLS with make
address@hidden Generalized tangent linear system with make
+
address@hidden @file{Makefile.sltcirc}
+
+To compile the GTLS analysis executable with @command{make} you
+can do
address@hidden
+make sltcirc.exe
address@hidden example
+
+If you want to have a separate directory for the GTLS analysis, you should
copy
+the sequence @file{dimetaphi.inc} (or make a link to that file) to the
+directory. You should also copy the file @file{Makefile.sltcirc} from the
address@hidden/} directory in this directory and rename it @file{Makefile}
+and set the Miniker directory path in the @code{miniker_dir} variable.
+
address@hidden GTLS run and output
address@hidden Generalized tangent linear system analysis run and output
+
address@hidden GTLS run
address@hidden run, GTLS
address@hidden GTLS output
address@hidden output, GTLS
address@hidden @file{sltcirc.exe}
address@hidden @file{title.tex}, GTLS
address@hidden @file{dres.data}, GTLS
address@hidden @file{aspha.data}, GTLS
+
+The @file{sltcirc.exe} executable generated by the compilation
+computes the elements of analysis of the system. This program requires
address@hidden to
+transmit a title for output and graphics (@pxref{Title file}),
address@hidden to access the
+state matrix and @file{dres.data}, because time-step can be changed along the
+simulation
+(@pxref{Simulation and output,,Running a simulation and using the output})
address@hidden our research texts about propagator analyses in
+SLTC, and ``les Gains sur champs (Al1 2003-2004)''}. To get access to these
files
+(in case they are not in the current
+directory) it is possible to make a link to
+the corresponding files in the model directory. Once it is done
+the program may be run:
+
address@hidden
+./sltcirc.exe
address@hidden example
+
+The following table gives the correspondence between variable name,
+result file and ntuple number, with a short explanation:
+
address@hidden address@hidden(.,.)}} address@hidden {ntuple} {eigen factors of
@math{w} in the SVD of @math{\Phi}}
address@hidden var @tab file @tab ntuple @tab explanation
address@hidden @code{p(.,.)} @tab @file{phit.data} @tab 55 @tab propagator from
0 to @math{t}, @math{\Phi(t,0)}
address@hidden @code{up(.,.)} @tab @file{uphit.data} @tab 50 @tab Left singular
vectors @math{U} in the SVD of @math{\Phi}
address@hidden @code{wp(.)} @tab @file{wphit.data} @tab 51 @tab singulat values
@math{w} in the SVD of @math{\Phi}
address@hidden @code{vp(.,.)} @tab @file{vphit.data} @tab 52 @tab Right
Singular Vectors @math{V} in the SVD of @math{\Phi}
address@hidden @code{wr(.)} @tab @file{wr.data} @tab 53 @tab real part of
eigen values of @math{\Phi(t,0)}
address@hidden @code{wi(.)} @tab @file{wi.data} @tab 54 @tab imaginary part of
eigen values of @math{\Phi(t,0)}
address@hidden @code{lwp(.)} @tab @file{lwphit.data} @tab 67 @tab Lyapunov
exponents
address@hidden @item @code{lwr(.,.)} @tab @file{lwr.data} @tab 68 @tab
address@hidden @item @code{lwi(.,.)} @tab @file{lwi.data} @tab 69 @tab
address@hidden @item @code{} @tab @file{.data} @tab @tab
address@hidden multitable
+
+
address@hidden Advanced use of Miniker with make
address@hidden Advanced use of Miniker with make
+
address@hidden
+* Make variables::
+* Rules::
+* Linking rule::
address@hidden menu
+
address@hidden Make variables
address@hidden Make variables
+
address@hidden @file{Makefile.miniker}
+
+The @file{Makefile.miniker} Makefile provided in the
+distribution should be included as it defines a lot of important
+variables and rules.
+
+The following make variables can be set by the user:
+
address@hidden @code
address@hidden miniker_dir
+that variable should hold the Miniker sources directory. If you installed
+Miniker that variable should be set to @file{$(includedir)/mini_ker}.
+If you use the sources right from the sources directory it should be set to
+the sources package directory.
address@hidden MTNDIRS
+This variable can hold a @samp{:} delimited list of directories that will
+be searched for mortran include files.
address@hidden CMFDIRS
+This variable can hold a @samp{:} delimited list of directories that will
+be searched for cmz directive include files.
address@hidden SEL
+This variable holds a @samp{,} delimited list of select flags, for example
address@hidden, @code{grid1d}, @code{debug}.
address@hidden LDADD
+This variable can be used to add libraries flags and files. It is used in
+the default linking command/rule.
address@hidden miniker_user_objects
+This variable should hold a space separated list of additional object files
+to be linked with the model and helper object files.
address@hidden CAR2TXTFLAGS
+cmz directives preprocessor flag.
address@hidden kalman
+This variable should be set to 1 if you want to use the kalman filter
+(@pxref{Kalman filter}).
address@hidden double
+This variable should be set to 1 if you want to have a double precision
+code (@pxref{Double precision}).
address@hidden table
+
+The following variables are allready set and may be used
+(some are set by ./configure see @ref{Configuration}):
+
address@hidden @code
address@hidden miniker_principal_objects
+The list of object files needed for the model build, together with some
+helper object files often used but not strictly required for the linking.
address@hidden DEPDIR
+The name of a hidden directory containing the dependencies computed
+for the main mortran files.
address@hidden F77
address@hidden FC
address@hidden FFLAGS
address@hidden LDFLAGS
+Compiler and linker related variables set by ./configure.
address@hidden LIBS
+This variable should hold the link flags and files required to build
+Miniker, set by ./configure.
address@hidden CAR2TXT
address@hidden MORTRAN
address@hidden MTNFLAGS
address@hidden MTNDEPEND
+Preprocessor and preprocessor flags, set by ./configure.
address@hidden table
+
address@hidden Rules
address@hidden Rules
+
+The following rules are defined in the @file{Makefile.miniker} file.
address@hidden @code
address@hidden miniker-clean
+remove the fortran files generated from the mortran files. Remove
+the object files.
address@hidden miniker-mtn-clean
+remove the mortran files generated from the files with cmz directives.
address@hidden
+Various rules to preprocess files with cmz directives and mortran files and
+to compile fortran files.
address@hidden table
+
+If the user needs a mortran main file, he may take advantage of the rule
+used to compute the dependencies of a mortran file. If the file is called,
+say, @file{mtnfile.mtn} leading to @file{mtnfile.f}, the following include
+should lead to the automatic creation, updating and inclusion of a
+file describing the dependencies of @file{mtnfile.mtn} in the
address@hidden:
+
address@hidden
+include $(DEPDIR)/mtnfile.Pf
address@hidden example
+
address@hidden Linking rule
address@hidden Linking rule
+
+The rule used for the linking of the model file is not in the
address@hidden file but
+should be provided in the user @file{Makefile} for more flexibility.
+The default rule
+uses the variables @code{miniker_user_objects} for additional object files
+and @code{LDADD} for additionnal linking flags and files, those
+variables are there to be changed by the user.
+
+The object files required by the Miniker code are in the make variable
address@hidden, this variable is also used.
+The value of the variables @code{FC}
+for the Fortran compiler, @code{FFLAGS} for the Fortran compiler
+flags and @code{LDFLAGS} for the linker flags should be set to right
+values; @code{LIBS} should also be right and hold the link flags and link
+files required to compile the Miniker model. These variables are
+set by by @command{./configure} during configuration (@pxref{Configuration})
+and used in the default rule:
+
address@hidden
+$(model_file): $(miniker_user_objects) $(miniker_principal_objects)
+ $(FC) $(FFLAGS) $(LDFLAGS) $^ $(LDADD) $(LIBS) -o $@
address@hidden verbatim
+
+In case this isn't right it may be freely changed. You should certainly
+refer to the @ref{Top,,Top,make,GNU Make Manual} manual to understand what
+that rule exactly means and make your own.
+
+
address@hidden Concepts index
address@hidden Concepts index
+
address@hidden cp
+
address@hidden Variables macros and functions index
address@hidden Variables, macros and functions index
+
address@hidden vr
+
address@hidden Installation
address@hidden Installation
+
address@hidden
+* Programming environments::
+* Common requisites::
+* Miniker with cmz::
+* Miniker with make::
address@hidden menu
+
address@hidden Programming environments
address@hidden Programming environments
address@hidden Programming environments
+
+Miniker is not a traditionnal software in that it isn't a library
+or an interpreter but rather a set of source and macro file that
+combines with the user model code and enable
+to build a binary program corresponding with the model. It
+requires a build environment with a preprocessor, a compiler
+and facilities that automate these steps.
+
+Two different environment are proposed. One use
address@hidden (@url{http://wwwcmz.web.cern.ch/@/wwwcmz/index.html}),
+while the other is based on @command{make}. Other libraries
+are needed, the CERN Program Library (cernlib) and lapack.
+
address@hidden Common requisites
address@hidden Common requisites
+
address@hidden cernlib
address@hidden lapack
+
+Whatever method is used a fortran 77 compiler is required. The compilers
+that have been used so far are g77, gfortran and the sun solaris compiler.
+
+When usng CMZ, the CERN Program Library, available at
address@hidden://wwwasd.web.cern.ch/@/wwwasd/cernlib/}, has to be installed.
+With make, internal source files copied from the cernlib may be used instead
+but then some examples won't be available, since they rely on some
+mathematical functions provided by the CERN library.
+On windows, in case you want to use the compiler from the GNU compiler
+collection with cygwin or MINGW/MSYS you can use the binaries provided at
address@hidden://zyao.home.cern.ch/@/zyao/cernlib.html}.
+On Mac OS X, the cernlib provided by fink (package @code{cernlib-devel})
+can be used.
+
+You should also have LAPACK, available at
@url{http://www.netlib.org/@/lapack/}.
+LAPACK can also be installed as part of the CERN Library or as part of
+the @uref{ATLAS,http://math-atlas.sourceforge.net/} implementation.
+On most linux distributions a lapack package is available.
+On Mac OS X, the ATLAS implementation provided by fink or the frameworks
+from Xcode can be used.
+
+
address@hidden Miniker with cmz
address@hidden Miniker with cmz
+
address@hidden @file{mini_ker.cmz}
address@hidden @file{selseq.kumac}
+
+First of all you have to get the cmz file @file{mini_ker.cmz} and put it
+in a directory. In that same directory you should create a directory for
+each of your models. In the model directory you should copy the file
address@hidden available with Miniker, and create your own cmz
+file for your model, called for example @file{mymodel.cmz}. You should also
+have installed the kumac macro files
+handling mortan compilation, the associated shell scripts and the mortran
+preprocessor.
+
address@hidden Miniker with make
address@hidden Miniker with make
+
address@hidden
+* Additional requirements::
+* Configuration::
+* Installation with make::
address@hidden menu
+
address@hidden Additional requirements
address@hidden Additional requirements for Miniker with make
+
address@hidden @command{mortran}, with make
address@hidden requirements, with make
+
+The package has been tested with GNU @command{make} and solaris
address@hidden
+
+Suitable preprocessors should also be installed. Two preprocessors are
+required, one that preprocess the cmz directives, and a mortran
+preprocessor. A cmz directives processor written in @command{perl},
+is distributed in the @command{car2txt} package available at
address@hidden://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}.
A @command{mortran}
+package with a command able to preprocess a mortran file given on
+the command line with a syntax similar with the @command{cpp} command line
+syntax is also required.
+Such a mortran is available at
@url{http://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}.
+
address@hidden All the @command{make} commands are not suitable, for example
the distribution
address@hidden doesn't work with solaris @command{make}. GNU @command{make}
works, however,
address@hidden and should be available on most platforms, often called
@command{gmake}.
+
+
address@hidden Configuration
address@hidden Configuration
+
address@hidden configuration of source
+
+The package is available at
@url{http://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}.
It is
+available as a compresssed tar archive. On UNIX, with GNU @command{tar} it
+may be unpacked using
+
address@hidden
+$ tar xzvf mini_ker-4.2.tar.gz
address@hidden example
+
+The detection of the compiler, the preprocessors (car2txt and mortran),
+and the libraries are performed by the configure script. This script
+sets the
+apropriate variables in makefiles. It can be run with:
+
address@hidden
+$ cd mini_ker-4.2
+$ ./configure
address@hidden example
+
+If the output of @command{./configure} doesn't show any error it means that
+all the components are here. It is possible to give @command{./configure}
+switches and also specify environment variables (see also
address@hidden/configure --help}):
+
address@hidden @code
address@hidden --disable-cernlib
+Use the internal cernlib source files, even if a cernlib is detected.
address@hidden --with-static-cernlib
+This command line switch forces a static linking with the cernlib (or a
dynamic linking
+if set to no).
address@hidden --with-cernlib
+This command line switch can be used to specify the cernlib location
+(if not detected or you want to use a specific cernlib).
address@hidden --with-blas
address@hidden --with-lapack
+With this command switch, you can specify the location of the blas and lapack
+libraries.
+
+For example, on mac OS X this can be used to specify the blas and lapack from
+the Apple frameworks:
+
address@hidden
+./configure \
+--with-blas=/System/Library/Frameworks/vecLib.framework/versions/A/vecLib \
+--with-lapack=/System/Library/Frameworks/vecLib.framework/versions/A/vecLib
address@hidden example
+
address@hidden F77
address@hidden FC
address@hidden FFLAGS
address@hidden LDFLAGS
+Classical compiler, compiler flags and linker flags.
address@hidden MORTRAN
+This environment variable holds the mortran preprocessor command
+(default is @command{mortran}).
address@hidden MTNFLAGS
+This environment variable holds command line arguments for the mortran
+preprocessor. It is empty in the default case.
address@hidden MTN
+This environment variable may be used to specify the mortran executable
+name and/or path, it should be used by the @command{mortran} commmand.
+(default is empty, which leads to a mortran executable called @command{mtn}).
address@hidden MTNDEPEND
+This environment variable may be used to specify the mortran dependencies
+checker executable. It should be used by the @command{mortran} commmand.
+(default is empty, which leads to a mortran dependencies checker
+called @command{mtndepend}).
address@hidden table
+
+After a proper configuration, if @command{make} is run then the example
+models should be build. You have to perform the configuration only once.
+
address@hidden Installation with make
address@hidden Installation with make
address@hidden installation with make
+
+Miniker can be installed by running
address@hidden
+make install
address@hidden example
+
+
+It should copy the sources
+and the @file{Makefile.miniker} file in
+a @file{mini_ker} directory in the @code{$(includedir)} directory, and
+copy the templates in @file{$(datadir)/mini_ker}. The default for
address@hidden(includedir)} is @file{/usr/local/include} and the default for
address@hidden(datadir)} is @file{/usr/local/share}, these defaults may be
+changed by @command{./configure} switches @samp{--prefix},
address@hidden and @samp{--datadir}. See @command{./configure --help}
+and the @file{INSTALL} file for more informations. The helper script
address@hidden should also be installed.
+
+
+
+The installation is not required to use comfortably Miniker. Indeed
+the only thing that changes with the sources and the @file{Makefile.miniker}
+directory location is the @code{miniker_dir} variable in a
+project @code{Makefile}.
+
+
address@hidden Cmz directives reference
address@hidden Cmz directives reference
+
+The cmz directives are described together with the other
+features of cmz in the cmz manual at
address@hidden://wwwcmz.web.cern.ch/wwwcmz/}, the important ones are
+nevertheless recalled here,
+especially for those that use make and don't need the whole
+features of cmz.
+
+After the description of the generic features, we turn
+to the cmz directive of interest.
+There are three kinds of cmz directives that are of use
+within Miniker: one kind
+that introduce files, the other for conditionnal compilation and
+the third for sequence inclusion.
+
+
address@hidden
+* Cmz directives general syntax::
+* Conditional expressions::
+* File introduction directives::
+* Conditional directives::
+* File inclusion directive::
+* The self directive::
address@hidden menu
+
address@hidden Cmz directives general syntax
address@hidden Cmz directives general syntax
+
+The cmz directives always begin with a @samp{+} in the first column,
+optionnaly followed by any number of @samp{_} that may be used for
+indentation, then the directive label, case insensitive, followed
+by the directive arguments separated by @samp{,}. The arguments
+are also case insensitive.
+Optional spaces may be around directive arguments.
+An optionnal @samp{.} ends the directive
+arguments and begin a comment, everything that follows that @samp{.} is
+ignored.
+
address@hidden Conditional expressions
address@hidden Conditional expressions
+
+A directive argument common to all the directives is the conditionnal
+expression. A conditionnal expression may be true or false, it is a
+combination of select flags. the select flags are combined with
+logical operators. A
+select flag itself is true if it was selected. A select flag @var{selflag}
+is selected by using the @code{sel @var{selflag}} instruction in cmz. It is
+selected by passing the @code{-D @var{selflag}} command line switch to
+the call of the cmz directives preprocessor when using make.
+
+
+A @samp{-} negates
+the expression that follows. Parenthesis @samp{(} and @samp{)} are used
+for the grouping of subexpressions. @samp{|} and @samp{,} are for the
+boolean or: an expression with a or is true
+if the expression on the left or the expression on the right of the or
+is true.
address@hidden&} is for the boolean and: an expression with an and is true if
+the expression on the left and the expression on the right are true.
+
+The grouping is left to right when there is no parenthesis, with or and
address@hidden&} having the same precedence. Therefore
+
address@hidden
+a&b|c @equiv{} (a&b)|c
+a|b&c @equiv{} (a|b)&c
+a|b&c is not a|(b&c)
+a&b|c is not a&(b|c)
address@hidden example
+
address@hidden File introduction directives
address@hidden File introduction directives
+
+A file (or sequence) introduction directive appears at the beginning
+of the file. There are two different directives, one is @code{DECK}
+for normal files, the other is @code{KEEP} for include files (sequences).
+The first argument is the name of the file. The file name may not be larger
+than 32 characters and is converted to lower case in the general case.
+The optionnal following arguments may be
+of 2 type (and may be mixed, separated by @samp{,}):
+
address@hidden @asis
address@hidden conditional
+A conditionnal is introduced by @code{IF=} followed by a conditionnal
+expression described in
address@hidden expressions}. The
+file is preprocessed if the conditionnal expression is true.
address@hidden language specification
+A language specification is introduced by a @code{T=}. The most
+common languages are @samp{mtn} for the mortran, @samp{ftn} for
+fortran not preprocessed, @samp{f77} for preprocessed fortran,
address@hidden for the c language and @samp{txt} for text files.
+In general the language of the file determines the name of files
+the preprocessed file is extracted to, the comment style and
+the command for inclusions.
address@hidden table
+
+It is a common practice to have wrong language type in @code{KEEP}
+as the language may be determined from the @code{DECK} that include
+them with cmz, or from their file name with make. This is not recommended
+and considered a bad practice.
+
+Such a directive will always appear in cmz, as it is built-in. It
+is recommended to have one when using make too, even though it is not
+required in most cases. Indeed make uses the file name directly
+and finds the language and file type by looking at the file extension.
+make should then pass the language type with a
address@hidden @var{lang}} command
+line switch when calling the cmz directives preprocessor.
+With make, the convention is to have @samp{cm} added before the normal
+file suffix and after the @samp{.}. The table @ref{tab:cmfile_suffix}
+shows the matching between suffixes, file type and file language.
+
+For example, a file beginning with
+
address@hidden
++Deck, subroutine_foo, If=monitor&-simple, T=f77.
address@hidden verbatim
+
+is a main preprocessed fortran file that will only be generated if
address@hidden is selected and @samp{simple} is not selected. The
+file to be preprocessed by make should have the @samp{.cmF} suffix,
+and be called @file{subroutine_foo.cmF}.
+
+A file beginning with
+
address@hidden
++KEEP,inc_common,If=monitor|interface,T=mtn
address@hidden verbatim
+
+is an mortran include file that should be processed only if @samp{monitor}
+or @samp{interface} is selected. The file to be preprocessed by make
+should have the @samp{cmmti} suffix and be called @file{inc_common.cmmti}.
+The resulting file when make is used will be called @file{inc_common.mti}.
+
address@hidden Conditional directives
address@hidden Conditional directives
+
+Conditional directives may be used to conditionnaly skip blocks of
+code. There are 4 conditional directives: @code{if}, @code{elseif},
address@hidden and @code{endif}. @code{+if} begins a conditional directives
+sequence, with argument a conditional expression. If the expression is
+true the block of code following the @code{+if} is output in the
+resulting file, up to another conditional directive, if it is false
+the code block is skipped. If the
+expression is false and the following conditional directive is
address@hidden, the same procedure is followed with the argument of
address@hidden
+which is also a conditionnal expression. More than one @code{+elseif}
+may follow a @code{+if}. If a @code{+if} or @code{+elseif} expression
+is true the following
+code block is output and all
+the following @code{+elseif} code blocks are skipped. If all the @code{+if}
+and @code{+elseif} expressions are false and
+the following coditionnal
+directive is @code{+else} then the block following the
address@hidden is output. If a previous expression was true the
+code block following the @code{+else} is skipped. The last code block
+is closed by @code{+endif}.
+
+Conditionnal directives may be nested, a @code{+if} begins a deeper
+conditionnal sequences directives that is ended by the corresponding
address@hidden
+
+The simplest example is:
+
address@hidden
+ some code;
++IF,monitor
+ code output only if monitor is true;
++ENDIF
address@hidden verbatim
+
+If @samp{monitor} is selected, the @code{+if} block is output, it leads to
+
address@hidden
+ some code;
+ code output only if monitor is true;
address@hidden verbatim
+
+If @samp{monitor} isn't selected the @code{+if} block is skipped, it leads to
+
address@hidden
+ some code;
address@hidden verbatim
+
+An example with @code{+else} may be:
+
address@hidden
++IF,double
+ call dmysub(eta);
++ELSE
+ call smysub(eta);
++ENDIF
address@hidden verbatim
+
+If @samp{double} is selected the code output is @code{call dmysub(eta);},
+if @samp{double} isn't selected the code output is @code{call dmysub(eta);}.
+
+Here is a self explanatory example of use of @code{+elseif}:
+
address@hidden
++IF,monitor
+ code used if monitor is selected;
++ELSEIF,kalman
+ code used if kalman is selected and monitor is not;
++ELSE
+ code used if kalman and monitor are not selected;
++ENDIF
address@hidden verbatim
+
+And last an example of nested conditional directives:
+
address@hidden
++IF,monitor
+ code used if monitor is selected;
++_IF,kalman. deep if
+ code used if monitor and kalman are selected;
++_ELSE. deep else
+ code used if monitor is selected and kalman is not;
++_ENDIF. end the deep conditionnals sequence
++ELSE
+ code used if monitor is not selected;
++_IF,kalman
+ code used if monitor is not selected but kalman is;
++_ELSE
+ code used if monitor and kalman are not selected;
++_ENDIF
+ other code used if monitor is not selected;
++ENDIF
address@hidden verbatim
+
address@hidden File inclusion directive
address@hidden File inclusion directive
+
+The file (sequence) inclusion directive is @code{seq}. The argument of
address@hidden is an include files @samp{,} separated list. The include
+files are @code{Keep} in cmz. The following optional arguments may be
+mixed:
+
address@hidden @asis
address@hidden conditional
+A conditionnal is introduced by @code{IF=} followed by a conditionnal
+expression described in
address@hidden expressions}. The
+directive is ignored if the conditionnal expression is false.
address@hidden T=noinclude
+When this argument is present the text of the sequence will
+always be included in the file where the @code{+seq} appears.
address@hidden table
+
+When there is no @code{T=noinclude} argument, the @code{+seq}
+directive may be replaced with an inclusion command suitable
+for the language of the file being processed, if such
+command has been specified.
+
+For example if we have the following sequence
address@hidden
++KEEP,inc,lang=C
+typedef struct incstr {char* msg};
address@hidden verbatim
+
+And the following code in the file being processed:
+
address@hidden
++DECK,mainf,lang=C
++SEQ,inc
+int main (int argc, char* argv) { exit(0); }
address@hidden verbatim
+
+the processing of @file{mainf} should lead to the file
address@hidden, containing
+an include command for @file{inc}:
+
address@hidden
+#include "inc.h"
+int main (int argc, char* argv) { exit(0); }
address@hidden verbatim
+
+In case the @code{+seq} has the @code{T=noinclude}:
+
address@hidden
++DECK,mainf,lang=C
++SEQ,inc,T=noinclude
+int main (int argc, char* argv) { exit(0); }
address@hidden verbatim
+
+The processing of @file{mainf} should lead to the file @file{mainf.c}
+containing the text of @file{inc}:
+
address@hidden
+typedef struct incstr {char* msg};
+int main (int argc, char* argv) { exit(0); }
address@hidden verbatim
+
address@hidden The self directive
address@hidden The @samp{self} directive
+
+The @code{self} directive is an obsolete directive that may be used for
+conditionnal skipping of code. For a better approach see
address@hidden directives}.
+The optionnal argument of @code{+SELF} is @code{If=} followed by
+a conditionnal expression. If the conditionnal expression is true the
+code following the directive is output, if it is false the code
+is skipped up to any directive (including another @code{+SELF})
+except @code{+seq}.
+
+
address@hidden Copying This Manual
address@hidden Copying This Manual
+
address@hidden
+* GNU Free Documentation License:: License for copying this manual.
address@hidden menu
+
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
+
address@hidden FDL, GNU Free Documentation License
address@hidden Version 1.1, March 2000
+
address@hidden
+Copyright @copyright{} 2000 Free Software Foundation, Inc.
+59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
address@hidden display
+
address@hidden 0
address@hidden
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+written document @dfn{free} in the sense of freedom: to assure everyone
+the effective freedom to copy and redistribute it, with or without
+modifying it, either commercially or noncommercially. Secondarily,
+this License preserves for the author and publisher a way to get
+credit for their work, while not being considered responsible for
+modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
address@hidden
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work that contains a
+notice placed by the copyright holder saying it can be distributed
+under the terms of this License. The ``Document'', below, refers to any
+such manual or work. Any member of the public is a licensee, and is
+addressed as ``you''.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (For example, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, whose contents can be viewed and edited directly and
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is
+not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
address@hidden without markup, Texinfo input format, address@hidden input
format,
address@hidden or @acronym{XML} using a publicly available
address@hidden, and standard-conforming simple @acronym{HTML} designed
+for human modification. Opaque formats include PostScript,
address@hidden, proprietary formats that can be read and edited only by
+proprietary word processors, @acronym{SGML} or @acronym{XML} for which
+the @acronym{DTD} and/or processing tools are not generally available,
+and the machine-generated @acronym{HTML} produced by some word
+processors for output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
address@hidden
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
address@hidden
+COPYING IN QUANTITY
+
+If you publish printed copies of the Document numbering more than 100,
+and the Document's license notice requires Cover Texts, you must enclose
+the copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols. If you use the latter
+option, you must take reasonably prudent steps, when you begin
+distribution of Opaque copies in quantity, to ensure that this
+Transparent copy will remain thus accessible at the stated location
+until at least one year after the last time you distribute an Opaque
+copy (directly or through your agents or retailers) of that edition to
+the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
address@hidden
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
address@hidden A
address@hidden
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
address@hidden
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has less than five).
+
address@hidden
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
address@hidden
+Preserve all the copyright notices of the Document.
+
address@hidden
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
address@hidden
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
address@hidden
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
address@hidden
+Include an unaltered copy of this License.
+
address@hidden
+Preserve the section entitled ``History'', and its title, and add to
+it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
address@hidden
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
address@hidden
+In any section entitled ``Acknowledgments'' or ``Dedications'',
+preserve the section's title, and preserve in the section all the
+substance and tone of each of the contributor acknowledgments
+and/or dedications given therein.
+
address@hidden
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
address@hidden
+Delete any section entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
address@hidden
+Do not retitle any existing section as ``Endorsements''
+or to conflict in title with any Invariant Section.
address@hidden enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
address@hidden
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections entitled ``History''
+in the various original documents, forming one section entitled
+``History''; likewise combine any sections entitled ``Acknowledgments'',
+and any sections entitled ``Dedications''. You must delete all sections
+entitled ``Endorsements.''
+
address@hidden
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
address@hidden
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, does not as a whole count as a Modified Version
+of the Document, provided no compilation copyright is claimed for the
+compilation. Such a compilation is called an ``aggregate'', and this
+License does not apply to the other self-contained works thus compiled
+with the Document, on account of their being thus compiled, if they
+are not themselves derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one quarter
+of the entire aggregate, the Document's Cover Texts may be placed on
+covers that surround only the Document within the aggregate.
+Otherwise they must appear on covers around the whole aggregate.
+
address@hidden
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License provided that you also include the
+original English version of this License. In case of a disagreement
+between the translation and the original English version of this
+License, the original English version will prevail.
+
address@hidden
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
address@hidden
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
address@hidden://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
address@hidden enumerate
+
address@hidden
address@hidden ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
address@hidden
address@hidden
+ Copyright (C) @var{year} @var{your name}.
+ 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 the Invariant Sections being @var{list their titles}, with the
+ Front-Cover Texts being @var{list}, and with the Back-Cover Texts being
@var{list}.
+ A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
address@hidden group
address@hidden smallexample
+
+If you have no Invariant Sections, write ``with no Invariant Sections''
+instead of saying which ones are invariant. If you have no
+Front-Cover Texts, write ``no Front-Cover Texts'' instead of
+``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
address@hidden Local Variables:
address@hidden ispell-local-pdict: "ispell-dict"
address@hidden End:
+
+
address@hidden
Index: res_info/texi_texinfo/texinfo.texi.first
===================================================================
RCS file: res_info/texi_texinfo/texinfo.texi.first
diff -N res_info/texi_texinfo/texinfo.texi.first
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ res_info/texi_texinfo/texinfo.texi.first 2 Aug 2009 13:11:05 -0000
1.1
@@ -0,0 +1,18107 @@
+\input texinfo.tex @c -*-texinfo-*-
address@hidden Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $
address@hidden Ordinarily Texinfo files have the extension .texi. But
texinfo.texi
address@hidden clashes with texinfo.tex on 8.3 filesystems, so we use
texinfo.txi.
+
address@hidden Everything between the start/end of header lines will be passed
by
address@hidden Emacs's {texinfo,makeinfo}-format region commands. See the
`start of
address@hidden header' node for more info.
address@hidden %**start of header
+
address@hidden makeinfo and texinfo.tex ignore all text before @setfilename.
address@hidden
address@hidden Ordinarily the setfilename argument ends with .info. But
address@hidden texinfo.info-13 is too long for 14-character filesystems.
address@hidden texinfo
+
address@hidden Automake automatically updates version.texi to @set VERSION and
address@hidden @set UPDATED to appropriate values.
address@hidden UPDATED 28 March 2002
address@hidden UPDATED-MONTH March 2002
address@hidden EDITION 4.2
address@hidden VERSION 4.2
address@hidden GNU Texinfo 4.2
+
address@hidden Define a new index for options.
address@hidden op
address@hidden Put everything except function (command, in this case) names in
one
address@hidden index (arbitrarily chosen to be the concept index).
address@hidden op cp
address@hidden vr cp
address@hidden pg cp
+
address@hidden separate
address@hidden 2
address@hidden finalout
+
address@hidden %**end of header
+
+
address@hidden Texinfo documentation system
address@hidden
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. Update info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
+* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
+* makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source.
address@hidden direntry
+
address@hidden Before release, run C-u C-c C-u C-a (texinfo-all-menus-update
with a
address@hidden prefix arg). This updates the node pointers, which texinfmt.el
needs.
+
address@hidden Set smallbook if printing in smallbook format so the example of
the
address@hidden smallbook font is actually written using smallbook; in bigbook,
a kludge
address@hidden is used for TeX output. Do this through the -t option to
texi2dvi,
address@hidden so this same source can be used for other paper sizes as well.
address@hidden smallbook
address@hidden set smallbook
address@hidden @@clear smallbook
+
address@hidden If you like blank pages, add through texi2dvi -t.
address@hidden setchapternewpage odd
+
address@hidden Currently undocumented command, 5 December 1993:
address@hidden nwnode (Same as node, but no warnings; for `makeinfo'.)
+
+
address@hidden Texinfo
+
+
+
address@hidden
address@hidden
+
+
address@hidden Top
address@hidden Texinfo
+
+This manual is for GNU Texinfo (version 4.2, 28 March 2002),
+a documentation system that can produce both online information and a
+printed manual from a single source.
+
+Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02
+Free Software Foundation, Inc.
+
address@hidden
+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.''
address@hidden quotation
+
+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.
+
+
address@hidden
+* Copying Conditions:: Your rights.
+* Overview:: Texinfo in brief.
+* Texinfo Mode:: How to use Texinfo mode.
+* Beginning a File:: What is at the beginning of a Texinfo file?
+* Ending a File:: What is at the end of a Texinfo file?
+* Structuring:: How to create chapters, sections, subsections,
+ appendices, and other parts.
+* Nodes:: How to write nodes.
+* Menus:: How to write menus.
+* Cross References:: How to write cross references.
+* Marking Text:: How to mark words and phrases as code,
+ keyboard input, meta-syntactic
+ variables, and the like.
+* Quotations and Examples:: How to write quotations, examples, etc.
+* Lists and Tables:: How to write lists and tables.
+* Indices:: How to create indices.
+* Insertions:: How to insert @@-signs, braces, etc.
+* Breaks:: How to force and prevent line and page breaks.
+* Definition Commands:: How to describe functions and the like
+ in a uniform manner.
+* Conditionals:: How to specify text for either @TeX{} or Info.
+* Internationalization::
+* Defining New Texinfo Commands::
+* Hardcopy:: How to convert a Texinfo file to a file
+ for printing and how to print that file.
+* Creating and Installing Info Files::
+* Command List:: All the Texinfo @@-commands.
+* Tips:: Hints on how to write a Texinfo document.
+* Sample Texinfo Files:: Complete examples, including full texts.
+* Include Files:: How to incorporate other Texinfo files.
+* Headings:: How to write page headings and footings.
+* Catching Mistakes:: How to find formatting mistakes.
+* Refilling Paragraphs:: All about paragraph refilling.
+* Command Syntax:: A description of @@-Command syntax.
+* Obtaining TeX:: How to Obtain @TeX{}.
+* Copying This Manual:: The GNU Free Documentation License.
+* Command and Variable Index:: A menu containing commands and variables.
+* Concept Index:: A menu covering many topics.
+
address@hidden
+ --- The Detailed Node Listing ---
+
+Overview of Texinfo
+
+* Reporting Bugs:: Submitting effective bug reports.
+* Using Texinfo:: Create printed or online output.
+* Info Files:: What is an Info file?
+* Printed Books:: Characteristics of a printed book or manual.
+* Formatting Commands:: @@-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.
+* Six Parts:: Usually, a Texinfo file has six parts.
+* Short Sample:: A short sample Texinfo file.
+* History:: Acknowledgements, contributors and genesis.
+
+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.
+
+Beginning a Texinfo File
+
+* Sample Beginning:: A sample beginning for a Texinfo file.
+* Texinfo File Header::
+* Document Permissions::
+* Titlepage & Copyright Page:: Creating the title and copyright pages.
+* The Top Node:: Creating the `Top' node and master menu.
+* Global Document Commands::
+* Software Copying Permissions:: Ensure that you and others continue to
+ have the right to use and share software.
+
+Texinfo File Header
+
+* First Line:: The first line of a Texinfo file.
+* Start of Header:: Formatting a region requires this.
+* setfilename:: Tell Info the name of the Info file.
+* settitle:: Create a title for the printed work.
+* End of Header:: Formatting a region requires this.
+
+Document Permissions
+
+* copying:: Declare the document's copying permissions.
+* insertcopying:: Where to insert the permissions.
+
+Title and Copyright Pages
+
+* titlepage:: Create a title for the printed document.
+* titlefont center sp:: The @code{@@titlefont}, @code{@@center},
+ and @code{@@sp} commands.
+* title subtitle author:: The @code{@@title}, @code{@@subtitle},
+ and @code{@@author} commands.
+* Copyright:: How to write the copyright notice and
+ include copying permissions.
+* end titlepage:: Turn on page headings after the title and
+ copyright pages.
+* headings on off:: An option for turning headings on and off
+ and double or single sided printing.
+
+The `Top' Node and Master Menu
+
+* Top Node Example::
+* Master Menu Parts::
+
+Global Document Commands
+
+* documentdescription:: Document summary for the HTML output.
+* setchapternewpage:: Start chapters on right-hand pages.
+* paragraphindent:: Specify paragraph indentation.
+* exampleindent:: Specify environment indentation.
+
+Ending a Texinfo File
+
+* Printing Indices & Menus:: How to print an index in hardcopy and
+ generate index menus in Info.
+* Contents:: How to create a table of contents.
+* File End:: How to mark the end of a file.
+
+Chapter Structuring
+
+* Tree Structuring:: A manual is like an upside down tree @dots{}
+* Structuring Command Types:: How to divide a manual into parts.
+* makeinfo top:: The @code{@@top} command, part of the `Top'
node.
+* chapter::
+* unnumbered & appendix::
+* majorheading & chapheading::
+* section::
+* unnumberedsec appendixsec heading::
+* subsection::
+* unnumberedsubsec appendixsubsec subheading::
+* subsubsection:: Commands for the lowest level sections.
+* Raise/lower sections:: How to change commands' hierarchical level.
+
+Nodes
+
+* Two Paths:: Different commands to structure
+ Info output and printed output.
+* Node Menu Illustration:: A diagram, and sample nodes and menus.
+* node:: Creating nodes, in detail.
+* makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
+* anchor:: Defining arbitrary cross-reference targets.
+
+The @code{@@node} Command
+
+* Node Names:: How to choose node and pointer names.
+* Writing a Node:: How to write an @code{@@node} line.
+* Node Line Tips:: Keep names short.
+* Node Line Requirements:: Keep names unique, without @@-commands.
+* First Node:: How to write a `Top' node.
+* makeinfo top command:: How to use the @code{@@top} command.
+
+Menus
+
+* Menu Location:: Put a menu in a short node.
+* Writing a Menu:: What is a menu?
+* Menu Parts:: A menu entry has three parts.
+* Less Cluttered Menu Entry:: Two part menu entry.
+* Menu Example:: Two and three part menu entries.
+* Other Info Files:: How to refer to a different Info file.
+
+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.
+* xref:: Begin a reference with `See' @dots{}
+* Top Node Naming:: How to refer to the beginning of another file.
+* ref:: A reference for the last part of a sentence.
+* pxref:: How to write a parenthetical cross reference.
+* inforef:: How to refer to an Info-only file.
+* uref:: How to refer to a uniform resource locator.
+
address@hidden@@xref}
+
+* Reference Syntax:: What a reference looks like and requires.
+* 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.
+
+Marking 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:: Indicating program code.
+* kbd:: Showing keyboard input.
+* key:: Specifying keys.
+* samp:: A literal sequence of characters.
+* verb:: A verbatim sequence of characters.
+* var:: Indicating metasyntactic variables.
+* env:: Indicating environment variables.
+* file:: Indicating file names.
+* command:: Indicating command names.
+* option:: Indicating option names.
+* dfn:: Specifying definitions.
+* cite:: Referring to books not in the Info system.
+* acronym:: Indicating acronyms.
+* url:: Indicating a World Wide Web reference.
+* email:: Indicating an electronic mail address.
+
+Emphasizing Text
+
+* 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.
+* quotation:: Writing a quotation.
+* example:: Writing an example in a fixed-width font.
+* verbatim:: Writing a verbatim example.
+* verbatiminclude:: Including a file verbatim.
+* lisp:: Illustrating Lisp code.
+* small:: Forms for @code{@@smallbook}.
+* display:: Writing an example in the current font.
+* format:: Writing an example without narrowed margins.
+* exdent:: Undo indentation on a line.
+* flushleft & flushright:: Pushing text flush left or flush right.
+* noindent:: Preventing paragraph indentation.
+* cartouche:: Drawing rounded rectangles around examples.
+
+Lists and Tables
+
+* Introducing Lists:: Texinfo formats lists for you.
+* itemize:: How to construct a simple list.
+* 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
+
+* table:: How to construct a two-column table.
+* ftable vtable:: Automatic indexing for two-column tables.
+* itemx:: How to put more entries in the first column.
+
+Multi-column Tables
+
+* Multitable Column Widths:: Defining multitable column widths.
+* Multitable Rows:: Defining multitable rows, with examples.
+
+Indices
+
+* Index Entries:: Choose different words for index entries.
+* Predefined Indices:: Use different indices for different kinds
+ of entry.
+* Indexing Commands:: How to make an index entry.
+* Combining Indices:: How to combine indices.
+* New Indices:: How to define your own indices.
+
+Combining Indices
+
+* syncodeindex:: How to merge two indices, using @code{@@code}
+ font for the merged-from index.
+* synindex:: How to merge two indices, using the
+ default font of the merged-to index.
+
+Special Insertions
+
+* Braces Atsigns:: How to insert braces, @samp{@@}.
+* Inserting Space:: How to insert the right amount of space
+ within a sentence.
+* Inserting Accents:: How to insert accents and special characters.
+* Dots Bullets:: How to insert dots and bullets.
+* TeX and copyright:: How to insert the @TeX{} logo
+ and the copyright symbol.
+* pounds:: How to insert the pounds currency symbol.
+* minus:: How to insert a minus sign.
+* math:: How to format a mathematical expression.
+* Glyphs:: How to indicate results of evaluation,
+ expansion of macros, errors, etc.
+* Footnotes:: How to include footnotes.
+* Images:: How to include graphics.
+
+Inserting @@ and Braces
+
+* Inserting An Atsign:: How to insert @samp{@@}.
+* Inserting Braces:: How to insert @address@hidden and
@address@hidden
+
+Inserting Space
+
+* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
+* Ending a Sentence:: Sometimes it does.
+* Multiple Spaces:: Inserting multiple spaces.
+* dmn:: How to format a dimension.
+
+Inserting Ellipsis and Bullets
+
+* dots:: How to insert dots @dots{}
+* bullet:: How to insert a bullet.
+
+Inserting @TeX{} and the Copyright Symbol
+
+* tex:: How to insert the @TeX{} logo.
+* copyright symbol:: How to use @code{@@address@hidden@}.
+
+Glyphs for Examples
+
+* Glyphs Summary::
+* result:: How to show the result of expression.
+* expansion:: How to indicate an expansion.
+* Print Glyph:: How to indicate printed output.
+* Error Glyph:: How to indicate an error message.
+* Equivalence:: How to indicate equivalence.
+* Point Glyph:: How to indicate the location of point.
+
+Glyphs Summary
+
+* result::
+* expansion::
+* Print Glyph::
+* Error Glyph::
+* Equivalence::
+* Point Glyph::
+
+Footnotes
+
+* Footnote Commands:: How to write a footnote in Texinfo.
+* Footnote Styles:: Controlling how footnotes appear in Info.
+
+Making and Preventing Breaks
+
+* Break Commands:: Cause and prevent splits.
+* Line Breaks:: How to force a single line to use two lines.
+* - and hyphenation:: How to tell @TeX{} about hyphenation points.
+* w:: How to prevent unwanted line breaks.
+* sp:: How to insert blank lines.
+* page:: How to force the start of a new page.
+* group:: How to prevent unwanted page breaks.
+* need:: Another way to prevent unwanted page breaks.
+
+Definition Commands
+
+* Def Cmd Template:: How to structure a description using a
+ definition command.
+* Optional Arguments:: How to handle optional and repeated arguments.
+* deffnx:: How to group two or more `first' lines.
+* Def Cmds in Detail:: All the definition commands.
+* Def Cmd Conventions:: Conventions for writing definitions.
+* Sample Function Definition::
+
+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.
+* Abstract Objects:: Commands for object-oriented programming.
+* Data Types:: The definition command for data types.
+
+Conditionally Visible Text
+
+* Conditional Commands:: Specifying text for HTML, Info, or @TeX{}.
+* Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}.
+* Raw Formatter Commands:: Using raw @TeX{} or HTML commands.
+* set clear value:: Designating which text to format (for
+ all output formats); and how to set a
+ flag to a string that you can insert.
+
address@hidden@@set}, @code{@@clear}, and @code{@@value}
+
+* set value:: Expand a flag variable to a string.
+* ifset ifclear:: Format a region if a flag is set.
+* value Example:: An easy way to update edition information.
+
+Internationalization
+
+* documentlanguage:: Declaring the current language.
+* documentencoding:: Declaring the input encoding.
+
+Defining New Texinfo Commands
+
+* Defining Macros:: Defining and undefining new commands.
+* Invoking Macros:: Using a macro, once you've defined it.
+* Macro Details:: Beyond basic macro usage.
+* alias:: Command aliases.
+* definfoenclose:: Customized highlighting.
+
+Formatting and Printing Hardcopy
+
+* Use TeX:: Use @TeX{} to format for hardcopy.
+* Format with tex/texindex:: How to format with explicit shell commands.
+* Format with texi2dvi:: A simpler way to format.
+* Print with 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.
+* smallbook:: How to print small format books and manuals.
+* A4 Paper:: How to print on A4 or A5 paper.
+* 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.
+
+Creating and Installing Info Files
+
+* Creating an Info File::
+* Installing an Info File::
+
+Creating an Info File
+
+* makeinfo advantages:: @code{makeinfo} provides better error checking.
+* Invoking makeinfo:: How to run @code{makeinfo} from a shell.
+* makeinfo options:: Specify fill-column and other options.
+* Pointer Validation:: How to check that pointers point somewhere.
+* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs.
+* 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.
+* makeinfo html:: Generating HTML output.
+
+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 install-info:: @code{install-info} options.
+
+Sample Texinfo Files
+
+* Short Sample Texinfo File::
+* GNU Sample Texts::
+
+Include Files
+
+* Using Include Files:: How to use the @code{@@include} command.
+* texinfo-multiple-files-update:: How to create and update nodes and
+ menus when using included files.
+* Include File Requirements:: What @code{texinfo-multiple-files-update}
expects.
+* 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.
+
+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.
+
+Formatting Mistakes
+
+* 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 texinfo-show-structure:: How to use @code{texinfo-show-structure}.
+* Using occur:: How to list all lines containing a pattern.
+* Running Info-Validate:: How to find badly referenced nodes.
+
+Finding Badly Referenced Nodes
+
+* Using 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.
+
+Copying This Manual
+
+* GNU Free Documentation License:: License for copying this manual.
+
address@hidden detailmenu
address@hidden menu
+
address@hidden Reward readers for getting to the end of the menu :).
address@hidden Contributed by Arnold Robbins.
address@hidden
+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
address@hidden quotation
+
+
address@hidden Copying Conditions
address@hidden Texinfo Copying Conditions
address@hidden Copying conditions
address@hidden Conditions for copying Texinfo
+
+The programs currently being distributed that relate to Texinfo include
address@hidden, @code{info}, @code{texindex}, and @file{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. This manual specifically is covered by
+the GNU Free Documentation License (@pxref{GNU Free Documentation
+License}).
+
+
address@hidden Overview
address@hidden Overview of Texinfo
address@hidden Overview of Texinfo
address@hidden Texinfo overview
+
address@hidden@footnote{The first syllable of ``Texinfo'' is pronounced
+like ``speck'', not ``hex''. This odd pronunciation is derived from,
+but is not the same as, the pronunciation of @TeX{}. In the word
address@hidden, the @samp{X} is actually the Greek letter ``chi'' rather than
+the English letter ``ex''. Pronounce @TeX{} as if the @samp{X} were the
+last sound in the name `Bach'; but pronounce Texinfo as if the @samp{x}
+were a `k'. Spell ``Texinfo'' with a capital ``T'' and the other
+letters in lower case.} is a documentation system that uses a single
+source file to produce both online information and printed output. This
+means that instead of writing two different documents, one for the
+online information and the other for a printed work, you need write only
+one document. Therefore, when the work is revised, you need revise only
+that one document.
+
address@hidden
+* Reporting Bugs:: Submitting effective bug reports.
+* Using Texinfo:: Create printed or online output.
+* Info Files:: What is an Info file?
+* Printed Books:: Characteristics of a printed book or manual.
+* Formatting Commands:: @@-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.
+* Six Parts:: Usually, a Texinfo file has six parts.
+* Short Sample:: A short sample Texinfo file.
+* History:: Acknowledgements, contributors and genesis.
address@hidden menu
+
+
address@hidden Reporting Bugs
address@hidden Reporting Bugs
+
address@hidden Bugs, reporting
address@hidden Suggestions for Texinfo, making
address@hidden Reporting bugs
+We welcome bug reports and suggestions for any aspect of the Texinfo system,
+programs, documentation, installation, anything. Please email them to
address@hidden@@gnu.org}. You can get the latest version of Texinfo
+from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide.
+
address@hidden Checklist for bug reports
+For bug reports, please include enough information for the maintainers
+to reproduce the problem. Generally speaking, that means:
+
address@hidden @bullet
address@hidden the version number of Texinfo and the program(s) or manual(s)
involved.
address@hidden hardware and operating system names and versions.
address@hidden the contents of any input files necessary to reproduce the bug.
address@hidden a description of the problem and samples of any erroneous output.
address@hidden any unusual options you gave to @command{configure}.
address@hidden anything else that you think would be helpful.
address@hidden 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.
+
address@hidden Patches, contributing
+Patches are most welcome; if possible, please make them with
address@hidden@w{diff -c}} (@pxref{Top,, Overview, diffutils, Comparing and
+Merging Files}) and include @file{ChangeLog} entries (@pxref{Change
+Log,,, emacs, The GNU Emacs Manual}).
+
+When sending patches, if possible please do not encode or split them in
+any way; it's much easier to deal with one plain text message, however
+large, than many small ones. @uref{ftp://ftp.gnu.org/gnu/sharutils/,
+GNU shar} is a convenient way of packaging multiple and/or binary files
+for email.
+
+
address@hidden Using Texinfo
address@hidden Using Texinfo
+
address@hidden Using Texinfo in general
address@hidden Texinfo, introduction to
address@hidden Introduction to Texinfo
+
+Using Texinfo, you can create a printed document with the normal
+features of a book, including chapters, sections, cross references, and
+indices. From the same Texinfo source file, you can create a
+menu-driven, online Info file with nodes, menus, cross references, and
+indices. You can also create from that same source file an HTML output
+file suitable for use with a web browser, or an XML file. @cite{The GNU
+Emacs Manual} is a good example of a Texinfo file, as is this manual.
+
+To make a printed document, you process a Texinfo source file with the
address@hidden typesetting program (but the Texinfo language is very different
+and much stricter than @TeX{}'s usual language, plain @TeX{}). This
+creates a DVI file that you can typeset and print as a book or report
+(@pxref{Hardcopy}).
+
address@hidden makeinfo
+To output an Info file, process your Texinfo source with the
address@hidden utility or Emacs's @code{texinfo-format-buffer} command.
+You can install the result in your Info tree (@pxref{Installing an Info
+File}).
+
+To output an HTML file, run @code{makeinfo --html} on your Texinfo
+source. You can (for example) install the result on your web site.
+
address@hidden Docbook, converting to Texinfo
address@hidden Conversion, from Docbook to Texinfo
+To output an XML file, run @code{makeinfo --xml} on your Texinfo source.
+To output DocBook (a particular form of XML), run @code{makeinfo
+--docbook}. If you want to convert from Docbook @emph{to} Texinfo,
+please see @uref{http://docbook2X.sourceforge.net/}.
+
address@hidden Output formats, supporting more
address@hidden SGML-tools output format
+If you are a programmer and would like to contribute to the GNU project
+by implementing additional output formats for Texinfo, that would be
+excellent. But please do not write a separate translator texi2foo for
+your favorite format foo! That is the hard way to do the job, and makes
+extra work in subsequent maintenance, since the Texinfo language is
+continually being enhanced and updated. Instead, the best approach is
+modify @code{makeinfo} to generate the new format, as it does now for
+Info, plain text, HTML, XML, and DocBook.
+
address@hidden works with virtually all printers; Info works with virtually all
+computer terminals; the HTML output works with virtually all web
+browsers. Thus Texinfo can be used by almost any computer user.
+
address@hidden Source file
+A Texinfo source file is a plain @sc{ascii} file containing text and
address@hidden@@-commands} (words preceded by an @samp{@@}) that tell the
+typesetting and formatting programs what to do. You may 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}.)
+
+Before writing a Texinfo source file, you should learn about nodes,
+menus, cross references, and the rest, for example by reading this
+manual.
+
+You can use Texinfo to create both online help and printed manuals;
+moreover, Texinfo is freely redistributable. For these reasons, Texinfo
+is the official documentation format of the GNU project. More
+information is available at the @uref{http://www.gnu.org/doc/, GNU
+documentation web page}.
+
address@hidden Man page output, not supported
+From time to time, proposals are made to generate traditional Unix man
+pages from Texinfo source. This is not likely to ever be supported,
+because man pages have a very strict conventional format. Merely
+enhancing @command{makeinfo} to output troff format would be
+insufficient. Generating a good man page therefore requires a
+completely different source than the typical Texinfo applications of
+writing a good user tutorial or a good reference manual. This makes
+generating man pages incompatible with the Texinfo design goal of not
+having to document the same information in different ways for different
+output formats. You might as well just write the man page directly.
+
address@hidden help2man
address@hidden O'Dea, Brendan
+Man pages still have their place, and if you wish to support them, the
+program @command{help2man} may be useful; it generates a traditional man
+page from the @samp{--help} output of a program. In fact, this is
+currently used to generate man pages for the Texinfo programs
+themselves. It is GNU software written by Brendan O'Dea, available from
address@hidden://ftp.gnu.org/gnu/help2man/}.
+
+
address@hidden Info Files
address@hidden Info files
address@hidden Info files
+
+An Info file is a Texinfo file formatted so that the Info documentation
+reading program can operate on it. (@code{makeinfo}
+and @code{texinfo-format-buffer} are two commands that convert a Texinfo file
+into an Info file.)
+
+Info files are divided into pieces called @dfn{nodes}, each of which
+contains the discussion of one topic. Each node has a name, and
+contains both text for the user to read and pointers to other nodes,
+which are identified by their names. The Info program displays one node
+at a time, and provides commands with which the user can move to other
+related nodes.
+
address@hidden, info, info}, for more information about using Info.
+
+Each node of an Info file may have any number of child nodes that
+describe subtopics of the node's topic. The names of child
+nodes are listed in a @dfn{menu} within the parent node; this
+allows you to use certain Info commands to move to one of the child
+nodes. Generally, an Info file is organized like a book. If a node
+is at the logical level of a chapter, its child nodes are at the level
+of sections; likewise, the child nodes of sections are at the level
+of subsections.
+
+All the children of any one parent are linked together in a
+bidirectional chain of `Next' and `Previous' pointers. The `Next'
+pointer provides a link to the next section, and the `Previous' pointer
+provides a link to the previous section. This means that all the nodes
+that are at the level of sections within a chapter are linked together.
+Normally the order in this chain is the same as the order of the
+children in the parent's menu. Each child node records the parent node
+name as its `Up' pointer. The last child has no `Next' pointer, and the
+first child has the parent both as its `Previous' and as its `Up'
address@hidden some documents, the first child has no `Previous'
+pointer. Occasionally, the last child has the node name of the next
+following higher level node as its `Next' pointer.}
+
+The book-like structuring of an Info file into nodes that correspond
+to chapters, sections, and the like is a matter of convention, not a
+requirement. The `Up', `Previous', and `Next' pointers of a node can
+point to any other nodes, and a menu can contain any other nodes.
+Thus, the node structure can be any directed graph. But it is usually
+more comprehensible to follow a structure that corresponds to the
+structure of chapters and sections in a printed book or address@hidden
+
+In addition to menus and to `Next', `Previous', and `Up' pointers, Info
+provides pointers of another kind, called references, that can be
+sprinkled throughout the text. This is usually the best way to
+represent links that do not fit a hierarchical address@hidden
+
+Usually, you will design a document so that its nodes match the
+structure of chapters and sections in the printed output. But
+occasionally there are times when this is not right for the material
+being discussed. Therefore, Texinfo uses separate commands to specify
+the node structure for the Info file and the section structure for the
+printed address@hidden
+
+Generally, you enter an Info file through a node that by convention is
+named `Top'. This node normally contains just a brief summary of the
+file's purpose, and a large menu through which the rest of the file is
+reached. From this node, you can either traverse the file
+systematically by going from node to node, or you can go to a specific
+node listed in the main menu, or you can search the index menus and then
+go directly to the node that has the information you want. Alternatively,
+with the standalone Info program, you can specify specific menu items on
+the command line (@pxref{Top,,, info, Info}).
+
+If you want to read through an Info file in sequence, as if it were a
+printed manual, you can hit @key{SPC} repeatedly, or you get the whole
+file with the advanced Info command @kbd{g *}. (@inforef{Expert,
+Advanced Info commands, info}.)@refill
+
address@hidden !!! dir file may be located in one of many places:
address@hidden /usr/local/emacs/info mentioned in info.c
DEFAULT_INFOPATH
address@hidden /usr/local/lib/emacs/info mentioned in info.c
DEFAULT_INFOPATH
address@hidden /usr/gnu/info mentioned in info.c
DEFAULT_INFOPATH
address@hidden /usr/local/info
address@hidden /usr/local/lib/info
+The @file{dir} file in the @file{info} directory serves as the
+departure point for the whole Info system. From it, you can reach the
+`Top' nodes of each of the documents in a complete Info address@hidden
+
address@hidden URI syntax for Info
+If you wish to refer to an Info file in a URI, you can use the
+(unofficial) syntax exemplified in the following. This works with
+Emacs/W3, for example:
address@hidden
+info:///usr/info/emacs#Dissociated%20Press
+info:emacs#Dissociated%20Press
+info://localhost/usr/info/emacs#Dissociated%20Press
address@hidden example
+
+The @command{info} program itself does not follow URI's of any kind.
+
+
address@hidden Printed Books
address@hidden Printed Books
address@hidden Printed book and manual characteristics
address@hidden Manual characteristics, printed
address@hidden Book characteristics, printed
address@hidden Texinfo printed book characteristics
address@hidden Characteristics, printed books or manuals
+
address@hidden Knuth, Donald
+A Texinfo file can be formatted and typeset as a printed book or manual.
+To do this, you need @TeX{}, a powerful, sophisticated typesetting
+program written by Donald address@hidden can also use the
address@hidden address@hidden, unsupported software}
address@hidden://tug.org/texi2roff.tar.gz, @code{texi2roff}} program if you
+do not have @TeX{}; since Texinfo is designed for use with @TeX{},
address@hidden is not described here. @code{texi2roff} is not part of
+the standard GNU distribution and is not maintained or up-to-date with
+all the Texinfo features described in this manual.}
+
+A Texinfo-based book is similar to any other typeset, printed work: it
+can have a title page, copyright page, table of contents, and preface,
+as well as chapters, numbered or unnumbered sections and subsections,
+page headers, cross references, footnotes, and address@hidden
+
+You can use Texinfo to write a book without ever having the intention
+of converting it into online information. You can use Texinfo for
+writing a printed novel, and even to write a printed memo, although
+this latter application is not recommended since electronic mail is so
+much address@hidden
+
address@hidden is a general purpose typesetting program. Texinfo provides a
+file @file{texinfo.tex} that contains information (definitions or
address@hidden) that @TeX{} uses when it typesets a Texinfo file.
+(@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands
+to @TeX{} commands, which @TeX{} can then process to create the typeset
+document.) @file{texinfo.tex} contains the specifications for printing
+a document. You can get the latest version of @file{texinfo.tex} from
address@hidden://ftp.gnu.org/gnu/texinfo.tex}.
+
+In the United States, documents are most often printed on 8.5 inch by 11
+inch pages (address@hidden by address@hidden); this is the default size. But
+you can also print for 7 inch by 9.25 inch pages (address@hidden by
address@hidden, the @code{@@smallbook} size; or on A4 or A5 size paper
+(@code{@@afourpaper}, @code{@@afivepaper}). (@xref{smallbook, ,
+Printing ``Small'' Books}. Also, see @ref{A4 Paper, ,Printing on A4
+Paper}.)
+
+By changing the parameters in @file{texinfo.tex}, you can change the
+size of the printed document. In addition, you can change the style in
+which the printed document is formatted; for example, you can change the
+sizes and fonts used, the amount of indentation for each paragraph, the
+degree to which words are hyphenated, and the like. By changing the
+specifications, you can make a book look dignified, old and serious, or
+light-hearted, young and cheery.
+
address@hidden is freely distributable. It is written in a superset 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.
+(@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information
+about @TeX{}.)@refill
+
address@hidden is very powerful and has a great many features. Because a
+Texinfo file must be able to present information both on a
+character-only terminal in Info form and in a typeset book, the
+formatting commands that Texinfo supports are necessarily limited.
+
+To get a copy of @TeX{}, see
address@hidden TeX, , How to Obtain @TeX{}}.
+
+
address@hidden Formatting Commands
address@hidden @@-commands
address@hidden @@-commands
address@hidden Formatting commands
+
+In a Texinfo file, the commands that tell @TeX{} how to typeset the
+printed manual and tell @code{makeinfo} and
address@hidden how to create an Info file are preceded
+by @samp{@@}; they are called @dfn{@@-commands}. For example,
address@hidden@@node} is the command to indicate a node and @code{@@chapter}
+is the command to indicate the start of a address@hidden
+
address@hidden
address@hidden note:} All the @@-commands, with the exception of the
address@hidden@@address@hidden@}} command, must be written entirely in lower
case.
address@hidden quotation
+
+The Texinfo @@-commands are a strictly limited set of constructs. The
+strict limits make it possible for Texinfo files to be understood both
+by @TeX{} and by the code that converts them into Info files. You can
+display Info files on any terminal that displays alphabetic and
+numeric characters. Similarly, you can print the output generated by
address@hidden on a wide variety of address@hidden
+
+Depending on what they do or what address@hidden word
address@hidden comes from the way it is used in mathematics and does not
+refer to a dispute between two people; it refers to the information
+presented to the command. According to the @cite{Oxford English
+Dictionary}, the word derives from the Latin for @dfn{to make clear,
+prove}; thus it came to mean `the evidence offered as proof', which is
+to say, `the information offered', which led to its mathematical
+meaning. In its other thread of derivation, the word came to mean `to
+assert in a manner against which others may make counter assertions',
+which led to the meaning of `argument' as a dispute.} they take, you
+need to write @@-commands on lines of their own or as part of
+sentences:
+
address@hidden @bullet
address@hidden
+Write a command such as @code{@@noindent} at the beginning of a line as
+the only text on the line. (@code{@@noindent} prevents the beginning of
+the next line from being indented as the beginning of a
+paragraph.)@refill
+
address@hidden
+Write a command such as @code{@@chapter} at the beginning of a line
+followed by the command's arguments, in this case the chapter title, on
+the rest of the line. (@code{@@chapter} creates chapter titles.)@refill
+
address@hidden
+Write a command such as @code{@@address@hidden@}} wherever you wish but usually
+within a sentence. (@code{@@address@hidden@}} creates dots @dots{})@refill
+
address@hidden
+Write a command such as @code{@@address@hidden@address@hidden wherever you
+wish (but usually within a sentence) with its argument,
address@hidden in this example, between the braces. (@code{@@code}
+marks text as being code.)@refill
+
address@hidden
+Write a command such as @code{@@example} on a line of its own; write the
+body-text on following lines; and write the matching @code{@@end}
+command, @code{@@end example} in this case, at the on a line of its own
+after the body-text. (@code{@@example} @dots{} @code{@@end example}
+indents and typesets body-text as an example.) It's usually ok to
+indent environment commands like this, but in complicated and
+hard-to-define circumstances the extra spaces cause extra space to
+appear in the output, so beware.
address@hidden itemize
+
address@hidden
address@hidden Braces, when to use
+As a general rule, a command requires braces if it mingles among other
+text; but it does not need braces if it starts a line of its own. The
+non-alphabetic commands, such as @code{@@:}, are exceptions to the rule;
+they do not need address@hidden
+
+As you gain experience with Texinfo, you will rapidly learn how to
+write the different commands: the different ways to write commands
+make it easier to write and read Texinfo files than if all commands
+followed exactly the same syntax. (For details about @@-command
+syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill
+
+
address@hidden Conventions
address@hidden General Syntactic Conventions
address@hidden General syntactic conventions
address@hidden Syntactic conventions
address@hidden Conventions, syntactic
+
+This section describes the general conventions used in all Texinfo documents.
+
address@hidden @bullet
address@hidden
+All printable @sc{ascii} characters except @samp{@@}, @address@hidden and
address@hidden@}} can appear in a Texinfo file and stand for themselves.
address@hidden@@} is the escape character which introduces commands, while
address@hidden@{} and @address@hidden are used to surround arguments to certain
+commands. To put one of these special characters into the document, put
+an @samp{@@} character in front of it, like this: @samp{@@@@},
address@hidden@@@{}, and @samp{@@@}}.
+
address@hidden
+It is customary in @TeX{} to use doubled single-quote characters to
+begin and end quotations: @address@hidden@address@hidden'@w{}'}}. This
+convention should be followed in Texinfo files. @TeX{} converts
+two single quotes to left- and right-hand doubled
+quotation marks,
address@hidden this comes out as "like this" in Info, of course, which is just
confusing.
+and Info converts doubled single-quote characters to @sc{ascii}
+double-quotes: @address@hidden@address@hidden'@w{}'}} becomes
@address@hidden"@dots{}"}}.
+
address@hidden
+Use three hyphens in a row, @samp{---}, for a dash---like this. In
address@hidden, a single or double hyphen produces a printed dash that is
+shorter than the usual typeset dash. Info reduces three hyphens to two
+for display on the screen.
+
address@hidden
+To prevent a paragraph from being indented in the printed manual, put
+the command @code{@@noindent} on a line by itself before the
+paragraph.
+
address@hidden
+If you mark off a region of the Texinfo file with the @code{@@iftex}
+and @address@hidden@@end iftex}} commands, that region will appear only in
+the printed copy; in that region, you can use certain commands
+borrowed from plain @TeX{} that you cannot use in Info. Conversely,
+text surrounded by @code{@@ifnottex} and @code{@@end ifnottex} will
+appear in all output formats @emph{except} @TeX{}.
+
+Each of the other output formats (@code{html}, @code{info},
address@hidden) have an analogous pair of commands. @xref{Conditionals}.
address@hidden itemize
+
address@hidden Tabs; don't use!
address@hidden
address@hidden:} Do not use tab characters in a Texinfo file (except in
+verbatim modes)! @TeX{} uses variable-width fonts, which means that it
+is impractical at best to define a tab to work in all circumstances.
+Consequently, @TeX{} treats tabs like single spaces, and that is not
+what they look like. Furthermore, @code{makeinfo} does nothing special
+with tabs, and thus a tab character in your input file may appear
+differently in the output, for example, in indented text.
+
address@hidden
+To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple
+spaces when you press the @key{TAB} key.
+
address@hidden
+Also, you can run @code{untabify} in Emacs to convert tabs in a region
+to multiple spaces.
address@hidden quotation
+
+
address@hidden Comments
address@hidden Comments
+
address@hidden Comments
address@hidden comment
address@hidden c @r{(comment)}
+
+You can write comments in a Texinfo file that will not appear in
+either the Info file or the printed manual by using the
address@hidden@@comment} command (which may be abbreviated to @code{@@c}).
+Such comments are for the person who revises the Texinfo file. All the
+text on a line that follows either @code{@@comment} or @code{@@c} is a
+comment; the rest of the line does not appear in either the Info file
+or the printed manual.
+
+Often, you can write the @code{@@comment} or @code{@@c} in the middle of
+a line, and only the text that follows after the @code{@@comment} or
address@hidden@@c} command does not appear; but some commands, such as
address@hidden@@settitle} and @code{@@setfilename}, work on a whole line. You
+cannot use @code{@@comment} or @code{@@c} in a line beginning with such
+a command.
+
address@hidden Ignored text
address@hidden Unprocessed text
address@hidden ignore
+You can write long stretches of text that will not appear in either
+the Info file or the printed manual by using the @code{@@ignore} and
address@hidden@@end ignore} commands. Write each of these commands on a line
+of its own, starting each command at the beginning of the line. Text
+between these two commands does not appear in the processed output.
+You can use @code{@@ignore} and @code{@@end ignore} for writing
+comments.
+
+Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or
address@hidden@@ifclear} conditions is ignored in the sense that it will not
+contribute to the formatted output. However, @TeX{} and makeinfo must
+still parse the ignored text, in order to understand when to @emph{stop}
+ignoring text from the source file; that means that you may still get
+error messages if you have invalid Texinfo commands within ignored text.
+
+
address@hidden Minimum
address@hidden What a Texinfo File Must Have
address@hidden Minimal Texinfo file (requirements)
address@hidden Must have in Texinfo file
address@hidden Required in Texinfo file
address@hidden Texinfo file minimum
+
+By convention, the namea of a Texinfo file ends with (in order of
+preference) one of the extensions @file{.texinfo}, @file{.texi},
address@hidden, or @file{.tex}. The longer extensions are preferred since
+they describe more clearly to a human reader the nature of the file.
+The shorter extensions are for operating systems that cannot handle long
+file names.
+
+In order to be made into a printed manual and an Info file, a Texinfo
+file @strong{must} begin with lines like this:
+
address@hidden
address@hidden
+\input texinfo
+@@setfilename @var{info-file-name}
+@@settitle @var{name-of-manual}
address@hidden group
address@hidden example
+
address@hidden
+The contents of the file follow this beginning, and then you
address@hidden end a Texinfo file with a line like this:
+
address@hidden
+@@bye
address@hidden example
+
address@hidden \input @r{(raw @TeX{} startup)}
address@hidden
+Here's an explanation:
+
address@hidden @bullet
address@hidden
+The @samp{\input texinfo} line tells @TeX{} to use the
address@hidden file, which tells @TeX{} how to translate the Texinfo
+@@-commands into @TeX{} typesetting commands. (Note the use of the
+backslash, @samp{\}; this is correct for @TeX{}.)
+
address@hidden
+The @code{@@setfilename} line provides a name for the Info file and
+tells @TeX{} to open auxiliary files. @strong{All text before
address@hidden@@setfilename} is ignored!}
+
address@hidden
+The @code{@@settitle} line specifies a title for the page headers (or
+footers) of the printed manual, and the default document description for
+the @samp{<head>} in HTML format. Strictly speaking, @code{@@settitle}
+is optional---if you don't mind your document being titled `Untitled'.
+
address@hidden
+The @code{@@bye} line at the end of the file on a line of its own tells
+the formatters that the file is ended and to stop formatting.
+
address@hidden itemize
+
+Typically, you will not use quite such a spare format, but will include
+mode setting and start-of-header and end-of-header lines at the
+beginning of a Texinfo file, like this:
+
address@hidden
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename @var{info-file-name}
+@@settitle @var{name-of-manual}
+@@c %**end of header
address@hidden group
address@hidden example
+
address@hidden
+In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into
+Texinfo mode when you edit the file.
+
+The @code{@@c} lines which surround the @code{@@setfilename} and
address@hidden@@settitle} lines are optional, but you need them in order to
+run @TeX{} or Info on just part of the file. (@xref{Start of Header}.)
+
+Furthermore, you will usually provide a Texinfo file with a title page,
+indices, and the like, all of which are explained in this manual. But
+the minimum, which can be useful for short documents, is just the three
+lines at the beginning and the one line at the end.
+
+
address@hidden Six Parts
address@hidden Six Parts of a Texinfo File
+
+Generally, a Texinfo file contains more than the minimal beginning and
+end described in the previous section---it usually contains the six
+parts listed below. These are described fully in the following sections.
+
address@hidden @r
address@hidden 1. Header
+The @dfn{Header} names the file, tells @TeX{} which definitions file to
+use, and other such housekeeping tasks.
+
address@hidden 2. Summary and Copyright
+The @dfn{Summary and Copyright} segment describes the document and
+contains the copyright notice and copying permissions. This is done
+with the @code{@@copying} command.
+
address@hidden 3. Title and Copyright
+The @dfn{Title and Copyright} segment contains the title and copyright
+pages for the printed manual. The segment must be enclosed between
address@hidden@@titlepage} and @code{@@end titlepage} commands. The title and
+copyright page appear only in the printed manual.
+
address@hidden 4. `Top' Node and Master Menu
+The `Top' node starts off the online output; it does not appear in the
+printed manual. We recommend including the copying permissions here as
+well as the segments above. And it contains at least a top-level menu
+listing the chapters, and possibly a @dfn{Master Menu} listing all the
+nodes in the entire document.
+
address@hidden 5. Body
+The @dfn{Body} of the document is typically structured like a
+traditional book or encyclopedia, but it may be free form.
+
address@hidden 6. End
+The @dfn{End} segment contains commands for printing indices and
+generating the table of contents, and the @code{@@bye} command on a line
+of its own.
address@hidden table
+
+
address@hidden Short Sample
address@hidden A Short Sample Texinfo File
address@hidden Sample Texinfo file, with comments
+
+Here is a very short but complete Texinfo file, in the six conventional
+parts enumerated in the previous section, so you can see how Texinfo
+source appears in practice. The first three parts of the file, from
address@hidden texinfo} through to @samp{@@end titlepage}, look more
+intimidating than they are: most of the material is standard
+boilerplate; when writing a manual, you simply change the names as
+appropriate.
+
address@hidden a File}, for full documentation on the commands listed
+here. @xref{GNU Sample Texts}, for the full texts to be used in GNU manuals.
+
+In the following, the sample text is @emph{indented}; comments on it are
+not. The complete file, without interspersed comments, is shown in
address@hidden Sample Texinfo File}.
+
address@hidden Part 1: Header
+
address@hidden
+The header does not appear in either the Info file or the
+printed output. It sets various parameters, including the
+name of the Info file and the title used in the header.
+
address@hidden
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename sample.info
+@@settitle Sample Manual 1.0
+@@c %**end of header
address@hidden group
address@hidden example
+
address@hidden Part 2: Summary Description and Copyright
+
address@hidden
+A real manual includes more text here, according to the license under
+which it is distributed. @xref{GNU Sample Texts}.
+
address@hidden
address@hidden
+@@copying
+This is a short example of a complete Texinfo file, version 1.0.
+
+Copyright @@address@hidden@} 2002 Free Software Foundation, Inc.
+@@end copying
address@hidden group
address@hidden example
+
address@hidden Part 3: Titlepage, Contents, Copyright
+
address@hidden
+The titlepage segment does not appear in the online output, only in the
+printed manual. We use the @code{@@insertcopying} command to
+include the permission text from the previous section, instead of
+writing it out again; it is output on the back of the title page. The
address@hidden@@contents} command generates a table of contents.
+
address@hidden
address@hidden
+@@titlepage
+@@title Sample Title
address@hidden group
+
address@hidden
+@@c The following two commands start the copyright page.
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
+@@end titlepage
address@hidden group
+
+@@c Output the table of contents at the beginning.
+@@contents
address@hidden example
+
address@hidden Part 4: `Top' Node and Master Menu
+
address@hidden
+The `Top' node contains the master menu for the Info file. Since a
+printed manual uses a table of contents rather than a menu, the master
+menu appears only in online output. We also include the copying text
+again for the benefit of online readers. And since the copying text
+begins with a brief description of the manual, no other text is needed.
+
address@hidden
address@hidden
+@@ifnottex
+@@node Top
+@@end ifnottex
address@hidden group
address@hidden example
+
address@hidden
address@hidden
+@@insertcopying
+
+@@menu
+* First Chapter:: The first chapter is the
+ only chapter in this sample.
+* Index:: Complete index.
+@@end menu
address@hidden group
address@hidden example
+
+
address@hidden Part 5: The Body of the Document
+
address@hidden
+The body segment contains all the text of the document, but not the
+indices or table of contents. This example illustrates a node and a
+chapter containing an enumerated list.
+
address@hidden
address@hidden
+@@node First Chapter
+@@chapter First Chapter
+
+@@cindex chapter, first
address@hidden group
+
address@hidden
+This is the first chapter.
+@@cindex index entry, another
address@hidden group
+
address@hidden
+Here is a numbered list.
+
+@@enumerate
+@@item
+This is the first item.
+
+@@item
+This is the second item.
+@@end enumerate
address@hidden group
address@hidden example
+
+
address@hidden Part 6: The End of the Document
+
address@hidden
+The end segment contains commands for generating an index in a node and
+unnumbered chapter of its own, and the @code{@@bye} command that marks
+the end of the document.
+
address@hidden
address@hidden
+@@node Index
+@@unnumbered Index
address@hidden group
+
address@hidden
+@@printindex cp
+
+@@bye
address@hidden group
address@hidden example
+
+
address@hidden Some Results
+
+Here is what the contents of the first chapter of the sample look like:
+
address@hidden 1
address@hidden 700
address@hidden
+This is the first chapter.
+
+Here is a numbered list.
+
address@hidden
address@hidden
+This is the first item.
+
address@hidden
+This is the second item.
address@hidden enumerate
address@hidden quotation
+
+
address@hidden History
address@hidden History
+
address@hidden Stallman, Richard M.
address@hidden Chassell, Robert J.
address@hidden Fox, Brian
address@hidden Berry, Karl
+Richard M.@: Stallman invented the Texinfo format, wrote the initial
+processors, and created Edition 1.0 of this manual. @w{Robert J.@:}
+Chassell greatly revised and extended the manual, starting with Edition
+1.1. Brian Fox was responsible for the standalone Texinfo distribution
+until version 3.8, and wrote the standalone @command{makeinfo} and
address@hidden programs. Karl Berry has continued maintenance since
+Texinfo 3.8 (manual edition 2.22).
+
address@hidden Pinard, Fran@,{c}ois
address@hidden Zuhn, David D.
address@hidden Weisshaus, Melissa
address@hidden Zaretskii, Eli
address@hidden Schwab, Andreas
address@hidden Weinberg, Zack
+Our thanks go out to all who helped improve this work, particularly the
+indefatigable Eli Zaretskii and Andreas Schwab, who have provided
+patches beyond counting. Fran@,{c}ois Pinard and @w{David D.@: Zuhn},
+tirelessly recorded and reported mistakes and obscurities. Zack
+Weinberg did the impossible by implementing the macro syntax in
address@hidden Special thanks go to Melissa Weisshaus for her
+frequent reviews of nearly similar editions. Dozens of others have
+contributed patches and suggestions, they are gratefully acknowledged in
+the @file{ChangeLog} file. Our mistakes are our own.
+
address@hidden Scribe
address@hidden Reid, Brian
address@hidden History of Texinfo
address@hidden Texinfo history
+A bit of history: in the 1970's at CMU, Brian Reid developed a program
+and format named Scribe to mark up documents for printing. It used the
address@hidden@@} character to introduce commands, as Texinfo does. Much more
+consequentially, it strived to describe document contents rather than
+formatting, an idea wholeheartedly adopted by Texinfo.
+
address@hidden Bolio
address@hidden address@hidden
+Meanwhile, people at MIT developed another, not too dissimilar format
+called Bolio. This then was converted to using @TeX{} as its typesetting
+language: address@hidden The earliest address@hidden version seems to have
been
+0.02 on October 31, 1984.
+
address@hidden could only be used as a markup language for documents to be
+printed, not for online documents. Richard Stallman (RMS) worked on
+both Bolio and address@hidden He also developed a nifty on-line help format
+called Info, and then combined address@hidden and Info to create Texinfo, a
+mark up language for text that is intended to be read both online and
+as printed hard copy.
+
+
address@hidden Texinfo Mode
address@hidden Using Texinfo Mode
address@hidden Texinfo mode
address@hidden Mode, using Texinfo
address@hidden GNU Emacs
address@hidden Emacs
+
+You may edit a Texinfo file with any text editor you choose. A Texinfo
+file is no different from any other @sc{ascii} file. However, GNU Emacs
+comes with a special mode, called Texinfo mode, that provides Emacs
+commands and tools to help ease your work.
+
+This chapter describes features of GNU Emacs' Texinfo mode but not any
+features of the Texinfo formatting language. So if you are reading this
+manual straight through from the beginning, you may want to skim through
+this chapter briefly and come back to it after reading succeeding
+chapters which describe the Texinfo formatting language in detail.
+
address@hidden
+* 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.
address@hidden menu
+
address@hidden Texinfo Mode Overview, Emacs Editing, Texinfo Mode, Texinfo Mode
address@hidden Texinfo Mode Overview
+
+Texinfo mode provides special features for working with Texinfo
+files.
+You can:@refill
+
address@hidden @bullet
address@hidden
+Insert frequently used @@-commands. @refill
+
address@hidden
+Automatically create @code{@@node} lines.
+
address@hidden
+Show the structure of a Texinfo source address@hidden
+
address@hidden
+Automatically create or update the `Next',
+`Previous', and `Up' pointers of a node.
+
address@hidden
+Automatically create or update address@hidden
+
address@hidden
+Automatically create a master address@hidden
+
address@hidden
+Format a part or all of a file for address@hidden
+
address@hidden
+Typeset and print part or all of a address@hidden
address@hidden itemize
+
+Perhaps the two most helpful features are those for inserting frequently
+used @@-commands and for creating node pointers and address@hidden
+
address@hidden Emacs Editing, Inserting, Texinfo Mode Overview, Texinfo Mode
address@hidden The Usual GNU Emacs Editing Commands
+
+In most cases, the usual Text mode commands work the same in Texinfo
+mode as they do in Text mode. Texinfo mode adds new editing commands
+and tools to GNU Emacs' general purpose editing features. The major
+difference concerns filling. In Texinfo mode, the paragraph
+separation variable and syntax table are redefined so that Texinfo
+commands that should be on lines of their own are not inadvertently
+included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph})
+command will refill a paragraph but not mix an indexing command on a
+line adjacent to it into the address@hidden
+
+In addition, Texinfo mode sets the @code{page-delimiter} variable to
+the value of @code{texinfo-chapter-level-regexp}; by default, this is
+a regular expression matching the commands for chapters and their
+equivalents, such as appendices. With this value for the page
+delimiter, you can jump from chapter title to chapter title with the
address@hidden ]} (@code{forward-page}) and @kbd{C-x [}
+(@code{backward-page}) commands and narrow to a chapter with the
address@hidden p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs,
+The GNU Emacs Manual}, for details about the page commands.)@refill
+
+You may name a Texinfo file however you wish, but the convention is to
+end a Texinfo file name with one of the extensions
address@hidden, @file{.texi}, @file{.txi}, or @file{.tex}. A longer
+extension is preferred, since it is explicit, but a shorter extension
+may be necessary for operating systems that limit the length of file
+names. GNU Emacs automatically enters Texinfo mode when you visit a
+file with a @file{.texinfo}, @file{.texi} or @file{.txi}
+extension. Also, Emacs switches to Texinfo mode
+when you visit a
+file that has @samp{-*-texinfo-*-} in its first line. If ever you are
+in another mode and wish to switch to Texinfo mode, type @code{M-x
address@hidden
+
+Like all other Emacs features, you can customize or enhance Texinfo
+mode as you wish. In particular, the keybindings are very easy to
+change. The keybindings described here are the default or standard
address@hidden
+
address@hidden Inserting, Showing the Structure, Emacs Editing, Texinfo Mode
address@hidden node-name, next, previous, up
address@hidden Inserting Frequently Used Commands
address@hidden Inserting frequently used commands
address@hidden Frequently used commands, inserting
address@hidden Commands, inserting them
+
+Texinfo mode provides commands to insert various frequently used
+@@-commands into the buffer. You can use these commands to save
address@hidden
+
+The insert commands are invoked by typing @kbd{C-c} twice and then the
+first letter of the @@-command:@refill
+
address@hidden @kbd
address@hidden C-c C-c c
address@hidden M-x texinfo-insert-@@code
address@hidden texinfo-insert-@@code
+Insert @code{@@address@hidden@}} and put the
+cursor between the address@hidden
+
address@hidden C-c C-c d
address@hidden M-x texinfo-insert-@@dfn
address@hidden texinfo-insert-@@dfn
+Insert @code{@@address@hidden@}} and put the
+cursor between the address@hidden
+
address@hidden C-c C-c e
address@hidden M-x texinfo-insert-@@end
address@hidden texinfo-insert-@@end
+Insert @code{@@end} and attempt to insert the correct following word,
+such as @samp{example} or @samp{table}. (This command does not handle
+nested lists correctly, but inserts the word appropriate to the
+immediately preceding list.)@refill
+
address@hidden C-c C-c i
address@hidden M-x texinfo-insert-@@item
address@hidden texinfo-insert-@@item
+Insert @code{@@item} and put the
+cursor at the beginning of the next address@hidden
+
address@hidden C-c C-c k
address@hidden M-x texinfo-insert-@@kbd
address@hidden texinfo-insert-@@kbd
+Insert @code{@@address@hidden@}} and put the
+cursor between the address@hidden
+
address@hidden C-c C-c n
address@hidden M-x texinfo-insert-@@node
address@hidden texinfo-insert-@@node
+Insert @code{@@node} and a comment line
+listing the sequence for the `Next',
+`Previous', and `Up' nodes.
+Leave point after the @code{@@address@hidden
+
address@hidden C-c C-c o
address@hidden M-x texinfo-insert-@@noindent
address@hidden texinfo-insert-@@noindent
+Insert @code{@@noindent} and put the
+cursor at the beginning of the next address@hidden
+
address@hidden C-c C-c s
address@hidden M-x texinfo-insert-@@samp
address@hidden texinfo-insert-@@samp
+Insert @code{@@address@hidden@}} and put the
+cursor between the address@hidden
+
address@hidden C-c C-c t
address@hidden M-x texinfo-insert-@@table
address@hidden texinfo-insert-@@table
+Insert @code{@@table} followed by a @key{SPC}
+and leave the cursor after the @address@hidden
+
address@hidden C-c C-c v
address@hidden M-x texinfo-insert-@@var
address@hidden texinfo-insert-@@var
+Insert @code{@@address@hidden@}} and put the
+cursor between the address@hidden
+
address@hidden C-c C-c x
address@hidden M-x texinfo-insert-@@example
address@hidden texinfo-insert-@@example
+Insert @code{@@example} and put the
+cursor at the beginning of the next address@hidden
+
address@hidden address@hidden was the binding for texinfo-insert-braces;
address@hidden in Emacs 19, backward-paragraph will take this binding.
address@hidden C-c C-c @{
address@hidden M-x texinfo-insert-braces
address@hidden texinfo-insert-braces
+Insert @address@hidden@}} and put the cursor between the address@hidden
+
address@hidden C-c C-c @}
address@hidden C-c C-c ]
address@hidden M-x up-list
address@hidden up-list
+Move from between a pair of braces forward past the closing brace.
+Typing @kbd{C-c C-c ]} is easier than typing @kbd{C-c C-c @}}, which
+is, however, more mnemonic; hence the two keybindings. (Also, you can
+move out from between braces by typing @kbd{C-f}.)@refill
address@hidden table
+
+To put a command such as @address@hidden@@address@hidden@address@hidden around
an
address@hidden word, position the cursor in front of the word and type
address@hidden 1 C-c C-c c}. This makes it easy to edit existing plain text.
+The value of the prefix argument tells Emacs how many words following
+point to include between address@hidden for one word, @samp{2} for
+two words, and so on. Use a negative argument to enclose the previous
+word or words. If you do not specify a prefix argument, Emacs inserts
+the @@-command string and positions the cursor between the braces. This
+feature works only for those @@-commands that operate on a word or words
+within one line, such as @code{@@kbd} and @code{@@address@hidden
+
+This set of insert commands was created after analyzing the frequency
+with which different @@-commands are 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 @address@hidden
+
address@hidden texinfo-start-menu-description
address@hidden Menu description, start
address@hidden Description for menu, start
address@hidden C-c C-d} (@code{texinfo-start-menu-description}) is an insert
+command that works differently from the other insert commands. It
+inserts a node's section or chapter title in the space for the
+description in a menu entry line. (A menu entry has three parts, the
+entry name, the node name, and the description. Only the node name is
+required, but a description helps explain what the node is about.
address@hidden Parts, , The Parts of a Menu}.)@refill
+
+To use @code{texinfo-start-menu-description}, position point in a menu
+entry line and type @kbd{C-c C-c C-d}. The command looks for and copies
+the title that goes with the node name, and inserts the title as a
+description; it positions point at beginning of the inserted text so you
+can edit it. The function does not insert the title if the menu entry
+line already contains a address@hidden
+
+This command is only an aid to writing descriptions; it does not do the
+whole job. You must edit the inserted text since a title tends to use
+the same words as a node name but a useful description uses different
address@hidden
+
address@hidden Showing the Structure, Updating Nodes and Menus, Inserting,
Texinfo Mode
address@hidden node-name, next, previous, up
address@hidden Showing the Section Structure of a File
address@hidden Showing the section structure of a file
address@hidden Section structure of a file, showing it
address@hidden Structure of a file, showing it
address@hidden Outline of file structure, showing it
address@hidden Contents-like outline of file structure
address@hidden File section structure, showing it
address@hidden Texinfo file section structure, showing it
+
+You can show the section structure of a Texinfo file by using the
address@hidden C-s} command (@code{texinfo-show-structure}). This command
+shows the section structure of a Texinfo file by listing the lines
+that begin with the @@-commands for @code{@@chapter},
address@hidden@@section}, and the like. It constructs what amounts
+to a table of contents. These lines are displayed in another buffer
+called the @samp{*Occur*} buffer. In that buffer, 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 address@hidden
+
address@hidden @kbd
address@hidden C-c C-s
address@hidden M-x texinfo-show-structure
address@hidden texinfo-show-structure
+Show the @code{@@chapter}, @code{@@section}, and such lines of a
+Texinfo address@hidden
+
address@hidden C-c C-c
address@hidden M-x occur-mode-goto-occurrence
address@hidden occur-mode-goto-occurrence
+Go to the line in the Texinfo file corresponding to the line under the
+cursor in the @file{*Occur*} address@hidden
address@hidden table
+
+If you call @code{texinfo-show-structure} with a prefix argument by
+typing @address@hidden C-c C-s}}, it will list not only those lines with the
+@@-commands for @code{@@chapter}, @code{@@section}, and the like, but
+also the @code{@@node} lines. You can use @code{texinfo-show-structure}
+with a prefix argument to check whether the `Next', `Previous', and `Up'
+pointers of an @code{@@node} line are correct.
+
+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 by using the
address@hidden n n} (@code{narrow-to-region}) command and
address@hidden will work on only that region. To see
+the whole buffer again, use @address@hidden n w}} (@code{widen}).
+(@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more
+information about the narrowing commands.)@refill
+
address@hidden page-delimiter
address@hidden Page delimiter in Texinfo mode
+In addition to providing the @code{texinfo-show-structure} command,
+Texinfo mode sets the value of the page delimiter variable to match
+the chapter-level @@-commands. This enables you to use the @kbd{C-x
+]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page})
+commands to move forward and backward by chapter, and to use the
address@hidden p} (@code{narrow-to-page}) command to narrow to a chapter.
address@hidden, , , emacs, The GNU Emacs Manual}, for more information
+about the page address@hidden
+
address@hidden Updating Nodes and Menus, Info Formatting, Showing the
Structure, Texinfo Mode
address@hidden node-name, next, previous, up
address@hidden Updating Nodes and Menus
address@hidden Updating nodes and menus
address@hidden Create nodes, menus automatically
address@hidden Insert nodes, menus automatically
address@hidden Automatically insert nodes, menus
+
+Texinfo mode provides commands for automatically creating or updating
+menus and node pointers. The commands are called ``update'' commands
+because their most frequent use is for updating a Texinfo file after you
+have worked on it; but you can use them to insert the `Next',
+`Previous', and `Up' pointers into an @code{@@node} line that has none
+and to create menus in a file that has none.
+
+If you do not use the updating commands, you need to write menus and
+node pointers by hand, which is a tedious address@hidden
+
address@hidden
+* 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.
address@hidden menu
+
address@hidden Updating Commands, Updating Requirements, Updating Nodes and
Menus, Updating Nodes and Menus
address@hidden The Updating Commands
+
+You can use the updating commands to:@refill
+
address@hidden @bullet
address@hidden
+insert or update the `Next', `Previous', and `Up' pointers of a
+node,@refill
+
address@hidden
+insert or update the menu for a section, address@hidden
+
address@hidden
+create a master menu for a Texinfo source address@hidden
address@hidden itemize
+
+You can also use the commands to update all the nodes and menus in a
+region or in a whole Texinfo address@hidden
+
+The updating commands work only with conventional Texinfo files, which
+are structured hierarchically like books. In such files, a structuring
+command line must follow closely after each @code{@@node} line, except
+for the `Top' @code{@@node} line. (A @dfn{structuring command line} is
+a line beginning with @code{@@chapter}, @code{@@section}, or other
+similar command.)
+
+You can write the structuring command line on the line that follows
+immediately after an @code{@@node} line or else on the line that
+follows after a single @code{@@comment} line or a single
address@hidden@@ifinfo} line. You cannot interpose more than one line between
+the @code{@@node} line and the structuring command line; and you may
+interpose only an @code{@@comment} line or an @code{@@ifinfo} line.
+
+Commands which work on a whole buffer require that the `Top' node be
+followed by a node with an @code{@@chapter} or equivalent-level command.
+The menu updating commands will not create a main or master menu for a
+Texinfo file that has only @code{@@chapter}-level nodes! The menu
+updating commands only create menus @emph{within} nodes for lower level
+nodes. To create a menu of chapters, you must provide a `Top'
+node.
+
+The menu updating commands remove menu entries that refer to other Info
+files since they do not refer to nodes within the current buffer. This
+is a deficiency. Rather than use menu entries, you can use cross
+references to refer to other Info files. None of the updating commands
+affect cross address@hidden
+
+Texinfo mode has five updating commands that are used most often: two
+are for updating the node pointers or menu of a single node (or a
+region); two are for updating every node pointer and menu in a file;
+and one, the @code{texinfo-master-menu} command, is for creating a
+master menu for a complete file, and optionally, for updating every
+node and menu in the whole Texinfo address@hidden
+
+The @code{texinfo-master-menu} command is the primary command:@refill
+
address@hidden @kbd
address@hidden C-c C-u m
address@hidden M-x texinfo-master-menu
address@hidden texinfo-master-menu
+Create or update a master menu that includes all the other menus
+(incorporating the descriptions from pre-existing menus, if
+any)address@hidden
+
+With an argument (prefix argument, @kbd{C-u,} if interactive), first create or
+update all the nodes and all the regular menus in the buffer before
+constructing the master menu. (@xref{The Top Node, , The Top Node and
+Master Menu}, for more about a master menu.)@refill
+
+For @code{texinfo-master-menu} to work, the Texinfo file must have a
+`Top' node and at least one subsequent address@hidden
+
+After extensively editing a Texinfo file, you can type the following:
+
address@hidden
+C-u M-x texinfo-master-menu
address@hidden or
+C-u C-c C-u m
address@hidden example
+
address@hidden
+This updates all the nodes and menus completely and all at address@hidden
address@hidden table
+
+The other major updating commands do smaller jobs and are designed for
+the person who updates nodes and menus as he or she writes a Texinfo
address@hidden
+
address@hidden 1000
+The commands are:@refill
+
address@hidden @kbd
address@hidden C-c C-u C-n
address@hidden M-x texinfo-update-node
address@hidden texinfo-update-node
+Insert the `Next', `Previous', and `Up' pointers for the node that point is
+within (i.e., for the @code{@@node} line preceding point). If the
address@hidden@@node} line has pre-existing `Next', `Previous', or `Up'
+pointers in it, the old pointers are removed and new ones inserted.
+With an argument (prefix argument, @kbd{C-u}, if interactive), this command
+updates all @code{@@node} lines in the region (which is the text
+between point and mark)address@hidden
+
address@hidden C-c C-u C-m
address@hidden M-x texinfo-make-menu
address@hidden texinfo-make-menu
+Create or update the menu in the node that point is within.
+With an argument (@kbd{C-u} as prefix argument, if
+interactive), the command makes or updates menus for the
+nodes which are either within or a part of the
address@hidden
+
+Whenever @code{texinfo-make-menu} updates an existing menu, the
+descriptions from that menu are incorporated into the new menu. This
+is done by copying descriptions from the existing menu to the entries
+in the new menu that have the same node names. If the node names are
+different, the descriptions are not copied to the new address@hidden
+
address@hidden C-c C-u C-e
address@hidden M-x texinfo-every-node-update
address@hidden texinfo-every-node-update
+Insert or update the `Next', `Previous', and `Up' pointers for every
+node in the address@hidden
+
address@hidden C-c C-u C-a
address@hidden M-x texinfo-all-menus-update
address@hidden texinfo-all-menus-update
+Create or update all the menus in the buffer. With an argument
+(@kbd{C-u} as prefix argument, if interactive), first insert
+or update all the node
+pointers before working on the address@hidden
+
+If a master menu exists, the @code{texinfo-all-menus-update} command
+updates it; but the command does not create a new master menu if none
+already exists. (Use the @code{texinfo-master-menu} command for
+that.)@refill
+
+When working on a document that does not merit a master menu, you can
+type the following:
+
address@hidden
+C-u C-c C-u C-a
address@hidden or
+C-u M-x texinfo-all-menus-update
address@hidden example
+
address@hidden
+This updates all the nodes and address@hidden
address@hidden table
+
+The @code{texinfo-column-for-description} variable specifies the
+column to which menu descriptions are indented. By default, the value
+is 32 although it is often useful to reduce it to as low as 24. You
+can set the variable with the @kbd{M-x edit-options} command
+(@pxref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs
+Manual}) or with the @kbd{M-x set-variable} command (@pxref{Examining,
+, Examining and Setting Variables, emacs, The GNU Emacs
+Manual})address@hidden
+
+Also, the @code{texinfo-indent-menu-description} command may be used to
+indent existing menu descriptions to a specified column. Finally, if
+you wish, you can use the @code{texinfo-insert-node-lines} command to
+insert missing @code{@@node} lines into a file. (@xref{Other Updating
+Commands}, for more information.)@refill
+
address@hidden Updating Requirements
address@hidden Updating Requirements
address@hidden Updating requirements
address@hidden Requirements for updating commands
+
+To use the updating commands, you must organize the Texinfo file
+hierarchically with chapters, sections, subsections, and the like.
+When you construct the hierarchy of the manual, do not `jump down'
+more than one level at a time: you can follow the `Top' node with a
+chapter, but not with a section; you can follow a chapter with a
+section, but not with a subsection. However, you may `jump up' any
+number of levels at one time---for example, from a subsection to a
address@hidden
+
+Each @code{@@node} line, with the exception of the line for the `Top'
+node, must be followed by a line with a structuring command such as
address@hidden@@chapter}, @code{@@section}, or
address@hidden@@address@hidden
+
+Each @code{@@node} line/structuring-command line combination
+must look either like this:
+
address@hidden
address@hidden
+@@node Comments, Minimum, Conventions, Overview
+@@comment node-name, next, previous, up
+@@section Comments
address@hidden group
address@hidden example
+
+or like this (without the @code{@@comment} line):
+
address@hidden
address@hidden
+@@node Comments, Minimum, Conventions, Overview
+@@section Comments
address@hidden group
address@hidden example
+
+or like this (without the explicit node pointers):
+
address@hidden
address@hidden
+@@node Comments
+@@section Comments
address@hidden group
address@hidden example
+
address@hidden
+In this example, `Comments' is the name of both the node and the
+section. The next node is called `Minimum' and the previous node is
+called `Conventions'. The `Comments' section is within the `Overview'
+node, which is specified by the `Up' pointer. (Instead of an
address@hidden@@comment} line, you may also write an @code{@@ifinfo} line.)
+
+If a file has a `Top' node, it must be called @samp{top} or @samp{Top}
+and be the first node in the file.
+
+The menu updating commands create a menu of sections within a chapter,
+a menu of subsections within a section, and so on. This means that
+you must have a `Top' node if you want a menu of address@hidden
+
+Incidentally, the @code{makeinfo} command will create an Info file for a
+hierarchically organized Texinfo file that lacks `Next', `Previous' and
+`Up' pointers. Thus, if you can be sure that your Texinfo file will be
+formatted with @code{makeinfo}, you have no need for the update node
+commands. (@xref{Creating an Info File}, for more information about
address@hidden) However, both @code{makeinfo} and the
address@hidden@dots{}} commands require that you insert menus in
+the file.
+
+
address@hidden Other Updating Commands
address@hidden Other Updating Commands
+
+In addition to the five major updating commands, Texinfo mode
+possesses several less frequently used updating commands:@refill
+
address@hidden @kbd
address@hidden M-x texinfo-insert-node-lines
address@hidden texinfo-insert-node-lines
+Insert @code{@@node} lines before the @code{@@chapter},
address@hidden@@section}, and other sectioning commands wherever they are
+missing throughout a region in a Texinfo address@hidden
+
+With an argument (@kbd{C-u} as prefix argument, if interactive), the
address@hidden command not only inserts
address@hidden@@node} lines but also inserts the chapter or section titles as
+the names of the corresponding nodes. In addition, it inserts the
+titles as node names in pre-existing @code{@@node} lines that lack
+names. Since node names should be more concise than section or
+chapter titles, you must manually edit node names so address@hidden
+
+For example, the following marks a whole buffer as a region and inserts
address@hidden@@node} lines and titles throughout:@refill
+
address@hidden
+C-x h C-u M-x texinfo-insert-node-lines
address@hidden example
+
+This command inserts titles as node names in @code{@@node} lines; the
address@hidden command (@pxref{Inserting,
+Inserting Frequently Used Commands}) inserts titles as descriptions in
+menu entries, a different action. However, in both cases, you need to
+edit the inserted text.
+
address@hidden M-x texinfo-multiple-files-update
address@hidden texinfo-multiple-files-update @r{(in brief)}
+Update nodes and menus in a document built from several separate files.
+With @kbd{C-u} as a prefix argument, create and insert a master menu in
+the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first
+update all the menus and all the `Next', `Previous', and `Up' pointers
+of all the included files before creating and inserting a master menu in
+the outer file. The @code{texinfo-multiple-files-update} command is
+described in the appendix on @code{@@include} files.
address@hidden@refill
+
address@hidden M-x texinfo-indent-menu-description
address@hidden texinfo-indent-menu-description
+Indent every description in the menu following point to the specified
+column. You can use this command to give yourself more space for
+descriptions. With an argument (@kbd{C-u} as prefix argument, if
+interactive), the @code{texinfo-indent-menu-description} command indents
+every description in every menu in the region. However, this command
+does not indent the second and subsequent lines of a multi-line
address@hidden
+
address@hidden M-x texinfo-sequential-node-update
address@hidden texinfo-sequential-node-update
+Insert the names of the nodes immediately following and preceding the
+current node as the `Next' or `Previous' pointers regardless of those
+nodes' hierarchical level. This means that the `Next' node of a
+subsection may well be the next chapter. Sequentially ordered nodes are
+useful for novels and other documents that you read through
+sequentially. (However, in Info, the @kbd{g *} command lets
+you look through the file sequentially, so sequentially ordered nodes
+are not strictly necessary.) With an argument (prefix argument, if
+interactive), the @code{texinfo-sequential-node-update} command
+sequentially updates all the nodes in the address@hidden
address@hidden table
+
address@hidden Info Formatting, Printing, Updating Nodes and Menus, Texinfo Mode
address@hidden node-name, next, previous, up
address@hidden Formatting for Info
address@hidden Formatting for Info
address@hidden Running an Info formatter
address@hidden Info formatting
+
+Texinfo mode provides several commands for formatting part or all of a
+Texinfo file for Info. Often, when you are writing a document, you
+want to format only part of a file---that is, a address@hidden
+
+You can use either the @code{texinfo-format-region} or the
address@hidden command to format a region:@refill
+
address@hidden @kbd
address@hidden texinfo-format-region
address@hidden C-c C-e C-r
address@hidden M-x texinfo-format-region
address@hidden C-c C-m C-r
address@hidden M-x makeinfo-region
+Format the current region for address@hidden
address@hidden table
+
+You can use either the @code{texinfo-format-buffer} or the
address@hidden command to format a whole buffer:@refill
+
address@hidden @kbd
address@hidden texinfo-format-buffer
address@hidden C-c C-e C-b
address@hidden M-x texinfo-format-buffer
address@hidden C-c C-m C-b
address@hidden M-x makeinfo-buffer
+Format the current buffer for address@hidden
address@hidden table
+
address@hidden 1000
+For example, after writing a Texinfo file, you can type the following:
+
address@hidden
+C-u C-c C-u m
address@hidden or
+C-u M-x texinfo-master-menu
address@hidden example
+
address@hidden
+This updates all the nodes and menus. Then type the following to create
+an Info file:
+
address@hidden
+C-c C-m C-b
address@hidden or
+M-x makeinfo-buffer
address@hidden example
+
+For @TeX{} or the Info formatting commands to work, the file @emph{must}
+include a line that has @code{@@setfilename} in its header.
+
address@hidden an Info File}, for details about Info address@hidden
+
address@hidden Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode
address@hidden node-name, next, previous, up
address@hidden Formatting and Printing
address@hidden Formatting for printing
address@hidden Printing a region or buffer
address@hidden Region formatting and printing
address@hidden Buffer formatting and printing
address@hidden Part of file formatting and printing
+
+Typesetting and printing a Texinfo file is a multi-step process in which
+you first create a file for printing (called a DVI file), and then
+print the file. Optionally, you may also create indices. To do this,
+you must run the @code{texindex} command after first running the
address@hidden typesetting command; and then you must run the @code{tex}
+command again. Or else run the @code{texi2dvi} command which
+automatically creates indices as needed (@pxref{Format with texi2dvi}).
+
+Often, when you are writing a document, you want to typeset and print
+only part of a file to see what it will look like. You can use the
address@hidden and related commands for this purpose. Use
+the @code{texinfo-tex-buffer} command to format all of a
address@hidden
+
address@hidden @kbd
address@hidden C-c C-t C-b
address@hidden M-x texinfo-tex-buffer
address@hidden texinfo-tex-buffer
+Run @code{texi2dvi} on the buffer. In addition to running @TeX{} on the
+buffer, this command automatically creates or updates indices as
address@hidden
+
address@hidden C-c C-t C-r
address@hidden M-x texinfo-tex-region
address@hidden texinfo-tex-region
+Run @TeX{} on the address@hidden
+
address@hidden C-c C-t C-i
address@hidden M-x texinfo-texindex
+Run @code{texindex} to sort the indices of a Texinfo file formatted with
address@hidden The @code{texinfo-tex-region} command does
+not run @code{texindex} automatically; it only runs the @code{tex}
+typesetting command. You must run the @code{texinfo-tex-region} command
+a second time after sorting the raw index files with the @code{texindex}
+command. (Usually, you do not format an index when you format a region,
+only when you format a buffer. Now that the @code{texi2dvi} command
+exists, there is little or no need for this command.)@refill
+
address@hidden C-c C-t C-p
address@hidden M-x texinfo-tex-print
address@hidden texinfo-tex-print
+Print the file (or the part of the file) previously formatted with
address@hidden or @address@hidden
address@hidden table
+
+For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the
+file @emph{must} start with a @samp{\input texinfo} line and must
+include an @code{@@settitle} line. The file must end with @code{@@bye}
+on a line by itself. (When you use @code{texinfo-tex-region}, you must
+surround the @code{@@settitle} line with start-of-header and
+end-of-header lines.)@refill
+
address@hidden, for a description of the other @TeX{} related
+commands, such as @address@hidden
+
address@hidden Texinfo Mode Summary, , Printing, Texinfo Mode
address@hidden node-name, next, previous, up
address@hidden Texinfo Mode Summary
+
+In Texinfo mode, each set of commands has default keybindings that
+begin with the same keys. All the commands that are custom-created
+for Texinfo mode begin with @kbd{C-c}. The keys are somewhat
address@hidden
+
address@hidden Insert Commands
+
+The insert commands are invoked by typing @kbd{C-c} twice and then the
+first letter of the @@-command to be inserted. (It might make more
+sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but
address@hidden C-c} is quick to type.)@refill
+
address@hidden
+C-c C-c c @r{Insert} @samp{@@code}.
+C-c C-c d @r{Insert} @samp{@@dfn}.
+C-c C-c e @r{Insert} @samp{@@end}.
+C-c C-c i @r{Insert} @samp{@@item}.
+C-c C-c n @r{Insert} @samp{@@node}.
+C-c C-c s @r{Insert} @samp{@@samp}.
+C-c C-c v @r{Insert} @samp{@@var}.
+C-c C-c @{ @r{Insert braces.}
+C-c C-c ]
+C-c C-c @} @r{Move out of enclosing braces.}
+
address@hidden
+C-c C-c C-d @r{Insert a node's section title}
+ @r{in the space for the description}
+ @r{in a menu entry line.}
address@hidden group
address@hidden example
+
address@hidden Show Structure
+
+The @code{texinfo-show-structure} command is often used within a
+narrowed address@hidden
+
address@hidden
+C-c C-s @r{List all the headings.}
address@hidden example
+
address@hidden The Master Update Command
+
+The @code{texinfo-master-menu} command creates a master menu; and can
+be used to update every node and menu in a file as address@hidden
+
address@hidden Probably should use @tables in this section.
address@hidden
address@hidden
+C-c C-u m
+M-x texinfo-master-menu
+ @r{Create or update a master menu.}
address@hidden group
+
address@hidden
+C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first}
+ @r{create or update all nodes and regular}
+ @r{menus, and then create a master menu.}
address@hidden group
address@hidden example
+
address@hidden Update Pointers
+
+The update pointer commands are invoked by typing @kbd{C-c C-u} and
+then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for
address@hidden@refill
+
address@hidden
+C-c C-u C-n @r{Update a node.}
+C-c C-u C-e @r{Update every node in the buffer.}
address@hidden example
+
address@hidden Update Menus
+
+Invoke the update menu commands by typing @kbd{C-c C-u}
+and then either @kbd{C-m} for @code{texinfo-make-menu} or
address@hidden for @code{texinfo-all-menus-update}. To update
+both nodes and menus at the same time, precede @kbd{C-c C-u
+C-a} with @address@hidden
+
address@hidden
+C-c C-u C-m @r{Make or update a menu.}
+
address@hidden
+C-c C-u C-a @r{Make or update all}
+ @r{menus in a buffer.}
address@hidden group
+
address@hidden
+C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,}
+ @r{first create or update all nodes and}
+ @r{then create or update all menus.}
address@hidden group
address@hidden example
+
address@hidden Format for Info
+
+The Info formatting commands that are written in Emacs Lisp are
+invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region
+or @kbd{C-b} for the whole address@hidden
+
+The Info formatting commands that are written in C and based on the
address@hidden program are invoked by typing @kbd{C-c C-m} and then
+either @kbd{C-r} for a region or @kbd{C-b} for the whole address@hidden
+
address@hidden 800
address@hidden
+Use the @address@hidden commands:
+
address@hidden
address@hidden
+C-c C-e C-r @r{Format the region.}
+C-c C-e C-b @r{Format the buffer.}
address@hidden group
address@hidden example
+
address@hidden 750
address@hidden
+Use @code{makeinfo}:
+
address@hidden
+C-c C-m C-r @r{Format the region.}
+C-c C-m C-b @r{Format the buffer.}
+C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.}
+C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.}
address@hidden example
+
address@hidden Typeset and Print
+
+The @TeX{} typesetting and printing commands are invoked by typing
address@hidden C-t} and then another control command: @kbd{C-r} for
address@hidden, @kbd{C-b} for @code{texinfo-tex-buffer},
+and so address@hidden
+
address@hidden
+C-c C-t C-r @r{Run @TeX{} on the region.}
+C-c C-t C-b @r{Run} @code{texi2dvi} @r{on the buffer.}
+C-c C-t C-i @r{Run} @code{texindex}.
+C-c C-t C-p @r{Print the DVI file.}
+C-c C-t C-q @r{Show the print queue.}
+C-c C-t C-d @r{Delete a job from the print queue.}
+C-c C-t C-k @r{Kill the current @TeX{} formatting job.}
+C-c C-t C-x @r{Quit a currently stopped @TeX{} formatting job.}
+C-c C-t C-l @r{Recenter the output buffer.}
address@hidden example
+
address@hidden Other Updating Commands
+
+The remaining updating commands do not have standard keybindings because
+they are rarely used.
+
address@hidden
address@hidden
+M-x texinfo-insert-node-lines
+ @r{Insert missing @code{@@node} lines in region.}
+ @r{With @kbd{C-u} as a prefix argument,}
+ @r{use section titles as node names.}
address@hidden group
+
address@hidden
+M-x texinfo-multiple-files-update
+ @r{Update a multi-file document.}
+ @r{With @kbd{C-u 2} as a prefix argument,}
+ @r{create or update all nodes and menus}
+ @r{in all included files first.}
address@hidden group
+
address@hidden
+M-x texinfo-indent-menu-description
+ @r{Indent descriptions.}
address@hidden group
+
address@hidden
+M-x texinfo-sequential-node-update
+ @r{Insert node pointers in strict sequence.}
address@hidden group
address@hidden example
+
+
address@hidden Beginning a File
address@hidden Beginning a Texinfo File
address@hidden Beginning a Texinfo file
address@hidden Texinfo file beginning
address@hidden File beginning
+
+Certain pieces of information must be provided at the beginning of a
+Texinfo file, such as the name for the output file(s), the title of the
+document, and the Top node.
+
+This chapter expands on the minimal complete Texinfo source file
+previously given (@pxref{Six Parts}).
+
address@hidden
+* 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.
+* The Top Node:: Creating the `Top' node and master menu.
+* Global Document Commands:: Affecting formatting throughout.
+* Software Copying Permissions:: Ensure that you and others continue to
+ have the right to use and share software.
address@hidden menu
+
+
address@hidden Sample Beginning
address@hidden Sample Texinfo File Beginning
+
address@hidden Example beginning of Texinfo file
+
+The following sample shows what is needed. The elements given here are
+explained in more detail in the following sections. Other commands are
+often included at the beginning of Texinfo files, but the ones here are
+the most critical.
+
address@hidden Sample Texts}, for the full texts to be used in GNU manuals.
+
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename @var{infoname}.info
+@@settitle @var{name-of-manual} @var{version}
+@@c %**end of header
+
+@@copying
+This manual is for @var{program}, version @var{version}.
+
+Copyright @@address@hidden@} @var{years} @var{copyright-owner}.
+
address@hidden
+@@quotation
+Permission is granted to @dots{}
+@@end quotation
+@@end copying
address@hidden group
+
address@hidden
+@@titlepage
+@@title @var{name-of-manual-when-printed}
+@@subtitle @var{subtitle-if-any}
+@@subtitle @var{second-subtitle}
+@@author @var{author}
address@hidden group
+
address@hidden
+@@c The following two commands
+@@c start the copyright page.
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
address@hidden group
+
+Published by @dots{}
+@@end titlepage
+
+@@c So the toc is printed in the right place.
+@@contents
+
+@@ifnottex
+@@node Top
+@@top @var{title}
+
+@@insertcopying
+@@end ifnottex
+
address@hidden
+@@menu
+* First Chapter:: Getting started @dots{}
+* Second Chapter:: @dots{}
+ @dots{}
+* Copying:: Your rights and freedoms.
+@@end menu
address@hidden group
+
address@hidden
+@@node First Chapter
+@@chapter First Chapter
+
+@@cindex first chapter
+@@cindex chapter, first
address@hidden
address@hidden group
address@hidden example
+
+
address@hidden Texinfo File Header
address@hidden Texinfo File Header
address@hidden Header for Texinfo files
address@hidden Texinfo file header
+
+Texinfo files start with at least three lines that provide Info and
address@hidden with necessary information. These are the @code{\input texinfo}
+line, the @code{@@settitle} line, and the @code{@@setfilename} line.
+
+Also, if you want to format just part of the Texinfo file, you must
+write the @code{@@settitle} and @code{@@setfilename} lines between
+start-of-header and end-of-header lines. The start- and end-of-header
+lines are optional, but they do no harm, so you might as well always
+include them.
+
+Any command that affects document formatting as a whole makes sense to
+include in the header. @code{@@synindex} (@pxref{synindex}), for
+instance, is another command often included in the header. @xref{GNU
+Sample Texts}, for complete sample texts.
+
+Thus, the beginning of a Texinfo file generally looks like this:
+
address@hidden
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename sample.info
+@@settitle Sample Manual 1.0
+@@c %**end of header
address@hidden group
address@hidden example
+
address@hidden
+* First Line:: The first line of a Texinfo file.
+* Start of Header:: Formatting a region requires this.
+* setfilename:: Tell Info the name of the Info file.
+* settitle:: Create a title for the printed work.
+* End of Header:: Formatting a region requires this.
address@hidden menu
+
+
address@hidden First Line
address@hidden The First Line of a Texinfo File
address@hidden First line of a Texinfo file
address@hidden Beginning line of a Texinfo file
address@hidden Header 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:
+
address@hidden
+\input texinfo @@c -*-texinfo-*-
address@hidden example
+
address@hidden
+This line serves two functions:
+
address@hidden
address@hidden
+When the file is processed by @TeX{}, the @samp{\input texinfo} command
+tells @TeX{} to load the macros needed for processing a Texinfo file.
+These are in a file called @file{texinfo.tex}, which should have been
+installed on your system along with either the @TeX{} or Texinfo
+software. @TeX{} uses the backslash, @samp{\}, to mark the beginning of
+a command, exactly as Texinfo uses @samp{@@}. The @file{texinfo.tex}
+file causes the switch from @samp{\} to @samp{@@}; before the switch
+occurs, @TeX{} requires @samp{\}, which is why it appears at the
+beginning of the file.
+
address@hidden
+When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode
+specification tells Emacs to use Texinfo mode.
address@hidden enumerate
+
+
address@hidden Start of Header
address@hidden Start of Header
address@hidden Start of header line
+
+A start-of-header line is a Texinfo comment that looks like this:
+
address@hidden
+@@c %**start of header
address@hidden example
+
+Write the start-of-header line on the second line of a Texinfo file.
+Follow the start-of-header line with @code{@@setfilename} and
address@hidden@@settitle} lines and, optionally, with other commands that
+globally affect the document formatting, such as @code{@@synindex} or
address@hidden@@footnotestyle}; and then by an end-of-header line (@pxref{End of
+Header}).
+
+The start- and end-of-header lines allow you to format only part of a
+Texinfo file for Info or printing. @xref{texinfo-format commands}.
+
+The odd string of characters, @samp{%**}, is to ensure that no other
+comment is accidentally taken for a start-of-header line. You can
+change it if you wish by setting the @code{tex-start-of-header} and/or
address@hidden Emacs variables. @xref{Texinfo Mode Printing}.
+
+
address@hidden setfilename
address@hidden @code{@@setfilename}: Set the output file name
address@hidden setfilename
address@hidden Texinfo requires @code{@@setfilename}
+
+In order to serve as the primary input file for either @code{makeinfo}
+or @TeX{}, a Texinfo file must contain a line that looks like this:
+
address@hidden
+@@setfilename @var{info-file-name}
address@hidden example
+
+Write the @code{@@setfilename} command at the beginning of a line and
+follow it on the same line by the Info file name. Do not write anything
+else on the line; anything on the line after the command is considered
+part of the file name, including what would otherwise be a
+comment.
+
address@hidden Ignored before @code{@@setfilename}
address@hidden @samp{\input} source line ignored
+The Info formatting commands ignore everything written before the
address@hidden@@setfilename} line, which is why the very first line of
+the file (the @code{\input} line) does not show up in the output.
+
+The @code{@@setfilename} line specifies the name of the output file to
+be generated. This name must be different from the name of the Texinfo
+file. There are two conventions for choosing the name: you can either
+remove the extension (such as @samp{.texi}) entirely from the input file
+name, or, preferably, replace it with the @samp{.info} extension.
+
address@hidden Length of file names
address@hidden File name collision
address@hidden Info file name, choosing
+Although an explicit @samp{.info} extension is preferable, some
+operating systems cannot handle long file names. You can run into a
+problem even when the file name you specify is itself short enough.
+This occurs because the Info formatters split a long Info file into
+short indirect subfiles, and name them by appending @samp{-1},
address@hidden, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original
+file name. (@xref{Tag and Split Files}.) The subfile name
address@hidden, for example, is too long for old systems with a
+14-character limit on filenames; so the Info file name for this document
+is @file{texinfo} rather than @file{texinfo.info}. When @code{makeinfo}
+is running on operating systems such as MS-DOS which impose severe
+limits on file names, it may remove some characters from the original
+file name to leave enough space for the subfile suffix, thus producing
+files named @file{texin-10}, @file{gcc.i12}, etc.
+
+When producing HTML output, @code{makeinfo} will replace any extension
+with @samp{html}, or add @samp{.html} if the given name has no
+extension.
+
address@hidden texinfo.cnf
+The @code{@@setfilename} line produces no output when you typeset a
+manual with @TeX{}, but it is nevertheless essential: it opens the
+index, cross-reference, and other auxiliary files used by Texinfo, and
+also reads @file{texinfo.cnf} if that file is present on your system
+(@pxref{Preparing for TeX,, Preparing for @TeX{}}).
+
+
address@hidden settitle
address@hidden @code{@@settitle}: Set the document title
address@hidden settitle
+
+In order to be made into a printed manual, a Texinfo file must contain
+a line that looks like this:
+
address@hidden
+@@settitle @var{title}
address@hidden example
+
+Write the @code{@@settitle} command at the beginning of a line and
+follow it on the same line by the title. This tells @TeX{} the title to
+use in a header or footer. Do not write anything else on the line;
+anything on the line after the command is considered part of the title,
+including what would otherwise be a comment.
+
+The @code{@@settitle} command should precede everything that generates
+actual output in @TeX{}.
+
address@hidden <title> HTML tag
+In the HTML file produced by @command{makeinfo}, @var{title} also serves
+as the document @samp{<title>} and the default document description in
+the @samp{<head>} part; see @ref{documentdescription}, for how to change
+that.
+
+The title in the @code{@@settitle} command does not affect the title as
+it appears on the title page. Thus, the two do not need not match
+exactly. A practice we recommend is to include the version or edition
+number of the manual in the @code{@@settitle} title; on the title page,
+the version number generally appears as a @code{@@subtitle} so it would
+be omitted from the @code{@@title}. (@xref{titlepage}.)
+
+Conventionally, when @TeX{} formats a Texinfo file for double-sided
+output, the title is printed in the left-hand (even-numbered) page
+headings and the current chapter title is printed in the right-hand
+(odd-numbered) page headings. (@TeX{} learns the title of each chapter
+from each @code{@@chapter} command.) By default, no page footer is
+printed.
+
+Even if you are printing in a single-sided style, @TeX{} looks for an
address@hidden@@settitle} command line, in case you include the manual title
+in the heading.
+
address@hidden prints page headings only for that text that comes after the
address@hidden@@end titlepage} command in the Texinfo file, or that comes
+after an @code{@@headings} command that turns on headings.
+(@xref{headings on off, , The @code{@@headings} Command}, for more
+information.)
+
+You may, if you wish, create your own, customized headings and footings.
address@hidden, for a detailed discussion of this.
+
+
address@hidden End of Header
address@hidden End of Header
address@hidden End of header line
+
+Follow the header lines with an @w{end-of-header} line, which is a
+Texinfo comment that looks like this:
+
address@hidden
+@@c %**end of header
address@hidden example
+
address@hidden of Header}.
+
+
address@hidden Document Permissions
address@hidden Document Permissions
address@hidden Document Permissions
address@hidden Copying Permissions
+
+The copyright notice and copying permissions for a document need to
+appear in several places in the various Texinfo output formats.
+Therefore, Texinfo provides a command (@code{@@copying}) to declare
+this text once, and another command (@code{@@insertcopying}) to
+insert the text at appropriate points.
+
address@hidden
+* copying:: Declare the document's copying permissions.
+* insertcopying:: Where to insert the permissions.
address@hidden menu
+
+
address@hidden copying
address@hidden @code{@@copying}: Declare copying permissions
address@hidden copying
+
+The @code{@@copying} command should be given very early in the document;
+right after the header material (@pxref{Texinfo File Header}) is the
+recommended location. It conventionally consists of a sentence or two
+about what the program is, the legal copyright line, and the copying
+permissions. Here is a skeletal example:
+
address@hidden
+@@copying
+This manual is for @var{program} (version @var{version}),
+which @dots{}
+
+Copyright @@address@hidden@} @var{years} @var{copyright-owner}.
+
+@@quotation
+Permission is granted to @dots{}
+@@end quotation
+@@end copying
address@hidden example
+
+The @code{@@quotation} has no legal significance; it's there to improve
+readability in some contexts.
+
address@hidden Sample Texts}, for the full text to be used in GNU manuals.
address@hidden Free Documentation License}, for the license itself under
+which GNU and other free manuals are distributed.
+
+The text of @code{@@copying} is output as a comment at the beginning of
+Info, HTML, and XML output files. It is @emph{not} output implicitly in
+plain text or @TeX{}; it's up to you to use @code{@@insertcopying} to
+emit the copying information. See the next section for details.
+
address@hidden copyright
+In output formats that support it (print and HTML), the
address@hidden@@address@hidden@}} command generates a @samp{c} inside a circle.
In
+Info and plain text, it generates @samp{(C)}. The copyright notice
+itself has the following legally defined sequence:
+
address@hidden
+Copyright @copyright{} @var{years} @var{copyright-owner}.
address@hidden example
+
address@hidden Copyright word, always in English
+The word `Copyright' must always be written in English, even if the
+manual is otherwise in another language. This is due to international
+law.
+
address@hidden Years, in copyright line
+The list of years should include all years in which a version was
+completed (even if it was released in a subsequent year). Ranges are
+not allowed, each year must be written out individually, separated by
+commas.
+
address@hidden Copyright owner for FSF works
+The copyright owner (or owners) is whoever holds legal copyright on the
+work. In the case of works assigned to the FSF, the owner is `Free
+Software Foundation, Inc.'.
+
address@hidden Notices,,,maintain,GNU Maintenance Instructions}, for
+additional information.
+
+
address@hidden insertcopying
address@hidden @code{@@insertcopying}: Include permissions text
address@hidden insertcopying
address@hidden Copying text, including
address@hidden Permissions text, including
address@hidden Including permissions text
+
+The @code{@@insertcopying} command is simply written on a line by
+itself, like this:
+
address@hidden
+@@insertcopying
address@hidden example
+
+It inserts the text previously defined by @code{@@copying}. Legally, it
+must be used on the copyright page in the printed manual
+(@pxref{Copyright}).
+
+Although it's not a legal requirement, we also strongly recommend using
address@hidden@@insertcopying} in the Top node of your manual (@pxref{The Top
+Node}). Here's why:
+
+The @code{@@copying} command itself causes the permissions text to
+appear in an Info file @emph{before} the first node. The text is also
+copied into the beginning of each split Info output file, as is legally
+necessary. This location implies a human reading the manual using Info
+does @emph{not} see this text (except when using the advanced Info
+command @kbd{g *}). Therefore, an explicit @code{@@insertcopying}
+in the Top node makes it apparent to readers that the manual is free.
+
+Similarly, the @code{@@copying} text is automatically included at the
+beginning of each HTML output file, as an HTML comment. Again, this
+text is not visible (unless the reader views the HTML source). And
+therefore again, the @code{@@insertcopying} in the Top node is valuable
+because it makes the copying permissions visible and thus promotes
+freedom.
+
+The permissions text defined by @code{@@copying} also appears
+automatically at the beginning of the XML output file.
+
+
address@hidden Titlepage & Copyright Page
address@hidden Title and Copyright Pages
+
+In hard copy output, the manual's name and author are usually printed on
+a title page. Copyright information is usually printed on the back of
+the title 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 several slightly
+obscure @TeX{} typesetting commands that cannot 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 appears in the printed manual.
+
address@hidden Title page, for plain text
address@hidden Copyright page, for plain text
+You may wish to include titlepage-like information for plain text
+output. Simply place any such leading material between
address@hidden@@ifplaintext} and @code{@@end ifplaintext}; @command{makeinfo}
+includes this when writing plain text (@samp{--no-headers}), along with
+an @code{@@insertcopying}.
+
address@hidden
+* titlepage:: Create a title for the printed document.
+* titlefont center sp:: The @code{@@titlefont}, @code{@@center},
+ and @code{@@sp} commands.
+* title subtitle author:: The @code{@@title}, @code{@@subtitle},
+ and @code{@@author} commands.
+* Copyright:: How to write the copyright notice and
+ include copying permissions.
+* end titlepage:: Turn on page headings after the title and
+ copyright pages.
+* headings on off:: An option for turning headings on and off
+ and double or single sided printing.
address@hidden menu
+
+
address@hidden titlepage
address@hidden @code{@@titlepage}
address@hidden Title page
address@hidden titlepage
+
+Start the material for the title page and following copyright page
+with @code{@@titlepage} on a line by itself and end it with
address@hidden@@end titlepage} on a line by itself.
+
+The @code{@@end titlepage} command starts a new page and turns on page
+numbering. (@xref{Headings, , Page Headings}, for details about how to
+generate page headings.) All the material that you want to appear on
+unnumbered pages should be put between the @code{@@titlepage} and
address@hidden@@end titlepage} commands. You can force the table of contents to
+appear there with the @code{@@setcontentsaftertitlepage} command
+(@pxref{Contents}).
+
address@hidden address@hidden, within @code{@@titlepage}}
+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 thereby create more than one unnumbered page. This is how
+the copyright page is produced. (The @code{@@titlepage} command might
+perhaps have been better named the @code{@@titleandadditionalpages}
+command, but that would have been rather long!)
+
+When you write a manual about a computer program, you should write the
+version of the program to which the manual applies on the title page.
+If the manual changes more frequently than the program or is independent
+of it, you should also include an edition address@hidden have found
+that it is helpful to refer to versions of independent manuals as
+`editions' and versions of programs as `versions'; otherwise, we find we
+are liable to confuse each other in conversation by referring to both
+the documentation and the software with the same words.} for the manual.
+This helps readers keep track of which manual is for which version of
+the program. (The `Top' node should also contain this information; see
address@hidden Top Node}.)
+
+Texinfo provides two main methods for creating a title page. One method
+uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands
+to generate a title page in which the words on the page are
+centered.
+
+The second method uses the @code{@@title}, @code{@@subtitle}, and
address@hidden@@author} commands to create a title page with black rules under
+the title and author lines and the subtitle text set flush to the
+right hand side of the page. With this method, you do not specify any
+of the actual formatting of the title page. You specify the text
+you want, and Texinfo does the formatting.
+
+You may use either method, or you may combine them; see the examples in
+the sections below.
+
address@hidden shorttitlepage
address@hidden Bastard title page
address@hidden Title page, bastard
+For extremely simple applications, and for the bastard title page in
+traditional book front matter, Texinfo also provides a command
address@hidden@@shorttitlepage} which takes the rest of the line as the title.
+The argument is typeset on a page by itself and followed by a blank
+page.
+
+
address@hidden titlefont center sp
address@hidden @code{@@titlefont}, @code{@@center}, and @code{@@sp}
address@hidden titlefont
address@hidden center
address@hidden sp @r{(titlepage line spacing)}
+
+You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center}
+commands to create a title page for a printed document. (This is the
+first of the two methods for creating a title page in Texinfo.)
+
+Use the @code{@@titlefont} command to select a large font suitable for
+the title itself. You can use @code{@@titlefont} more than once if you
+have an especially long title.
+
address@hidden 700
+For example:
+
address@hidden
+@@address@hidden@}
address@hidden example
+
+Use the @code{@@center} command at the beginning of a line to center
+the remaining text on that line. Thus,
+
address@hidden
+@@center @@address@hidden@}
address@hidden example
+
address@hidden
+centers the title, which in this example is ``Texinfo'' printed
+in the title font.
+
+Use the @code{@@sp} command to insert vertical space. For example:
+
address@hidden
+@@sp 2
address@hidden example
+
address@hidden
+This inserts two blank lines on the printed page. (@xref{sp, ,
address@hidden@@sp}}, for more information about the @code{@@sp}
+command.)
+
+A template for this method looks like this:
+
address@hidden
address@hidden
+@@titlepage
+@@sp 10
+@@center @@address@hidden@address@hidden
+@@sp 2
+@@center @var{subtitle-if-any}
+@@sp 2
+@@center @var{author}
address@hidden
+@@end titlepage
address@hidden group
address@hidden example
+
+The spacing of the example fits an 8.5 by 11 inch manual.
+
+
address@hidden title subtitle author
address@hidden @code{@@title}, @code{@@subtitle}, and @code{@@author}
address@hidden title
address@hidden subtitle
address@hidden author
+
+You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author}
+commands to create a title page in which the vertical and horizontal
+spacing is done for you automatically. This contrasts with the method
+described in the previous section, in which the @code{@@sp} command is
+needed to adjust vertical spacing.
+
+Write the @code{@@title}, @code{@@subtitle}, or @code{@@author}
+commands at the beginning of a line followed by the title, subtitle,
+or author.
+
+The @code{@@title} command produces a line in which the title is set
+flush to the left-hand side of the page in a larger than normal font.
+The title is underlined with a black rule. Only a single line is
+allowed; the @code{@@*} command may not be used to break the title into
+two lines. To handle very long titles, you may find it profitable to
+use both @code{@@title} and @code{@@titlefont}; see the final example in
+this section.
+
+The @code{@@subtitle} command sets subtitles in a normal-sized font
+flush to the right-hand side of the page.
+
+The @code{@@author} command sets the names of the author or authors in
+a middle-sized font flush to the left-hand side of the page on a line
+near the bottom of the title page. The names are underlined with a
+black rule that is thinner than the rule that underlines the title.
+(The black rule only occurs if the @code{@@author} command line is
+followed by an @code{@@page} command line.)
+
+There are two ways to use the @code{@@author} command: you can write
+the name or names on the remaining part of the line that starts with
+an @code{@@author} command:
+
address@hidden
+@@author by Jane Smith and John Doe
address@hidden example
+
address@hidden
+or you can write the names one above each other by using two (or more)
address@hidden@@author} commands:
+
address@hidden
address@hidden
+@@author Jane Smith
+@@author John Doe
address@hidden group
address@hidden example
+
address@hidden
+(Only the bottom name is underlined with a black rule.)
+
address@hidden 950
+A template for this method looks like this:
+
address@hidden
address@hidden
+@@titlepage
+@@title @var{name-of-manual-when-printed}
+@@subtitle @var{subtitle-if-any}
+@@subtitle @var{second-subtitle}
+@@author @var{author}
+@@page
address@hidden
+@@end titlepage
address@hidden group
address@hidden example
+
+You may also combine the @code{@@titlefont} method described in the
+previous section and @code{@@title} method described in this one. This
+may be useful if you have a very long title. Here is a real-life example:
+
address@hidden
address@hidden
+@@titlepage
+@@address@hidden address@hidden
+@@sp 1
+@@title for MS-Windows and MS-DOS
+@@subtitle Edition @@address@hidden@} for Release @@address@hidden@}
+@@author by Daniel Hagerty, Melissa Weisshaus
+@@author and Eli Zaretskii
address@hidden group
address@hidden example
+
address@hidden
+(The use of @code{@@value} here is explained in @ref{value Example}.
+
+
address@hidden Copyright
address@hidden Copyright Page
address@hidden Copyright page
address@hidden Printed permissions
address@hidden Permissions, printed
+
+By international treaty, the copyright notice for a book must be either
+on the title page or on the back of the title page. When the copyright
+notice is on the back of the title page, that page is customarily not
+numbered. Therefore, in Texinfo, the information on the copyright page
+should be within @code{@@titlepage} and @code{@@end titlepage}
+commands.
+
address@hidden vskip @address@hidden vertical skip}
address@hidden filll @address@hidden dimension}
+Use the @code{@@page} command to cause a page break. To push the
+copyright notice and the other text on the copyright page towards the
+bottom of the page, use the following incantantion after @code{@@page}:
+
address@hidden
+@@vskip 0pt plus 1filll
address@hidden example
+
address@hidden
+This is a @TeX{} command that is not supported by the Info formatting
+commands. The @code{@@vskip} command inserts whitespace. The @samp{0pt
+plus 1filll} means to put in zero points of mandatory whitespace, and as
+much optional whitespace as needed to push the following text to the
+bottom of the page. Note the use of three @samp{l}s in the word
address@hidden; this is correct.
+
+To insert the copyright text itself, write @code{@@insertcopying}
+next (@pxref{Document Permissions}):
+
address@hidden
+@@insertcopying
address@hidden example
+
+Follow the copying text by the publisher, ISBN numbers, cover art
+credits, and other such information.
+
+Here is an example putting all this together:
+
address@hidden
+@@titlepage
address@hidden
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
+
+Published by @dots{}
+
+Cover art by @dots{}
+@@end titlepage
address@hidden example
+
+
address@hidden end titlepage
address@hidden Heading Generation
address@hidden end titlepage
address@hidden Headings, page, begin to appear
address@hidden Titlepage end starts headings
address@hidden End titlepage starts headings
+
+The @code{@@end titlepage} command must be written on a line by itself.
+It not only marks the end of the title and copyright pages, but also
+causes @TeX{} to start generating page headings and page numbers.
+
+To repeat what is said elsewhere, Texinfo has two standard page heading
+formats, one for documents which are printed on one side of each sheet of paper
+(single-sided printing), and the other for documents which are printed on both
+sides of each sheet (double-sided printing).
+You can specify these formats in different ways:
+
address@hidden @bullet
address@hidden
+The conventional way is to write an @code{@@setchapternewpage} command
+before the title page commands, and then have the @code{@@end
+titlepage} command start generating page headings in the manner desired.
+(@xref{setchapternewpage}.)
+
address@hidden
+Alternatively, you can use the @code{@@headings} command to prevent page
+headings from being generated or to start them for either single or
+double-sided printing. (Write an @code{@@headings} command immediately
+after the @code{@@end titlepage} command. @xref{headings on off, , The
address@hidden@@headings} Command}, for more information.)@refill
+
address@hidden
+Or, you may specify your own page heading and footing format.
address@hidden, , Page Headings}, for detailed
+information about page headings and footings.
address@hidden itemize
+
+Most documents are formatted with the standard single-sided or
+double-sided format, using @code{@@setchapternewpage odd} for
+double-sided printing and no @code{@@setchapternewpage} command for
+single-sided printing.
+
+
address@hidden headings on off
address@hidden The @code{@@headings} Command
address@hidden headings
+
+The @code{@@headings} command is rarely used. It specifies what kind of
+page headings and footings to print on each page. Usually, this is
+controlled by the @code{@@setchapternewpage} command. You need the
address@hidden@@headings} command only if the @code{@@setchapternewpage} command
+does not do what you want, or if you want to turn off pre-defined page
+headings prior to defining your own. Write an @code{@@headings} command
+immediately after the @code{@@end titlepage} address@hidden
+
+You can use @code{@@headings} as follows:@refill
+
address@hidden @code
address@hidden @@headings off
+Turn off printing of page address@hidden
+
address@hidden @@headings single
+Turn on page headings appropriate for single-sided printing.
address@hidden
+
address@hidden @@headings double
address@hidden @@headings on
+Turn on page headings appropriate for double-sided printing. The two
+commands, @code{@@headings on} and @code{@@headings double}, are
address@hidden
+
address@hidden @@headings singleafter
address@hidden @@headings doubleafter
+Turn on @code{single} or @code{double} headings, respectively, after the
+current page is output.
+
address@hidden @@headings on
+Turn on page headings: @code{single} if @samp{@@setchapternewpage
+on}, @code{double} otherwise.
address@hidden table
+
+For example, suppose you write @code{@@setchapternewpage off} before the
address@hidden@@titlepage} command to tell @TeX{} to start a new chapter on the
+same page as the end of the last chapter. This command also causes
address@hidden to typeset page headers for single-sided printing. To cause
address@hidden to typeset for double sided printing, write @code{@@headings
+double} after the @code{@@end titlepage} command.
+
+You can stop @TeX{} from generating any page headings at all by
+writing @code{@@headings off} on a line of its own immediately after the
+line containing the @code{@@end titlepage} command, like this:@refill
+
address@hidden
+@@end titlepage
+@@headings off
address@hidden example
+
address@hidden
+The @code{@@headings off} command overrides the @code{@@end titlepage}
+command, which would otherwise cause @TeX{} to print page
address@hidden
+
+You can also specify your own style of page heading and footing.
address@hidden, , Page Headings}, for more address@hidden
+
+
address@hidden The Top Node
address@hidden The `Top' Node and Master Menu
address@hidden Top node
address@hidden Node, `Top'
+
+The `Top' node is the node in which a reader enters an Info manual. As
+such, it should begin with the @code{@@insertcopying} command
+(@pxref{Document Permissions}) to provide a brief description of the
+manual (including the version number) and copying permissions, and end
+with a master menu for the whole manual. Of course you should include
+any other general information you feel a reader would find helpful.
+
address@hidden top
+It is also conventional to write an @code{@@top} sectioning command line
+containing the title of the document immediately after the @code{@@node
+Top} line (@pxref{makeinfo top command, , The @code{@@top} Sectioning
+Command}).
+
+The contents of the `Top' node should appear only in the online output;
+none of it should appear in printed output, so enclose it between
address@hidden@@ifnottex} and @code{@@end ifnottex} commands. (@TeX{} does not
+print either an @code{@@node} line or a menu; they appear only in Info;
+strictly speaking, you are not required to enclose these parts between
address@hidden@@ifnottex} and @code{@@end ifnottext}, but it is simplest to do
+so. @xref{Conditionals, , Conditionally Visible Text}.)
+
address@hidden
+* Top Node Example::
+* Master Menu Parts::
address@hidden menu
+
+
address@hidden Top Node Example
address@hidden Top Node Example
+
address@hidden Top node example
+
+Here is an example of a Top node.
+
address@hidden
address@hidden
+@@ifnottex
+@@node Top
+@@top Sample Title
+
+@@insertcopying
address@hidden group
+
+Additional general information.
+
address@hidden
+@@menu
+* First Chapter::
+* Second Chapter::
address@hidden
+* Index::
address@hidden group
+@@end menu
address@hidden example
+
+
address@hidden Master Menu Parts
address@hidden Parts of a Master Menu
address@hidden Master menu
address@hidden Menu, master
address@hidden Parts of a master menu
+
+A @dfn{master menu} is a detailed main menu listing all the nodes in a
+file.
+
+A master menu is enclosed in @code{@@menu} and @code{@@end menu}
+commands and does not appear in the printed document.
+
+Generally, a master menu is divided into parts.
+
address@hidden @bullet
address@hidden
+The first part contains the major nodes in the Texinfo file: the nodes
+for the chapters, chapter-like sections, and the appendices.
+
address@hidden
+The second part contains nodes for the indices.
+
address@hidden
+The third and subsequent parts contain a listing of the other, lower
+level nodes, often ordered by chapter. This way, rather than go
+through an intermediary menu, an inquirer can go directly to a
+particular node when searching for specific information. These menu
+items are not required; add them if you think they are a
+convenience. If you do use them, put @code{@@detailmenu} before the
+first one, and @code{@@end detailmenu} after the last; otherwise,
address@hidden will get confused.
address@hidden itemize
+
+Each section in the menu can be introduced by a descriptive line. So
+long as the line does not begin with an asterisk, it will not be
+treated as a menu entry. (@xref{Writing a Menu}, for more
+information.)
+
+For example, the master menu for this manual looks like the following
+(but has many more entries):
+
address@hidden
address@hidden
+@@menu
+* Copying Conditions:: Your rights.
+* Overview:: Texinfo in brief.
address@hidden
address@hidden group
address@hidden
+* Command and Variable Index::
+* Concept Index::
address@hidden group
+
address@hidden
+@@detailmenu
+ --- The Detailed Node Listing ---
+
+Overview of Texinfo
+
+* Reporting Bugs:: @dots{}
address@hidden
address@hidden group
+
address@hidden
+Beginning a Texinfo File
+
+* Sample Beginning:: @dots{}
address@hidden
+@@end detailmenu
+@@end menu
address@hidden group
address@hidden example
+
+
address@hidden Global Document Commands
address@hidden Global Document Commands
address@hidden Global Document Commands
+
+Besides the basic commands mentioned in the previous sections, here are
+additional commands which affect the document as a whole. They are
+generally all given before the Top node, if they are given at all.
+
address@hidden
+* documentdescription:: Document summary for the HTML output.
+* setchapternewpage:: Start chapters on right-hand pages.
+* paragraphindent:: Specify paragraph indentation.
+* exampleindent:: Specify environment indentation.
address@hidden menu
+
+
address@hidden documentdescription
address@hidden @code{@@documentdescription}: Summary text
address@hidden Document description
address@hidden Description of document
address@hidden Summary of document
address@hidden Abstract of document
address@hidden <meta> HTML tag, and document description
address@hidden documentdescription
+
+When producing HTML output for a document, @command{makeinfo} writes a
address@hidden<meta>} element in the @samp{<head>} to give some idea of the
+content of the document. By default, this @dfn{description} is the title
+of the document, taken from the @code{@@settitle} command
+(@pxref{settitle}). To change this, use the @code{@@documentdescription}
+environment, as in:
+
address@hidden
+@@documentdescription
+descriptive text.
+@@end documentdescription
address@hidden example
+
address@hidden
+This will produce the following output in the @samp{<head>} of the HTML:
+
address@hidden
+<meta name=description content="descriptive text.">
address@hidden example
+
address@hidden@@documentdescription} must be specified before the first node of
+the document.
+
+
address@hidden setchapternewpage
address@hidden @code{@@setchapternewpage}:
address@hidden Starting chapters
address@hidden Pages, starting odd
address@hidden setchapternewpage
+
+In an officially bound book, text is usually printed on both sides of
+the paper, chapters start on right-hand pages, and right-hand pages have
+odd numbers. But in short reports, text often is printed only on one
+side of the paper. Also in short reports, chapters sometimes do not
+start on new pages, but are printed on the same page as the end of the
+preceding chapter, after a small amount of vertical whitespace.
+
+You can use the @code{@@setchapternewpage} command with various
+arguments to specify how @TeX{} should start chapters and whether it
+should format headers for printing on one or both sides of the paper
+(single-sided or double-sided printing).
+
+Write the @code{@@setchapternewpage} command at the beginning of a
+line followed by its argument.
+
+For example, you would write the following to cause each chapter to
+start on a fresh odd-numbered page:
+
address@hidden
+@@setchapternewpage odd
address@hidden example
+
+You can specify one of three alternatives with the
address@hidden@@setchapternewpage} command:
+
address@hidden @asis
+
address@hidden @code{@@setchapternewpage off}
+Cause @TeX{} to typeset a new chapter on the same page as the last
+chapter, after skipping some vertical whitespace. Also, cause @TeX{} to
+format page headers for single-sided printing.
+
address@hidden @code{@@setchapternewpage on}
+Cause @TeX{} to start new chapters on new pages and to format page
+headers for single-sided printing. This is the form most often used for
+short reports or personal printing. This is the default.
+
address@hidden @code{@@setchapternewpage odd}
+Cause @TeX{} to start new chapters on new, odd-numbered pages
+(right-handed pages) and to typeset for double-sided printing. This is
+the form most often used for books and manuals.
address@hidden table
+
+Texinfo does not have an @code{@@setchapternewpage even} command,
+because there is no printing tradition of starting chapters or books on
+an even-numbered page.
+
+If you don't like the default headers that @code{@@setchapternewpage}
+sets, you can explicit control them with the @code{@@headings} command.
address@hidden on off, , The @code{@@headings} Command}.
+
+At the beginning of a manual or book, pages are not numbered---for
+example, the title and copyright pages of a book are not numbered. By
+convention, table of contents and frontmatter pages are numbered with
+roman numerals and not in sequence with the rest of the document.
+
+Since an Info file does not have pages, the @code{@@setchapternewpage}
+command has no effect on it.
+
+We recommend not including any @code{@@setchapternewpage} command in
+your manual sources at all, since the desired output is not intrinsic to
+the document. For a particular hard copy run, if you don't want the
+default option (no blank pages, same headers on all pages) use the
address@hidden option to @command{texi2dvi} to specify the output
+you want.
+
+
address@hidden paragraphindent
address@hidden Paragraph Indenting
address@hidden Indenting paragraphs, control of
address@hidden Paragraph indentation control
address@hidden paragraphindent
+
+The Texinfo processors may insert whitespace at the beginning of the
+first line of each paragraph, thereby indenting that paragraph. You can
+use the @code{@@paragraphindent} command to specify this indentation.
+Write an @code{@@paragraphindent} command at the beginning of a line
+followed by either @samp{asis} or a number:
+
address@hidden
+@@paragraphindent @var{indent}
address@hidden example
+
+The indentation is according to the value of @var{indent}:
+
address@hidden @asis
address@hidden @code{asis}
+Do not change the existing indentation (not implemented in @TeX{}).
+
address@hidden @code{none}
address@hidden 0
+Omit all indentation.
+
address@hidden @var{n}
+Indent by @var{n} space characters in Info output, by @var{n} ems in
address@hidden
+
address@hidden table
+
+The default value of @var{indent} is 3. @code{@@paragraphindent} is
+ignored for HTML output.
+
+It is best to write the @code{@@paragraphindent} command before the
+end-of-header line at the beginning of a Texinfo file, so the region
+formatting commands indent paragraphs as specified. @xref{Start of
+Header}.
+
+A peculiarity of the @code{texinfo-format-buffer} and
address@hidden commands is that they do not indent (nor
+fill) paragraphs that contain @code{@@w} or @code{@@*} commands.
address@hidden Paragraphs}, for further information.
+
+
address@hidden exampleindent
address@hidden @code{@@exampleindent}: Environment Indenting
address@hidden Indenting environments
address@hidden Environment indentation
address@hidden Example indentation
address@hidden exampleindent
+
+The Texinfo processors indent each line of @code{@@example} and similar
+environments. You can use the @code{@@exampleindent} command to specify
+this indentation. Write an @code{@@exampleindent} command at the
+beginning of a line followed by either @samp{asis} or a number:
+
address@hidden
+@@exampleindent @var{indent}
address@hidden example
+
+The indentation is according to the value of @var{indent}:
+
address@hidden @asis
address@hidden @code{asis}
+Do not change the existing indentation (not implemented in @TeX{}).
+
address@hidden 0
+Omit all indentation.
+
address@hidden @var{n}
+Indent environments by @var{n} space characters in Info output, by
address@hidden ems in @TeX{}.
+
address@hidden table
+
+The default value of @var{indent} is 5. @code{@@exampleindent} is
+ignored for HTML output.
+
+It is best to write the @code{@@exampleindent} command before the
+end-of-header line at the beginning of a Texinfo file, so the region
+formatting commands indent paragraphs as specified. @xref{Start of
+Header}.
+
+
address@hidden Software Copying Permissions
address@hidden Software Copying Permissions
address@hidden Software copying permissions
address@hidden Copying software
address@hidden Distribution
address@hidden License agreement
+
+If the Texinfo file has a section containing the ``General Public
+License'' and the distribution information and a warranty disclaimer for
+the software that is documented, we recommend placing this right after
+the `Top' node. The General Public License is very important to Project
+GNU software. It ensures that you and others will continue to have a
+right to use and share the software.
+
+The copying and distribution information and the disclaimer are followed
+by an introduction or else by the first chapter of the manual.
+
address@hidden Introduction, as part of file
+Although an introduction 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, an introduction would follow the licensing and distribution
+information, although sometimes people put it earlier in the document.
+
+
address@hidden Ending a File
address@hidden Ending a Texinfo File
address@hidden Ending a Texinfo file
address@hidden Texinfo file ending
address@hidden File ending
address@hidden bye
+
+The end of a Texinfo file should include commands to create indices and
+(perhaps) to generate both the full and summary tables of contents.
+Finally, it must include the @code{@@bye} command that marks the last
+line to be processed.
+
address@hidden 700
+For example:
+
address@hidden
+@@node Index
+@@unnumbered Index
+
+@@printindex cp
+
+@@shortcontents
+@@contents
+
+@@bye
address@hidden example
+
address@hidden
+* Printing Indices & Menus:: How to print an index in hardcopy and
+ generate index menus in Info.
+* Contents:: How to create a table of contents.
+* File End:: How to mark the end of a file.
address@hidden menu
+
+
address@hidden Printing Indices & Menus
address@hidden Printing Indices and Menus
address@hidden printindex
address@hidden Printing an index
address@hidden Indices, printing and menus
address@hidden Generating menus with indices
address@hidden Menus generated with indices
+
+To print an index means to include it as part of a manual or Info file.
+This does not happen automatically just because you use @code{@@cindex}
+or other index-entry generating commands in the Texinfo file; those just
+cause the raw data for the index to be accumulated. To generate an
+index, you must include the @code{@@printindex} command at the place in
+the document where you want the index to appear. Also, as part of the
+process of creating a printed manual, you must run a program called
address@hidden (@pxref{Hardcopy}) to sort the raw data to produce a
+sorted index file. The sorted index file is what is actually used to
+print the index.
+
+Texinfo offers six separate types of predefined index, each with a
+two-letter abbreviation, as illustrated in the following table.
+However, you may merge indices (@pxref{Combining Indices}) or define
+your own indices (@pxref{New Indices}).
+
+Here are the predefined indices, their abbreviations, and the
+corresponding index entry commands:
+
address@hidden @samp
address@hidden cp
+concept index (@code{@@cindex})
address@hidden fn
+function index (@code{@@findex})
address@hidden vr
+variable index (@code{@@index})
address@hidden ky
+key index (@code{@@kindex})
address@hidden pg
+program index (@code{@@pindex})
address@hidden tp
+data type index (@code{@@tindex})
address@hidden table
+
+The @code{@@printindex} command takes a two-letter index abbreviation,
+reads the corresponding sorted index file and formats it appropriately
+into an index.
+
+The @code{@@printindex} command does not generate a chapter heading for
+the index. Consequently, you should precede the @code{@@printindex}
+command with a suitable section or chapter command (usually
address@hidden@@appendix} or @code{@@unnumbered}) to supply the chapter heading
+and put the index into the table of contents. Precede the
address@hidden@@unnumbered} command with an @code{@@node} line.
+
+For example:
+
address@hidden
address@hidden
+@@node Variable Index
+@@unnumbered Variable Index
+
+@@printindex vr
address@hidden group
+
address@hidden
+@@node Concept Index
+@@unnumbered Concept Index
+
+@@printindex cp
address@hidden group
address@hidden smallexample
+
address@hidden
+
+We recommend placing the concept index last, since that makes it easiest
+to find. We also recommend having a single index whenever possible,
+since then readers have only one place to look (@pxref{Combining Indices}).
+
+
address@hidden Contents
address@hidden Generating a Table of Contents
address@hidden Table of contents
address@hidden Contents, Table of
address@hidden Short table of contents
address@hidden contents
address@hidden summarycontents
address@hidden shortcontents
+
+The @code{@@chapter}, @code{@@section}, and other structuring commands
+supply the information to make up a table of contents, but they do not
+cause an actual table to appear in the manual. To do this, you must use
+the @code{@@contents} and/or @code{@@summarycontents} command(s).
+
address@hidden @code
address@hidden @@contents
+Generate a table of contents in a printed manual, including all
+chapters, sections, subsections, etc., as well as appendices and
+unnumbered chapters. Headings generated by the @code{@@heading}
+series of commands do not appear in the table of contents.
+
address@hidden @@shortcontents
address@hidden @@summarycontents
+(@code{@@summarycontents} is a synonym for @code{@@shortcontents}.)
+
+Generate a short or summary table of contents that lists only the
+chapters, appendices, and unnumbered chapters. Sections, subsections
+and subsubsections are omitted. Only a long manual needs a short table
+of contents in addition to the full table of contents.
+
address@hidden table
+
+Both contents commands should be written on a line by themselves.
+The contents commands automatically generate a chapter-like heading at
+the top of the first table of contents page, so don't include any
+sectioning command such as @code{@@unnumbered} before them.
+
+Since an Info file uses menus instead of tables of contents, the Info
+formatting commands ignore the contents commands. But the contents are
+included in plain text output (generated by @code{makeinfo
+--no-headers}), unless @code{makeinfo} is writing its output to standard
+output.
+
+When @code{makeinfo} writes a short table of contents while producing
+html output, the links in the short table of contents point to
+corresponding entries in the full table of contents rather than the text
+of the document. The links in the full table of contents point to the
+main text of the document.
+
+The contents commands can be placed either at the very end of the file,
+after any indices (see the previous section) and just before the
address@hidden@@bye} (see the next section), or near the beginning of the file,
+after the @code{@@end titlepage} (@pxref{titlepage}). The advantage to
+the former is that then the contents output is always up to date,
+because it reflects the processing just done. The advantage to the
+latter is that the contents are printed in the proper place, thus you do
+not need to rearrange the DVI file with @command{dviselect} or shuffle
+paper.
+
address@hidden setcontentsaftertitlepage
address@hidden setshortcontentsaftertitlepage
address@hidden Contents, after title page
address@hidden Table of contents, after title page
+As an author, you can put the contents commands wherever you prefer.
+But if you are a user simply printing a manual, you may wish to print
+the contents after the title page even if the author put the contents
+commands at the end of the document (as is the case in most existing
+Texinfo documents, at this writing). You can do this by specifying
address@hidden@@setcontentsaftertitlepage} and/or
address@hidden@@setshortcontentsaftertitlepage}. The first prints only the main
+contents after the @code{@@end titlepage}; the second prints both the
+short contents and the main contents. In either case, any subsequent
address@hidden@@contents} or @code{@@shortcontents} is ignored (unless no
address@hidden@@end titlepage} is ever encountered).
+
+You need to include the @code{@@address@hidden
+commands early in the document (just after @code{@@setfilename}, for
+example). We recommend using @command{texi2dvi} (@pxref{Format with
+texi2dvi}) to specify this without altering the source file at all. For
+example:
address@hidden
+texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi
address@hidden example
+
+
address@hidden File End
address@hidden @code{@@bye} File Ending
address@hidden bye
+
+An @code{@@bye} command terminates @TeX{} or Info formatting. None of
+the formatting commands reading anything following @code{@@bye}. The
address@hidden@@bye} command should be on a line by itself.
+
+If you wish, you may follow the @code{@@bye} line with notes. These
+notes will not be formatted and will not appear in either Info or a
+printed manual; it is as if text after @code{@@bye} were within
address@hidden@@ignore} @dots{} @code{@@end ignore}. Also, you may follow the
address@hidden@@bye} line with a local variables list for Emacs.
address@hidden, , Using Local Variables and the Compile Command},
+for more information.
+
+
address@hidden Structuring
address@hidden Chapter Structuring
address@hidden Chapter structuring
address@hidden Structuring of chapters
+
+The @dfn{chapter structuring} commands divide a document into a hierarchy of
+chapters, sections, subsections, and subsubsections. These commands
+generate large headings; they also provide information for the table
+of contents of a printed manual (@pxref{Contents, , Generating a Table
+of Contents})address@hidden
+
+The chapter structuring commands do not create an Info node structure,
+so normally you should put an @code{@@node} command immediately before
+each chapter structuring command (@pxref{Nodes}). The only time you
+are likely to use the chapter structuring commands without using the
+node structuring commands is if you are writing a document that
+contains no cross references and will never be transformed into Info
address@hidden
+
+It is unlikely that you will ever write a Texinfo file that is
+intended only as an Info file and not as a printable document. If you
+do, you might still use chapter structuring commands to create a
+heading at the top of each node---but you don't need address@hidden
+
address@hidden
+* Tree Structuring:: A manual is like an upside down tree @dots{}
+* Structuring Command Types:: How to divide a manual into parts.
+* makeinfo top:: The @code{@@top} command, part of the `Top'
node.
+* chapter::
+* unnumbered & appendix::
+* majorheading & chapheading::
+* section::
+* unnumberedsec appendixsec heading::
+* subsection::
+* unnumberedsubsec appendixsubsec subheading::
+* subsubsection:: Commands for the lowest level sections.
+* Raise/lower sections:: How to change commands' hierarchical level.
address@hidden menu
+
+
address@hidden Tree Structuring
address@hidden Tree Structure of Sections
address@hidden Tree structuring
+
+A Texinfo file is usually structured like a book with chapters,
+sections, subsections, and the like. This structure can be visualized
+as a tree (or rather as an upside-down tree) with the root at the top
+and the levels corresponding to chapters, sections, subsection, and
address@hidden
+
+Here is a diagram that shows a Texinfo file with three chapters,
+each of which has two address@hidden
+
address@hidden
address@hidden
+ Top
+ |
+ -------------------------------------
+ | | |
+ Chapter 1 Chapter 2 Chapter 3
+ | | |
+ -------- -------- --------
+ | | | | | |
+ Section Section Section Section Section Section
+ 1.1 1.2 2.1 2.2 3.1 3.2
+
address@hidden group
address@hidden example
+
+In a Texinfo file that has this structure, the beginning of Chapter 2
+looks like this:@refill
+
address@hidden
address@hidden
+@@node Chapter 2, Chapter 3, Chapter 1, top
+@@chapter Chapter 2
address@hidden group
address@hidden example
+
+The chapter structuring commands are described in the sections that
+follow; the @code{@@node} and @code{@@menu} commands are described in
+following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill
+
+
address@hidden Structuring Command Types
address@hidden Structuring Command Types
+
+The chapter structuring commands fall into four groups or series, each
+of which contains structuring commands corresponding to the
+hierarchical levels of chapters, sections, subsections, and
address@hidden
+
+The four groups are the @code{@@chapter} series, the
address@hidden@@unnumbered} series, the @code{@@appendix} series, and the
address@hidden@@heading} address@hidden
+
+Each command produces titles that have a different appearance on the
+printed page or Info file; only some of the commands produce
+titles that are listed in the table of contents of a printed book or
address@hidden
+
address@hidden @bullet
address@hidden
+The @code{@@chapter} and @code{@@appendix} series of commands produce
+numbered or lettered entries both in the body of a printed work and in
+its table of address@hidden
+
address@hidden
+The @code{@@unnumbered} series of commands produce unnumbered entries
+both in the body of a printed work and in its table of contents. The
address@hidden@@top} command, which has a special use, is a member of this
+series (@pxref{makeinfo top, , @code{@@top}})address@hidden
+
address@hidden
+The @code{@@heading} series of commands produce unnumbered headings
+that do not appear in a table of contents. The heading commands never
+start a new address@hidden
+
address@hidden
+The @code{@@majorheading} command produces results similar to using
+the @code{@@chapheading} command but generates a larger vertical
+whitespace before the address@hidden
+
address@hidden
+When an @code{@@setchapternewpage} command says to do so, the
address@hidden@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands
+start new pages in the printed manual; the @code{@@heading} commands
+do address@hidden
address@hidden itemize
+
+Here are the four groups of chapter structuring commands:
+
address@hidden
+{\globaldefs = 1 \smallfonts}
address@hidden tex
+
address@hidden @columnfractions .19 .30 .29 .22
address@hidden @tab @tab
@tab No new page
address@hidden @i{Numbered} @tab @i{Unnumbered} @tab
@i{Lettered/numbered} @tab @i{Unnumbered}
address@hidden In contents @tab In contents @tab In
contents @tab Omitted address@hidden
address@hidden @tab @code{@@top} @tab
@tab @code{@@majorheading}
address@hidden @code{@@chapter} @tab @code{@@unnumbered} @tab
@code{@@appendix} @tab @code{@@chapheading}
address@hidden @code{@@section} @tab @code{@@unnumberedsec} @tab
@code{@@appendixsec} @tab @code{@@heading}
address@hidden @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab
@code{@@appendixsubsec} @tab @code{@@subheading}
address@hidden @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab
@code{@@appendixsubsubsec} @tab @code{@@subsubheading}
address@hidden multitable
address@hidden
+{\globaldefs = 1 \textfonts}
address@hidden tex
+
+
address@hidden makeinfo top
address@hidden @code{@@top}
+
+The @code{@@top} command is a special sectioning command that you use
+only after an @samp{@@node Top} line at the beginning of a Texinfo file.
+The @code{@@top} command tells the @code{makeinfo} formatter which node
+is the `Top' node, so it can use it as the root of the node tree if your
+manual uses implicit pointers. It has the same typesetting effect as
address@hidden@@unnumbered} (@pxref{unnumbered & appendix, , @code{@@unnumbered}
+and @code{@@appendix}}). For detailed information, see @ref{makeinfo
+top command, , The @code{@@top} Command}.
+
+The @code{@@top} node and its menu (if any) is conventionally wrapped in
+an @code{@@ifnottex} conditional so that it will appear only in Info and
+HTML output, not @TeX{}.
+
+
address@hidden chapter, unnumbered & appendix, makeinfo top, Structuring
address@hidden node-name, next, previous, up
address@hidden @code{@@chapter}
address@hidden chapter
+
address@hidden@@chapter} identifies a chapter in the document. Write the
+command at the beginning of a line and follow it on the same line by
+the title of the address@hidden
+
+For example, this chapter in this manual is entitled ``Chapter
+Structuring''; the @code{@@chapter} line looks like this:@refill
+
address@hidden
+@@chapter Chapter Structuring
address@hidden example
+
+In @TeX{}, the @code{@@chapter} command creates a chapter in the
+document, specifying the chapter title. The chapter is numbered
address@hidden
+
+In Info, the @code{@@chapter} command causes the title to appear on a
+line by itself, with a line of asterisks inserted underneath. Thus,
+in Info, the above example produces the following output:@refill
+
address@hidden
+Chapter Structuring
+*******************
address@hidden example
+
address@hidden centerchap
+Texinfo also provides a command @code{@@centerchap}, which is analogous
+to @code{@@unnumbered}, but centers its argument in the printed output.
+This kind of stylistic choice is not usually offered by Texinfo.
address@hidden but the Hacker's Dictionary wanted it ...
+
+
address@hidden unnumbered & appendix
address@hidden @code{@@unnumbered} and @code{@@appendix}
address@hidden unnumbered
address@hidden appendix
+
+Use the @code{@@unnumbered} command to create a chapter that appears
+in a printed manual without chapter numbers of any kind. Use the
address@hidden@@appendix} command to create an appendix in a printed manual
+that is labelled by letter instead of by address@hidden
+
+For Info file output, the @code{@@unnumbered} and @code{@@appendix}
+commands are equivalent to @code{@@chapter}: the title is printed on a
+line by itself with a line of asterisks underneath. (@xref{chapter, ,
address@hidden@@chapter}}.)@refill
+
+To create an appendix or an unnumbered chapter, write an
address@hidden@@appendix} or @code{@@unnumbered} command at the beginning of a
+line and follow it on the same line by the title, as you would if you
+were creating a address@hidden
+
+
address@hidden majorheading & chapheading, section, unnumbered & appendix,
Structuring
address@hidden @code{@@majorheading}, @code{@@chapheading}
address@hidden majorheading
address@hidden chapheading
+
+The @code{@@majorheading} and @code{@@chapheading} commands put
+chapter-like headings in the body of a address@hidden
+
+However, neither command causes @TeX{} to produce a numbered heading
+or an entry in the table of contents; and neither command causes
address@hidden to start a new page in a printed address@hidden
+
+In @TeX{}, an @code{@@majorheading} command generates a larger vertical
+whitespace before the heading than an @code{@@chapheading} command but
+is otherwise the address@hidden
+
+In Info,
+the @code{@@majorheading} and
address@hidden@@chapheading} commands are equivalent to
address@hidden@@chapter}: the title is printed on a line by itself with a line
+of asterisks underneath. (@xref{chapter, , @code{@@chapter}}.)@refill
+
address@hidden section, unnumberedsec appendixsec heading, majorheading &
chapheading, Structuring
address@hidden node-name, next, previous, up
address@hidden @code{@@section}
address@hidden section
+
+In a printed manual, an @code{@@section} command identifies a
+numbered section within a chapter. The section title appears in the
+table of contents. In Info, an @code{@@section} command provides a
+title for a segment of text, underlined with @address@hidden
+
+This section is headed with an @code{@@section} command and looks like
+this in the Texinfo file:@refill
+
address@hidden
+@@section @@address@hidden@@@@address@hidden
address@hidden example
+
+To create a section, write the @code{@@section} command at the
+beginning of a line and follow it on the same line by the section
address@hidden
+
+Thus,
+
address@hidden
+@@section This is a section
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+This is a section
+=================
address@hidden group
address@hidden example
+
address@hidden
+in Info.
+
address@hidden unnumberedsec appendixsec heading, subsection, section,
Structuring
address@hidden node-name, next, previous, up
address@hidden @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
address@hidden unnumberedsec
address@hidden appendixsec
address@hidden heading
+
+The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading}
+commands are, respectively, the unnumbered, appendix-like, and
+heading-like equivalents of the @code{@@section} command.
+(@xref{section, , @code{@@section}}.)@refill
+
address@hidden @code
address@hidden @@unnumberedsec
+The @code{@@unnumberedsec} command may be used within an
+unnumbered chapter or within a regular chapter or appendix to
+provide an unnumbered address@hidden
+
address@hidden @@appendixsec
address@hidden @@appendixsection
address@hidden@@appendixsection} is a longer spelling of the
address@hidden@@appendixsec} command; the two are address@hidden
address@hidden appendixsection
+
+Conventionally, the @code{@@appendixsec} or @code{@@appendixsection}
+command is used only within address@hidden
+
address@hidden @@heading
+You may use the @code{@@heading} command anywhere you wish for a
+section-style heading that will not appear in the table of address@hidden
address@hidden table
+
address@hidden subsection, unnumberedsubsec appendixsubsec subheading,
unnumberedsec appendixsec heading, Structuring
address@hidden node-name, next, previous, up
address@hidden The @code{@@subsection} Command
address@hidden subsection
+
+Subsections are to sections as sections are to chapters.
+(@xref{section, , @code{@@section}}.) In Info, subsection titles are
+underlined with @samp{-}. For example,@refill
+
address@hidden
+@@subsection This is a subsection
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+This is a subsection
+--------------------
address@hidden group
address@hidden example
+
+In a printed manual, subsections are listed in the table of contents
+and are numbered three levels address@hidden
+
address@hidden unnumberedsubsec appendixsubsec subheading, subsubsection,
subsection, Structuring
address@hidden node-name, next, previous, up
address@hidden The @code{@@subsection}-like Commands
address@hidden Subsection-like commands
address@hidden unnumberedsubsec
address@hidden appendixsubsec
address@hidden subheading
+
+The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and
address@hidden@@subheading} commands are, respectively, the unnumbered,
+appendix-like, and heading-like equivalents of the @code{@@subsection}
+command. (@xref{subsection, , @code{@@subsection}}.)@refill
+
+In Info, the @code{@@subsection}-like commands generate a title
+underlined with hyphens. In a printed manual, an @code{@@subheading}
+command produces a heading like that of a subsection except that it is
+not numbered and does not appear in the table of contents. Similarly,
+an @code{@@unnumberedsubsec} command produces an unnumbered heading like
+that of a subsection and an @code{@@appendixsubsec} command produces a
+subsection-like heading labelled with a letter and numbers; both of
+these commands produce headings that appear in the table of
address@hidden
+
address@hidden subsubsection, Raise/lower sections, unnumberedsubsec
appendixsubsec subheading, Structuring
address@hidden node-name, next, previous, up
address@hidden The `subsub' Commands
address@hidden Subsub commands
address@hidden subsubsection
address@hidden unnumberedsubsubsec
address@hidden appendixsubsubsec
address@hidden subsubheading
+
+The fourth and lowest level sectioning commands in Texinfo are the
+`subsub' commands. They are:@refill
+
address@hidden @code
address@hidden @@subsubsection
+Subsubsections are to subsections as subsections are to sections.
+(@xref{subsection, , @code{@@subsection}}.) In a printed manual,
+subsubsection titles appear in the table of contents and are numbered
+four levels address@hidden
+
address@hidden @@unnumberedsubsubsec
+Unnumbered subsubsection titles appear in the table of contents of a
+printed manual, but lack numbers. Otherwise, unnumbered
+subsubsections are the same as subsubsections. In Info, unnumbered
+subsubsections look exactly like ordinary address@hidden
+
address@hidden @@appendixsubsubsec
+Conventionally, appendix commands are used only for appendices and are
+lettered and numbered appropriately in a printed manual. They also
+appear in the table of contents. In Info, appendix subsubsections look
+exactly like ordinary address@hidden
+
address@hidden @@subsubheading
+The @code{@@subsubheading} command may be used anywhere that you need
+a small heading that will not appear in the table of contents. In
+Info, subsubheadings look exactly like ordinary subsubsection
address@hidden
address@hidden table
+
+In Info, `subsub' titles are underlined with periods.
+For example,@refill
+
address@hidden
+@@subsubsection This is a subsubsection
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+This is a subsubsection
+.......................
address@hidden group
address@hidden example
+
address@hidden Raise/lower sections, , subsubsection, Structuring
address@hidden node-name, next, previous, up
address@hidden @code{@@raisesections} and @code{@@lowersections}
address@hidden raisesections
address@hidden lowersections
address@hidden Raising and lowering sections
address@hidden Sections, raising and lowering
+
+The @code{@@raisesections} and @code{@@lowersections} commands raise and
+lower the hierarchical level of chapters, sections, subsections and the
+like. The @code{@@raisesections} command changes sections to chapters,
+subsections to sections, and so on. The @code{@@lowersections} command
+changes chapters to sections, sections to subsections, and so on.
+
address@hidden Include files, and section levels
+An @code{@@lowersections} command is useful if you wish to include text
+that is written as an outer or standalone Texinfo file in another
+Texinfo file as an inner, included file. If you write the command at
+the beginning of the file, all your @code{@@chapter} commands are
+formatted as if they were @code{@@section} commands, all your
address@hidden@@section} command are formatted as if they were
address@hidden@@subsection} commands, and so on.
+
address@hidden 1000
address@hidden@@raisesections} raises a command one level in the chapter
+structuring hierarchy:@refill
+
address@hidden
address@hidden
+ @r{Change} @r{To}
+
+@@subsection @@section,
+@@section @@chapter,
+@@heading @@chapheading,
+ @r{etc.}
address@hidden group
address@hidden example
+
address@hidden 1000
address@hidden@@lowersections} lowers a command one level in the chapter
+structuring hierarchy:@refill
+
address@hidden
address@hidden
+ @r{Change} @r{To}
+
+@@chapter @@section,
+@@subsection @@subsubsection,
+@@heading @@subheading,
+ @r{etc.}
address@hidden group
address@hidden example
+
+An @code{@@raisesections} or @code{@@lowersections} command changes only
+those structuring commands that follow the command in the Texinfo file.
+Write an @code{@@raisesections} or @code{@@lowersections} command on a
+line of its own.
+
+An @code{@@lowersections} command cancels an @code{@@raisesections}
+command, and vice versa. Typically, the commands are used like this:
+
address@hidden
+@@lowersections
+@@include somefile.texi
+@@raisesections
address@hidden example
+
+Without the @code{@@raisesections}, all the subsequent sections in your
+document will be lowered.
+
+Repeated use of the commands continue to raise or lower the hierarchical
+level a step at a time.
+
+An attempt to raise above `chapters' reproduces chapter commands; an
+attempt to lower below `subsubsections' reproduces subsubsection
+commands.
+
address@hidden Nodes
address@hidden Nodes
+
address@hidden are the primary segments of a Texinfo file. They do not
+themselves impose a hierarchical or any other kind of structure on a file.
+Nodes contain @dfn{node pointers} that name other nodes, and can contain
address@hidden which are lists of nodes. In Info, the movement commands
+can carry you to a pointed-to node or to a node listed in a menu. Node
+pointers and menus provide structure for Info files just as chapters,
+sections, subsections, and the like, provide structure for printed
address@hidden
+
address@hidden
+* Two Paths:: Different commands to structure
+ Info output and printed output.
+* Node Menu Illustration:: A diagram, and sample nodes and menus.
+* node:: Creating nodes, in detail.
+* makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
+* anchor:: Defining arbitrary cross-reference targets.
address@hidden menu
+
+
address@hidden Two Paths
address@hidden Two Paths
+
+The node and menu commands and the chapter structuring commands are
+technically independent of each other:
+
address@hidden @bullet
address@hidden
+In Info, node and menu commands provide structure. The chapter
+structuring commands generate headings with different kinds of
+underlining---asterisks for chapters, hyphens for sections, and so on;
+they do nothing address@hidden
+
address@hidden
+In @TeX{}, the chapter structuring commands generate chapter and section
+numbers and tables of contents. The node and menu commands provide
+information for cross references; they do nothing address@hidden
address@hidden itemize
+
+You can use node pointers and menus to structure an Info file any way
+you want; and you can write a Texinfo file so that its Info output has a
+different structure than its printed output. However, virtually all
+Texinfo files are written such that the structure for the Info output
+corresponds to the structure for the printed output. It is neither
+convenient nor understandable to the reader to do address@hidden
+
+Generally, printed output is structured in a tree-like hierarchy in
+which the chapters are the major limbs from which the sections branch
+out. Similarly, node pointers and menus are organized to create a
+matching structure in the Info address@hidden
+
+
address@hidden Node Menu Illustration
address@hidden Node and Menu Illustration
+
+Here is a copy of the diagram shown earlier that illustrates a Texinfo
+file with three chapters, each of which contains two address@hidden
+
+The ``root'' is at the top of the diagram and the ``leaves'' are at the
+bottom. This is how such a diagram is drawn conventionally; it
+illustrates an upside-down tree. For this reason, the root node is
+called the `Top' node, and `Up' node pointers carry you closer to the
address@hidden
+
address@hidden
address@hidden
+ Top
+ |
+ -------------------------------------
+ | | |
+ Chapter 1 Chapter 2 Chapter 3
+ | | |
+ -------- -------- --------
+ | | | | | |
+ Section Section Section Section Section Section
+ 1.1 1.2 2.1 2.2 3.1 3.2
address@hidden group
address@hidden example
+
+The fully-written command to start Chapter 2 would be this:
+
address@hidden
address@hidden
+@@node Chapter 2, Chapter 3, Chapter 1, Top
+@@comment node-name, next, previous, up
address@hidden group
address@hidden example
+
address@hidden
+This @code{@@node} line says that the name of this node is ``Chapter
+2'', the name of the `Next' node is ``Chapter 3'', the name of the
+`Previous' node is ``Chapter 1'', and the name of the `Up' node is
+``Top''. You can omit writing out these node names if your document is
+hierarchically organized (@pxref{makeinfo Pointer Creation}), but the
+pointer relationships still obtain.
+
address@hidden
address@hidden Note:} `Next' refers to the next node at the same
+hierarchical level in the manual, not necessarily to the next node
+within the Texinfo file. In the Texinfo file, the subsequent node may
+be at a lower level---a section-level node most often follows a
+chapter-level node, for example. `Next' and `Previous' refer to nodes
+at the @emph{same} hierarchical level. (The `Top' node contains the
+exception to this rule. Since the `Top' node is the only node at that
+level, `Next' refers to the first following node, which is almost always
+a chapter or chapter-level node.)@refill
address@hidden quotation
+
+To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter
+2. (@xref{Menus}.) You would write the menu just
+before the beginning of Section 2.1, like this:@refill
+
address@hidden
address@hidden
+ @@menu
+ * Sect. 2.1:: Description of this section.
+ * Sect. 2.2::
+ @@end menu
address@hidden group
address@hidden example
+
+Write the node for Sect. 2.1 like this:@refill
+
address@hidden
address@hidden
+ @@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
+ @@comment node-name, next, previous, up
address@hidden group
address@hidden example
+
+In Info format, the `Next' and `Previous' pointers of a node usually
+lead to other nodes at the same level---from chapter to chapter or from
+section to section (sometimes, as shown, the `Previous' pointer points
+up); an `Up' pointer usually leads to a node at the level above (closer
+to the `Top' node); and a `Menu' leads to nodes at a level below (closer
+to `leaves'). (A cross reference can point to a node at any level;
+see @ref{Cross References}.)@refill
+
+Usually, an @code{@@node} command and a chapter structuring command are
+used in sequence, along with indexing commands. (You may follow the
address@hidden@@node} line with a comment line that reminds you which pointer is
+which.)@refill
+
+Here is the beginning of the chapter in this manual called ``Ending a
+Texinfo File''. This shows an @code{@@node} line followed by a comment
+line, an @code{@@chapter} line, and then by indexing address@hidden
+
address@hidden
address@hidden
+@@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
address@hidden group
address@hidden example
+
+
address@hidden node
address@hidden The @code{@@node} Command
+
address@hidden Node, defined
address@hidden node
+
+A @dfn{node} is a segment of text that begins at an @code{@@node}
+command and continues until the next @code{@@node} command. The
+definition of node is different from that for chapter or section. A
+chapter may contain sections and a section may contain subsections;
+but a node cannot contain subnodes; the text of a node continues only
+until the next @code{@@node} command in the file. A node usually
+contains only one chapter structuring command, the one that follows
+the @code{@@node} line. On the other hand, in printed output nodes
+are used only for cross references, so a chapter or section may
+contain any number of nodes. Indeed, a chapter usually contains
+several nodes, one for each section, subsection, and
address@hidden
+
+To create a node, write an @code{@@node} command at the beginning of a
+line, and follow it with up to four arguments, separated by commas, on
+the rest of the same line. The first argument is required; it is the
+name of this node. The subsequent arguments are the names of the
+`Next', `Previous', and `Up' pointers, in that order, and may be omitted
+if your Texinfo document is hierarchically organized (@pxref{makeinfo
+Pointer Creation}).
+
+You may insert spaces before each name if you wish; the spaces are
+ignored. You must write the name of the node and the names of the
+`Next', `Previous', and `Up' pointers all on the same line. Otherwise,
+the formatters fail. (@inforef{Top, info, info}, for more information
+about nodes in Info.)
+
+Usually, you write one of the chapter-structuring command lines
+immediately after an @code{@@node} line---for example, an
address@hidden@@section} or @code{@@subsection} line. (@xref{Structuring
+Command Types}.)
+
address@hidden
address@hidden note:} The GNU Emacs Texinfo mode updating commands work
+only with Texinfo files in which @code{@@node} lines are followed by chapter
+structuring lines. @xref{Updating address@hidden
address@hidden quotation
+
address@hidden uses @code{@@node} lines to identify the names to use for cross
+references. For this reason, you must write @code{@@node} lines in a
+Texinfo file that you intend to format for printing, even if you do not
+intend to format it for Info. (Cross references, such as the one at the
+end of this sentence, are made with @code{@@xref} and related commands;
+see @ref{Cross References}.)@refill
+
address@hidden
+* Node Names:: How to choose node and pointer names.
+* Writing a Node:: How to write an @code{@@node} line.
+* Node Line Tips:: Keep names short.
+* Node Line Requirements:: Keep names unique, without @@-commands.
+* First Node:: How to write a `Top' node.
+* makeinfo top command:: How to use the @code{@@top} command.
address@hidden menu
+
+
address@hidden Node Names
address@hidden Choosing Node and Pointer Names
+
address@hidden Node names, choosing
+The name of a node identifies the node. The pointers enable
+you to reach other nodes and consist of the names of those address@hidden
+
+Normally, a node's `Up' pointer contains the name of the node whose menu
+mentions that node. The node's `Next' pointer contains the name of the
+node that follows that node in that menu and its `Previous' pointer
+contains the name of the node that precedes it in that menu. When a
+node's `Previous' node is the same as its `Up' node, both node pointers
+name the same address@hidden
+
+Usually, the first node of a Texinfo file is the `Top' node, and its
+`Up' and `Previous' pointers point to the @file{dir} file, which
+contains the main menu for all of address@hidden
+
+The `Top' node itself contains the main or master menu for the manual.
+Also, it is helpful to include a brief description of the manual in the
+`Top' node. @xref{First Node}, for information on how to write the
+first node of a Texinfo address@hidden
+
+Even when you explicitly specify all pointers, that does not mean you
+can write the nodes in the Texinfo source file in an arbitrary order!
+Because @TeX{} processes the file sequentially, irrespective of node
+pointers, you must write the nodes in the order you wish them to appear
+in the printed output.
+
+
address@hidden Writing a Node
address@hidden How to Write an @code{@@node} Line
address@hidden Writing an @code{@@node} line
address@hidden @code{@@node} line writing
address@hidden Node line writing
+
+The easiest way to write an @code{@@node} line is to write @code{@@node}
+at the beginning of a line and then the name of the node, like
+this:@refill
+
address@hidden
+@@node @var{node-name}
address@hidden example
+
+If you are using GNU Emacs, you can use the update node commands
+provided by Texinfo mode to insert the names of the pointers; or you
+can leave the pointers out of the Texinfo file and let @code{makeinfo}
+insert node pointers into the Info file it creates. (@xref{Texinfo
+Mode}, and @ref{makeinfo Pointer Creation}.)@refill
+
+Alternatively, you can insert the `Next', `Previous', and `Up'
+pointers yourself. If you do this, you may find it helpful to use the
+Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts
address@hidden@@node} and a comment line listing the names of the pointers in
+their proper order. The comment line helps you keep track of which
+arguments are for which pointers. This comment line is especially useful
+if you are not familiar with address@hidden
+
+The template for a fully-written-out node line with `Next', `Previous',
+and `Up' pointers looks like this:@refill
+
address@hidden
+@@node @var{node-name}, @var{next}, @var{previous}, @var{up}
address@hidden example
+
+If you wish, you can ignore @code{@@node} lines altogether in your first
+draft and then use the @code{texinfo-insert-node-lines} command to
+create @code{@@node} lines for you. However, we do not recommend this
+practice. It is better to name the node itself at the same time that
+you write a segment so you can easily make cross references. A large
+number of cross references are an especially important feature of a good
+Info file.
+
+After you have inserted an @code{@@node} line, you should immediately
+write an @@-command for the chapter or section and insert its name.
+Next (and this is important!), put in several index entries. Usually,
+you will find at least two and often as many as four or five ways of
+referring to the node in the index. Use them all. This will make it
+much easier for people to find the node.
+
+
address@hidden Node Line Tips
address@hidden @code{@@node} Line Tips
+
+Here are three suggestions:
+
address@hidden @bullet
address@hidden
+Try to pick node names that are informative but address@hidden
+
+In the Info file, the file name, node name, and pointer names are all
+inserted on one line, which may run into the right edge of the window.
+(This does not cause a problem with Info, but is ugly.)@refill
+
address@hidden
+Try to pick node names that differ from each other near the beginnings
+of their names. This way, it is easy to use automatic name completion in
address@hidden
+
address@hidden
+By convention, node names are capitalized just as they would be for
+section or chapter titles---initial and significant words are
+capitalized; others are address@hidden
address@hidden itemize
+
+
address@hidden Node Line Requirements, First Node, Node Line Tips, node
address@hidden @code{@@node} Line Requirements
+
address@hidden Node line requirements
address@hidden Restrictions on node names
+Here are several requirements for @code{@@node} lines:
+
address@hidden @bullet
address@hidden Unique nodename requirement
address@hidden Node name must be unique
address@hidden
+All the node names for a single Info file must be address@hidden
+
+Duplicates confuse the Info movement commands. This means, for
+example, that if you end every chapter with a summary, you must name
+each summary node differently. You cannot just call each one
+``Summary''. You may, however, duplicate the titles of chapters, sections,
+and the like. Thus you can end each chapter in a book with a section
+called ``Summary'', so long as the node names for those sections are all
address@hidden
+
address@hidden
+A pointer name must be the name of a address@hidden
+
+The node to which a pointer points may come before or after the
+node containing the pointer.
+
address@hidden @@-commands in nodename
address@hidden Node name, should not contain @@-commands
address@hidden
address@hidden@@-commands} used in node names generally confuse Info, so you
+should avoid them. This includes punctuation characters that are
+escaped with a @samp{@@}, such as @code{@@} and @address@hidden For a few
+rare cases when this is useful, Texinfo has limited support for using
address@hidden@@-commands} in node names; see @ref{Pointer Validation}.
+
address@hidden 750
+Thus, the beginning of the section called @code{@@chapter} looks like
+this:@refill
+
address@hidden
address@hidden
+@@node chapter, unnumbered & appendix, makeinfo top, Structuring
+@@comment node-name, next, previous, up
+@@section @@address@hidden@@@@address@hidden
+@@findex chapter
address@hidden group
address@hidden smallexample
+
address@hidden
address@hidden Parentheses in nodename
+You cannot use parentheses in node names, because a node name such as
address@hidden(foo)bar} is interpreted by the Info readers as a node
address@hidden in an Info file @file{foo}.
+
address@hidden
address@hidden Apostrophe in nodename
address@hidden Colon in nodename
address@hidden Comma in nodename
address@hidden Period in nodename
address@hidden Characters, invalid in node name
address@hidden Invalid characters in node names
+Unfortunately, you cannot use periods, commas, colons or apostrophes
+within a node name; these confuse @TeX{} or the Info formatters.
+
address@hidden 700
+For example, the following is a section title:
+
address@hidden
+@@address@hidden@@@@address@hidden, @@address@hidden@@@@address@hidden,
@@address@hidden@@@@address@hidden
address@hidden smallexample
+
address@hidden
+The corresponding node name is:
+
address@hidden
+unnumberedsec appendixsec heading
address@hidden smallexample
+
address@hidden Case in node name
address@hidden
+Case is significant.
address@hidden itemize
+
+
address@hidden First Node
address@hidden The First Node
address@hidden Top node is first
address@hidden First node
+
+The first node of a Texinfo file is the @dfn{Top} node, except in an
+included file (@pxref{Include Files}). The Top node should contain a
+short summary, copying permissions, and a master menu. @xref{The Top
+Node}, for more information on the Top node contents and examples.
+
+Here is a description of the node pointers to be used in the Top node:
+
address@hidden @bullet
+
address@hidden
address@hidden Up node of Top node
address@hidden (dir) as Up node of Top node
+The Top node (which must be named @samp{top} or @samp{Top}) should have
+as its `Up' node the name of a node in another file, where there is a
+menu that leads to this file. Specify the file name in parentheses.
+
+Usually, all Info files are installed in the same Info directory tree;
+in this case, use @samp{(dir)} as the parent of the Top node; this is
+short for @samp{(dir)top}, and specifies the Top node in the @file{dir}
+file, which contains the main menu for the Info system as a whole.
+
address@hidden
address@hidden Previous node of Top node
+On the other hand, do not define the `Previous' node of the Top node to
+be @samp{(dir)}, as it causes confusing behavior for users: if you are
+in the Top node and hits @key{DEL} to go backwards, you wind up in the
+middle of the some other entry in the @file{dir} file, which has nothing
+to do with what you were reading.
+
address@hidden
address@hidden Next node of Top node
+The `Next' node of the Top node should be the first chapter in your
+document.
+
address@hidden itemize
+
address@hidden an Info File}, for more information about installing
+an Info file in the @file{info} directory.
+
+For concreteness, here is an example with explicit pointers (which you
+can maintain automatically with the texinfo mode commands):
+
+Or you can leave the pointers off entirely and let the tools implicitly
+define them. This is recommended. Thus:
+
address@hidden
+@@node Top
address@hidden example
+
+
address@hidden makeinfo top command
address@hidden The @code{@@top} Sectioning Command
address@hidden top @r{(@@-command)}
+
+A special sectioning command, @code{@@top} should be used with the
address@hidden@@node Top} line. The @code{@@top} sectioning command tells
address@hidden that it marks the `Top' node in the file. It provides
+the information that @code{makeinfo} needs to insert node pointers
+automatically. Write the @code{@@top} command at the beginning of the
+line immediately following the @code{@@node Top} line. Write the title
+on the remaining part of the same line as the @code{@@top} command.
+
+In Info, the @code{@@top} sectioning command causes the title to appear
+on a line by itself, with a line of asterisks inserted underneath, as
+other sectioning commands do.
+
+In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
+sectioning command is merely a synonym for @code{@@unnumbered}.
+Neither of these formatters require an @code{@@top} command, and do
+nothing special with it. You can use @code{@@chapter} or
address@hidden@@unnumbered} after the @code{@@node Top} line when you use
+these formatters. Also, you can use @code{@@chapter} or
address@hidden@@unnumbered} when you use the Texinfo updating commands to
+create or update pointers and menus.
+
+Thus, in practice, a Top node starts like this:
+
address@hidden
+@@node Top
+@@top Your Manual Title
address@hidden example
+
+
address@hidden makeinfo Pointer Creation
address@hidden Creating Pointers with @code{makeinfo}
address@hidden Creating pointers with @code{makeinfo}
address@hidden Pointer creation with @code{makeinfo}
address@hidden Automatic pointer creation with @code{makeinfo}
+
+The @code{makeinfo} program has a feature for automatically defining
+node pointers for a hierarchically organized file.
+
+When you take advantage of this feature, you do not need to write the
+`Next', `Previous', and `Up' pointers after the name of a node.
+However, you must write a sectioning command, such as @code{@@chapter}
+or @code{@@section}, on the line immediately following each truncated
address@hidden@@node} line (except that comment lines may intervene).
+
+In addition, you must follow the `Top' @code{@@node} line with a line
+beginning with @code{@@top} to mark the `Top' node in the
+file. @xref{makeinfo top, , @code{@@top}}.
+
+Finally, you must write the name of each node (except for the `Top'
+node) in a menu that is one or more hierarchical levels above the
+node's hierarchical level.
+
+This node pointer insertion feature in @code{makeinfo} relieves you from
+the need to update menus and pointers manually or with Texinfo mode
+commands. (@xref{Updating Nodes and Menus}.)
+
+In most cases, you will want to take advantage of this feature and not
+redundantly specify node pointers. However, Texinfo documents are not
+required to be organized hierarchically or in fact contain sectioning
+commands at all. For example, if you never intend the document to be
+printed. In those cases, you will need to explicitly specify the pointers.
+
+
address@hidden anchor
address@hidden @code{@@anchor}: Defining Arbitrary Cross-reference Targets
+
address@hidden anchor
address@hidden Anchors
address@hidden Cross-reference targets, arbitrary
address@hidden Targets for cross-references, arbitrary
+
+An @dfn{anchor} is a position in your document, labeled so that
+cross-references can refer to it, just as they can to nodes. You create
+an anchor with the @code{@@anchor} command, and give the label as a
+normal brace-delimited argument. For example:
+
address@hidden
+This marks the @@address@hidden@}spot.
address@hidden
+@@address@hidden,,the address@hidden
address@hidden example
+
address@hidden produces:
+
address@hidden
+This marks the spot.
address@hidden
+See [the spot], page 1.
address@hidden example
+
+As you can see, the @code{@@anchor} command itself produces no output.
+This example defines an anchor `x-spot' just before the word `spot'.
+You can refer to it later with an @code{@@xref} or other cross-reference
+command, as shown. @xref{Cross References}, for details on the
+cross-reference commands.
+
+It is best to put @code{@@anchor} commands just before the position you
+wish to refer to; that way, the reader's eye is led on to the correct
+text when they jump to the anchor. You can put the @code{@@anchor}
+command on a line by itself if that helps readability of the source.
+Spaces are always ignored after @code{@@anchor}.
+
+Anchor names and node names may not conflict. Anchors and nodes are
+given similar treatment in some ways; for example, the @code{goto-node}
+command in standalone Info takes either an anchor name or a node name as
+an argument. (@xref{goto-node,,,info-stnd,GNU Info}.)
+
+
address@hidden Menus
address@hidden Menus
address@hidden Menus
address@hidden menu
+
address@hidden contain pointers to subordinate address@hidden can
+carry you to any node, regardless of the hierarchical structure; even to
+nodes in a different Info file. However, the GNU Emacs Texinfo mode
+updating commands work only to create menus of subordinate nodes.
+Conventionally, cross references are used to refer to other nodes.} In
+Info, you use menus to go to such nodes. Menus have no effect in
+printed manuals and do not appear in them.
+
+By convention, a menu is put at the end of a node since a reader who
+uses the menu may not see text that follows it. Furthermore, a node
+that has a menu should not contain much text. If you have a lot of text
+and a menu, move most of the text into a new subnode---all but a few
+lines. Otherwise, a reader with a terminal that displays only a few
+lines may miss the menu and its associated text. As a practical matter,
+you should locate a menu within 20 lines of the beginning of the
+node.
+
address@hidden
+* Menu Location:: Put a menu in a short node.
+* Writing a Menu:: What is a menu?
+* Menu Parts:: A menu entry has three parts.
+* Less Cluttered Menu Entry:: Two part menu entry.
+* Menu Example:: Two and three part menu entries.
+* Other Info Files:: How to refer to a different Info file.
address@hidden menu
+
+
address@hidden Menu Location, Writing a Menu, Menus, Menus
address@hidden Menus Need Short Nodes
address@hidden Menu location
address@hidden Location of menus
address@hidden Nodes for menus are short
address@hidden Short nodes for menus
+
+The short text before a menu may look awkward in a printed manual. To
+avoid this, you can write a menu near the beginning of its node and
+follow the menu by an @code{@@node} line, and then an @code{@@heading}
+line located within @code{@@ifinfo} and @code{@@end ifinfo}. This way,
+the menu, @code{@@node} line, and title appear only in the Info file,
+not the printed document.
+
+For example, the preceding two paragraphs follow an Info-only menu,
address@hidden@@node} line, and heading, and look like this:
+
address@hidden
address@hidden
+@@menu
+* Menu Location:: Put a menu in a short node.
+* Writing a Menu:: What is a menu?
+* Menu Parts:: A menu entry has three parts.
+* Less Cluttered Menu Entry:: Two part menu entry.
+* Menu Example:: Two and three part entries.
+* Other Info Files:: How to refer to a different
+ Info file.
+@@end menu
+
+@@node Menu Location, Writing a Menu, , Menus
+@@ifinfo
+@@heading Menus Need Short Nodes
+@@end ifinfo
address@hidden group
address@hidden example
+
+The Texinfo file for this document contains a number of
+examples of this procedure; one is at the beginning of this chapter.
+
+
address@hidden Writing a Menu, Menu Parts, Menu Location, Menus
address@hidden Writing a Menu
address@hidden Writing a menu
address@hidden Menu writing
+
+A menu consists of an @code{@@menu} command on a line by
+itself followed by menu entry lines or menu comment lines
+and then by an @code{@@end menu} command on a line by
address@hidden
+
+A menu looks like this:@refill
+
address@hidden
address@hidden
+@@menu
+Larger Units of Text
+
+* Files:: All about handling files.
+* Multiples: Buffers. Multiple buffers; editing
+ several files at once.
+@@end menu
address@hidden group
address@hidden example
+
+In a menu, every line that begins with an @address@hidden }} is a @dfn{menu
+entry}. (Note the space after the asterisk.) A line that does not
+start with an @address@hidden }} may also appear in a menu. Such a line is
+not a menu entry but is a menu comment line that appears in the Info
+file. In the example above, the line @samp{Larger Units of Text} is a
+menu comment line; the two lines starting with @address@hidden }} are menu
address@hidden Spaces, in menus
+entries. Space characters in a menu are preserved as-is; this allows
+you to format the menu as you wish.
+
+
address@hidden Menu Parts, Less Cluttered Menu Entry, Writing a Menu, Menus
address@hidden The Parts of a Menu
address@hidden Parts of a menu
address@hidden Menu parts
address@hidden @code{@@menu} parts
+
+A menu entry has three parts, only the second of which is required:
+
address@hidden
address@hidden
+The menu entry name (optional).
+
address@hidden
+The name of the node (required).
+
address@hidden
+A description of the item (optional).
address@hidden enumerate
+
+The template for a menu entry looks like this:@refill
+
address@hidden
+* @var{menu-entry-name}: @var{node-name}. @var{description}
address@hidden example
+
+Follow the menu entry name with a single colon and follow the node name
+with tab, comma, period, or address@hidden
+
+In Info, a user selects a node with the @kbd{m} (@code{Info-menu})
+command. The menu entry name is what the user types after the @kbd{m}
address@hidden
+
+The third part of a menu entry is a descriptive phrase or sentence.
+Menu entry names and node names are often short; the description
+explains to the reader what the node is about. A useful description
+complements the node name rather than repeats it. The description,
+which is optional, can spread over two or more lines; if it does, some
+authors prefer to indent the second line while others prefer to align it
+with the first (and all others). It's up to you.
+
+
address@hidden Less Cluttered Menu Entry, Menu Example, Menu Parts, Menus
address@hidden node-name, next, previous, up
address@hidden Less Cluttered Menu Entry
address@hidden Two part menu entry
address@hidden Double-colon menu entries
address@hidden Menu entries with two colons
address@hidden Less cluttered menu entry
address@hidden Uncluttered menu entry
+
+When the menu entry name and node name are the same, you can write
+the name immediately after the asterisk and space at the beginning of
+the line and follow the name with two address@hidden
+
address@hidden 800
+For example, write
+
address@hidden
+* Name:: @var{description}
address@hidden example
+
address@hidden 800
address@hidden
+instead of
+
address@hidden
+* Name: Name. @var{description}
address@hidden example
+
+You should use the node name for the menu entry name whenever possible,
+since it reduces visual clutter in the address@hidden
+
address@hidden Menu Example, Other Info Files, Less Cluttered Menu Entry, Menus
address@hidden node-name, next, previous, up
address@hidden A Menu Example
address@hidden Menu example
address@hidden Example menu
+
+A menu looks like this in Texinfo:@refill
+
address@hidden
address@hidden
+@@menu
+* menu entry name: Node name. A short description.
+* Node name:: This form is preferred.
+@@end menu
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+This produces:
+
address@hidden
address@hidden
+* menu:
+
+* menu entry name: Node name. A short description.
+* Node name:: This form is preferred.
address@hidden group
address@hidden example
+
address@hidden 700
+Here is an example as you might see it in a Texinfo file:@refill
+
address@hidden
address@hidden
+@@menu
+Larger Units of Text
+
+* Files:: All about handling files.
+* Multiples: Buffers. Multiple buffers; editing
+ several files at once.
+@@end menu
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+This produces:
+
address@hidden
address@hidden
+* menu:
+Larger Units of Text
+
+* Files:: All about handling files.
+* Multiples: Buffers. Multiple buffers; editing
+ several files at once.
address@hidden group
address@hidden example
+
+In this example, the menu has two entries. @samp{Files} is both a menu
+entry name and the name of the node referred to by that name.
address@hidden is the menu entry name; it refers to the node named
address@hidden The line @samp{Larger Units of Text} is a comment; it
+appears in the menu, but is not an address@hidden
+
+Since no file name is specified with either @samp{Files} or
address@hidden, they must be the names of nodes in the same Info file
+(@pxref{Other Info Files, , Referring to Other Info Files})address@hidden
+
address@hidden Other Info Files, , Menu Example, Menus
address@hidden node-name, next, previous, up
address@hidden Referring to Other Info Files
address@hidden Referring to other Info files
address@hidden Nodes in other Info files
address@hidden Other Info files' nodes
address@hidden Going to other Info files' nodes
address@hidden Info; other files' nodes
+
+You can create a menu entry that enables a reader in Info to go to a
+node in another Info file by writing the file name in parentheses just
+before the node name. In this case, you should use the three-part menu
+entry format, which saves the reader from having to type the file
address@hidden
+
address@hidden 800
+The format looks like this:@refill
+
address@hidden
address@hidden
+@@menu
+* @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description}
+* @var{second-entry-name}:(@var{filename})@var{second-node}. @var{description}
+@@end menu
address@hidden group
address@hidden example
+
+For example, to refer directly to the @samp{Outlining} and
address@hidden nodes in the @cite{Emacs Manual}, you would write a
+menu like this:@refill
+
address@hidden
address@hidden
+@@menu
+* Outlining: (emacs)Outline Mode. The major mode for
+ editing outlines.
+* Rebinding: (emacs)Rebinding. How to redefine the
+ meaning of a key.
+@@end menu
address@hidden group
address@hidden example
+
+If you do not list the node name, but only name the file, then Info
+presumes that you are referring to the `Top' address@hidden
+
+The @file{dir} file that contains the main menu for Info has menu
+entries that list only file names. These take you directly to the `Top'
+nodes of each Info document. (@xref{Installing an Info File}.)
+
address@hidden 700
+For example:
+
address@hidden
address@hidden
+* Info: (info). Documentation browsing system.
+* Emacs: (emacs). The extensible, self-documenting
+ text editor.
address@hidden group
address@hidden example
+
address@hidden
+(The @file{dir} top level directory for the Info system is an Info file,
+not a Texinfo file, but a menu entry looks the same in both types of
+file.)@refill
+
+The GNU Emacs Texinfo mode menu updating commands only work with nodes
+within the current buffer, so you cannot use them to create menus that
+refer to other files. You must write such menus by hand.
+
+
address@hidden Cross References
address@hidden Cross References
address@hidden Making cross references
address@hidden Cross references
address@hidden References
+
address@hidden references} are used to refer the reader to other parts of the
+same or different Texinfo files. In Texinfo, nodes and anchors are the
+places to which cross references can refer.
+
address@hidden
+* References:: What cross references are for.
+* Cross Reference Commands:: A summary of the different commands.
+* Cross Reference Parts:: A cross reference has several parts.
+* xref:: Begin a reference with `See' @dots{}
+* Top Node Naming:: How to refer to the beginning of another file.
+* ref:: A reference for the last part of a sentence.
+* pxref:: How to write a parenthetical cross reference.
+* inforef:: How to refer to an Info-only file.
+* uref:: How to refer to a uniform resource locator.
address@hidden menu
+
address@hidden References, Cross Reference Commands, Cross References, Cross
References
address@hidden What References Are For
+
+Often, but not always, a printed document should be designed so that
+it can be read sequentially. People tire of flipping back and forth
+to find information that should be presented to them as they need
address@hidden
+
+However, in any document, some information will be too detailed for
+the current context, or incidental to it; use cross references to
+provide access to such information. Also, an online help system or a
+reference manual is not like a novel; few read such documents in
+sequence from beginning to end. Instead, people look up what they
+need. For this reason, such creations should contain many cross
+references to help readers find other information that they may not
+have address@hidden
+
+In a printed manual, a cross reference results in a page reference,
+unless it is to another manual altogether, in which case the cross
+reference names that address@hidden
+
+In Info, a cross reference results in an entry that you can follow using
+the Info @samp{f} command. (@inforef{Help-Adv, Some advanced Info
+commands, info}.)@refill
+
+The various cross reference commands use nodes (or anchors,
address@hidden,,@code{@@anchor}}) to define cross reference locations.
+This is evident in Info, in which a cross reference takes you to the
+specified location. @TeX{} also uses nodes to define cross reference
+locations, but the action is less obvious. When @TeX{} generates a DVI
+file, it records each node's page number and uses the page numbers in making
+references. Thus, if you are writing a manual that will only be
+printed, and will not be used online, you must nonetheless write
address@hidden@@node} lines to name the places to which you make cross
address@hidden
+
address@hidden 800
address@hidden Cross Reference Commands, Cross Reference Parts, References,
Cross References
address@hidden node-name, next, previous, up
address@hidden Different Cross Reference Commands
address@hidden Different cross reference commands
+
+There are four different cross reference commands:@refill
+
address@hidden @code
address@hidden @@xref
+Used to start a sentence in the printed manual saying @w{`See @dots{}'}
+or an Info cross-reference saying @samp{*Note @var{name}: @var{node}.}.
+
address@hidden @@ref
+Used within or, more often, at the end of a sentence; same as
address@hidden@@xref} for Info; produces just the reference in the printed
+manual without a preceding `See'address@hidden
+
address@hidden @@pxref
+Used within parentheses to make a reference that suits both an Info
+file and a printed book. Starts with a lower case `see' within the
+printed manual. (@samp{p} is for `parenthesis'.)@refill
+
address@hidden @@inforef
+Used to make a reference to an Info file for which there is no printed
address@hidden
address@hidden table
+
address@hidden
+(The @code{@@cite} command is used to make references to books and
+manuals for which there is no corresponding Info file and, therefore,
+no node to which to point. @xref{cite, , @code{@@cite}}.)@refill
+
address@hidden Cross Reference Parts, xref, Cross Reference Commands, Cross
References
address@hidden node-name, next, previous, up
address@hidden Parts of a Cross Reference
address@hidden Cross reference parts
address@hidden Parts of a cross reference
+
+A cross reference command requires only one argument, which is the
+name of the node to which it refers. But a cross reference command
+may contain up to four additional arguments. By using these
+arguments, you can provide a cross reference name for Info, a topic
+description or section title for the printed output, the name of a
+different Info file, and the name of a different printed
address@hidden
+
+Here is a simple cross reference example:@refill
+
address@hidden
+@@address@hidden address@hidden
address@hidden example
+
address@hidden
+which produces
+
address@hidden
+*Note Node name::.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See Section @var{nnn} [Node name], page @var{ppp}.
address@hidden quotation
+
address@hidden 700
+Here is an example of a full five-part cross reference:@refill
+
address@hidden
address@hidden
+@@address@hidden name, Cross Reference Name, Particular Topic,
+info-file-name, A Printed address@hidden, for details.
address@hidden group
address@hidden example
+
address@hidden
+which produces
+
address@hidden
+*Note Cross Reference Name: (info-file-name)Node name,
+for details.
address@hidden example
+
address@hidden
+in Info and
+
address@hidden
+See section ``Particular Topic'' in @i{A Printed Manual}, for details.
address@hidden quotation
+
address@hidden
+in a printed book.
+
+The five possible arguments for a cross reference are:@refill
+
address@hidden
address@hidden
+The node or anchor name (required). This is the location to which the
+cross reference takes you. In a printed document, the location of the
+node provides the page reference only for references within the same
address@hidden
+
address@hidden
+The cross reference name for the Info reference, if it is to be different
+from the node name. If you include this argument, it becomes
+the first part of the cross reference. It is usually address@hidden
+
address@hidden
+A topic description or section name. Often, this is the title of the
+section. This is used as the name of the reference in the printed
+manual. If omitted, the node name is address@hidden
+
address@hidden
+The name of the Info file in which the reference is located, if it is
+different from the current file. You need not include any @samp{.info}
+suffix on the file name, since Info readers try appending it
+automatically.
+
address@hidden
+The name of a printed manual from a different Texinfo address@hidden
address@hidden enumerate
+
+The template for a full five argument cross reference looks like
+this:@refill
+
address@hidden
address@hidden
+@@address@hidden@var{node-name}, @var{cross-reference-name},
@var{title-or-topic},
address@hidden, @address@hidden
address@hidden group
address@hidden example
+
+Cross references with one, two, three, four, and five arguments are
+described separately following the description of @code{@@address@hidden
+
+Write a node name in a cross reference in exactly the same way as in
+the @code{@@node} line, including the same capitalization; otherwise, the
+formatters may not find the address@hidden
+
+You can write cross reference commands within a paragraph, but note
+how Info and @TeX{} format the output of each of the various commands:
+write @code{@@xref} at the beginning of a sentence; write
address@hidden@@pxref} only within parentheses, and so address@hidden
+
address@hidden xref, Top Node Naming, Cross Reference Parts, Cross References
address@hidden node-name, next, previous, up
address@hidden @code{@@xref}
address@hidden xref
address@hidden Cross references using @code{@@xref}
address@hidden References using @code{@@xref}
+
+The @code{@@xref} command generates a cross reference for the
+beginning of a sentence. The Info formatting commands convert it into
+an Info cross reference, which the Info @samp{f} command can use to
+bring you directly to another node. The @TeX{} typesetting commands
+convert it into a page reference, or a reference to another book or
address@hidden
+
address@hidden
+* Reference Syntax:: What a reference looks like and requires.
+* 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.
address@hidden menu
+
address@hidden Reference Syntax, One Argument, xref, xref
address@hidden What a Reference Looks Like and Requires
+
+Most often, an Info cross reference looks like this:@refill
+
address@hidden
+*Note @var{node-name}::.
address@hidden example
+
address@hidden
+or like this
+
address@hidden
+*Note @var{cross-reference-name}: @var{node-name}.
address@hidden example
+
address@hidden
+In @TeX{}, a cross reference looks like this:
+
address@hidden
+See Section @var{section-number} address@hidden, page @var{page}.
address@hidden quotation
+
address@hidden
+or like this
+
address@hidden
+See Section @var{section-number} address@hidden, page @var{page}.
address@hidden quotation
+
+The @code{@@xref} command does not generate a period or comma to end
+the cross reference in either the Info file or the printed output.
+You must write that period or comma yourself; otherwise, Info will not
+recognize the end of the reference. (The @code{@@pxref} command works
+differently. @xref{pxref, , @code{@@pxref}}.)@refill
+
address@hidden
address@hidden note:} A period or comma @strong{must} follow the closing
+brace of an @code{@@xref}. It is required to terminate the cross
+reference. This period or comma will appear in the output, both in
+the Info file and in the printed address@hidden
address@hidden quotation
+
address@hidden@@xref} must refer to an Info node by name. Use @code{@@node}
+to define the node (@pxref{Writing a Node})address@hidden
+
address@hidden@@xref} is followed by several arguments inside braces, separated
by
+commas. Whitespace before and after these commas is address@hidden
+
+A cross reference requires only the name of a node; but it may contain
+up to four additional arguments. Each of these variations produces a
+cross reference that looks somewhat address@hidden
+
address@hidden
address@hidden note:} Commas separate arguments in a cross reference;
+avoid including them in the title or other part lest the formatters
+mistake them for address@hidden
address@hidden quotation
+
address@hidden One Argument, Two Arguments, Reference Syntax, xref
address@hidden @code{@@xref} with One Argument
+
+The simplest form of @code{@@xref} takes one argument, the name of
+another node in the same Info file. The Info formatters produce
+output that the Info readers can use to jump to the reference; @TeX{}
+produces output that specifies the page and section number for address@hidden
+
address@hidden 700
address@hidden
+For example,
+
address@hidden
+@@address@hidden address@hidden
address@hidden example
+
address@hidden
+produces
+
address@hidden
+*Note Tropical Storms::.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See Section 3.1 [Tropical Storms], page 24.
address@hidden quotation
+
address@hidden
+(Note that in the preceding example the closing brace is followed by a
+period.)@refill
+
+You can write a clause after the cross reference, like this:@refill
+
address@hidden
+@@address@hidden address@hidden, for more info.
address@hidden example
+
address@hidden
+which produces
+
address@hidden
+*Note Tropical Storms::, for more info.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See Section 3.1 [Tropical Storms], page 24, for more info.
address@hidden quotation
+
address@hidden
+(Note that in the preceding example the closing brace is followed by a
+comma, and then by the clause, which is followed by a period.)@refill
+
address@hidden Two Arguments, Three Arguments, One Argument, xref
address@hidden @code{@@xref} with Two Arguments
+
+With two arguments, the second is used as the name of the Info cross
+reference, while the first is still the name of the node to which the
+cross reference address@hidden
+
address@hidden 750
address@hidden
+The template is like this:
+
address@hidden
+@@address@hidden@var{node-name}, @address@hidden
address@hidden example
+
address@hidden 700
address@hidden
+For example,
+
address@hidden
+@@address@hidden Effects, address@hidden
address@hidden example
+
address@hidden
+produces:
+
address@hidden
+*Note Lightning: Electrical Effects.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See Section 5.2 [Electrical Effects], page 57.
address@hidden quotation
+
address@hidden
+(Note that in the preceding example the closing brace is followed by a
+period; and that the node name is printed, not the cross reference name.)
+
+You can write a clause after the cross reference, like this:@refill
+
address@hidden
+@@address@hidden Effects, address@hidden, for more info.
address@hidden example
+
address@hidden
+which produces
address@hidden
+*Note Lightning: Electrical Effects, for more info.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See Section 5.2 [Electrical Effects], page 57, for more info.
address@hidden quotation
+
address@hidden
+(Note that in the preceding example the closing brace is followed by a
+comma, and then by the clause, which is followed by a period.)@refill
+
address@hidden Three Arguments, Four and Five Arguments, Two Arguments, xref
address@hidden @code{@@xref} with Three Arguments
+
+A third argument replaces the node name in the @TeX{} output. The third
+argument should be the name of the section in the printed output, or
+else state the topic discussed by that section. Often, you will want to
+use initial upper case letters so it will be easier to read when the
+reference is printed. Use a third argument when the node name is
+unsuitable because of syntax or address@hidden
+
+Remember to avoid placing a comma within the title or topic section of
+a cross reference, or within any other section. The formatters divide
+cross references into arguments according to the commas; a comma
+within a title or other section will divide it into two arguments. In
+a reference, you need to write a title such as ``Clouds, Mist, and
+Fog'' without the address@hidden
+
+Also, remember to write a comma or period after the closing brace of an
address@hidden@@xref} to terminate the cross reference. In the following
+examples, a clause follows a terminating address@hidden
+
+
address@hidden 750
address@hidden
+The template is like this:
+
address@hidden
address@hidden
+@@address@hidden@var{node-name}, @var{cross-reference-name}, @address@hidden
address@hidden group
address@hidden example
+
address@hidden 700
address@hidden
+For example,
+
address@hidden
address@hidden
+@@address@hidden Effects, Lightning, Thunder and address@hidden,
+for details.
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
+*Note Lightning: Electrical Effects, for details.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See Section 5.2 [Thunder and Lightning], page 57, for details.
address@hidden quotation
+
+If a third argument is given and the second one is empty, then the
+third argument serves both. (Note how two commas, side by side, mark
+the empty second argument.)@refill
+
address@hidden
address@hidden
+@@address@hidden Effects, , Thunder and address@hidden,
+for details.
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
+*Note Thunder and Lightning: Electrical Effects, for details.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See Section 5.2 [Thunder and Lightning], page 57, for details.
address@hidden quotation
+
+As a practical matter, it is often best to write cross references with
+just the first argument if the node name and the section title are the
+same, and with the first and third arguments if the node name and title
+are address@hidden
+
+Here are several examples from @cite{The GNU Awk User's Guide}:@refill
+
address@hidden
+@@address@hidden address@hidden
+@@address@hidden@}.
+@@address@hidden, ,Case-sensitivity in address@hidden
+@@address@hidden Output, , Closing Output Files and address@hidden,
+ for more information.
+@@address@hidden, , Regular Expressions as address@hidden
address@hidden smallexample
+
address@hidden Four and Five Arguments, , Three Arguments, xref
address@hidden @code{@@xref} with Four and Five Arguments
+
+In a cross reference, a fourth argument specifies the name of another
+Info file, different from the file in which the reference appears, and
+a fifth argument specifies its title as a printed address@hidden
+
+Remember that a comma or period must follow the closing brace of an
address@hidden@@xref} command to terminate the cross reference. In the
+following examples, a clause follows a terminating address@hidden
+
address@hidden 800
address@hidden
+The template is:
+
address@hidden
address@hidden
+@@address@hidden@var{node-name}, @var{cross-reference-name},
@var{title-or-topic},
address@hidden, @address@hidden
address@hidden group
address@hidden example
+
address@hidden 700
address@hidden
+For example,
+
address@hidden
+@@address@hidden Effects, Lightning, Thunder and Lightning,
+weather, An Introduction to address@hidden, for details.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+*Note Lightning: (weather)Electrical Effects, for details.
address@hidden example
+
address@hidden
+The name of the Info file is enclosed in parentheses and precedes
+the name of the node.
+
address@hidden
+In a printed manual, the reference looks like this:@refill
+
address@hidden
+See section ``Thunder and Lightning'' in @i{An Introduction to
+Meteorology}, for details.
address@hidden quotation
+
address@hidden
+The title of the printed manual is typeset in italics; and the
+reference lacks a page number since @TeX{} cannot know to which page a
+reference refers when that reference is to another address@hidden
+
+Often, you will leave out the second argument when you use the long
+version of @code{@@xref}. In this case, the third argument, the topic
+description, will be used as the cross reference name in address@hidden
+
address@hidden
+The template looks like this:
+
address@hidden
+@@address@hidden@var{node-name}, , @var{title-or-topic}, @var{info-file-name},
address@hidden@}, for details.
address@hidden example
+
address@hidden
+which produces
+
address@hidden
+*Note @var{title-or-topic}: (@var{info-file-name})@var{node-name}, for details.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See section @var{title-or-topic} in @var{printed-manual-title}, for details.
address@hidden quotation
+
address@hidden 700
address@hidden
+For example,
+
address@hidden
+@@address@hidden Effects, , Thunder and Lightning,
+weather, An Introduction to address@hidden, for details.
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+*Note Thunder and Lightning: (weather)Electrical Effects,
+for details.
address@hidden group
address@hidden example
+
address@hidden
+and
+
address@hidden
+See section ``Thunder and Lightning'' in @i{An Introduction to
+Meteorology}, for details.
address@hidden quotation
+
+On rare occasions, you may want to refer to another Info file that
+is within a single printed manual---when multiple Texinfo files are
+incorporated into the same @TeX{} run but make separate Info files.
+In this case, you need to specify only the fourth argument, and not
+the address@hidden
+
address@hidden Top Node Naming, ref, xref, Cross References
address@hidden Naming a `Top' Node
address@hidden Naming a `Top' Node in references
address@hidden @address@hidden node naming for references
+
+In a cross reference, you must always name a node. This means that in
+order to refer to a whole manual, you must identify the `Top' node by
+writing it as the first argument to the @code{@@xref} command. (This
+is different from the way you write a menu entry; see @ref{Other Info
+Files, , Referring to Other Info Files}.) At the same time, to
+provide a meaningful section topic or title in the printed cross
+reference (instead of the word `Top'), you must write an appropriate
+entry for the third argument to the @code{@@xref} command.
address@hidden
+
address@hidden
+Thus, to make a cross reference to @cite{The GNU Make Manual},
+write:@refill
+
address@hidden
+@@address@hidden, , Overview, make, The GNU Make address@hidden
address@hidden example
+
address@hidden
+which produces
+
address@hidden
+*Note Overview: (make)Top.
address@hidden example
+
address@hidden
+and
+
address@hidden
+See section ``Overview'' in @i{The GNU Make Manual}.
address@hidden quotation
+
address@hidden
+In this example, @samp{Top} is the name of the first node, and
address@hidden is the name of the first section of the address@hidden
address@hidden ref, pxref, Top Node Naming, Cross References
address@hidden node-name, next, previous, up
address@hidden @code{@@ref}
address@hidden Cross references using @code{@@ref}
address@hidden References using @code{@@ref}
address@hidden ref
+
address@hidden@@ref} is nearly the same as @code{@@xref} except that it does
+not generate a `See' in the printed output, just the reference itself.
+This makes it useful as the last part of a address@hidden
+
address@hidden 700
address@hidden
+For example,
+
address@hidden Hurricanes
address@hidden
+For more information, see @@address@hidden@}.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+For more information, see *Note Hurricanes::.
address@hidden example
+
address@hidden
+and
+
address@hidden
+For more information, see Section 8.2 [Hurricanes], page 123.
address@hidden quotation
+
+The @code{@@ref} command sometimes leads writers to express themselves
+in a manner that is suitable for a printed manual but looks awkward
+in the Info format. Bear in mind that your audience will be using
+both the printed and the Info address@hidden
+
address@hidden 800
address@hidden
+For example,
+
address@hidden Sea surges
address@hidden
address@hidden
+Sea surges are described in @@address@hidden@}.
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+produces
+
address@hidden
+Sea surges are described in Section 6.7 [Hurricanes], page 72.
address@hidden quotation
+
address@hidden 800
address@hidden
+in a printed document, and the following in Info:
+
address@hidden
+Sea surges are described in *Note Hurricanes::.
address@hidden example
+
address@hidden
address@hidden:} You @emph{must} write a period, comma, or right
+parenthesis immediately after an @code{@@ref} command with two or more
+arguments. Otherwise, Info will not find the end of the cross reference
+entry and its attempt to follow the cross reference will fail. As a
+general rule, you should write a period or comma after every
address@hidden@@ref} command. This looks best in both the printed and the Info
address@hidden
address@hidden quotation
+
address@hidden pxref, inforef, ref, Cross References
address@hidden node-name, next, previous, up
address@hidden @code{@@pxref}
address@hidden Cross references using @code{@@pxref}
address@hidden References using @code{@@pxref}
address@hidden pxref
+
+The parenthetical reference command, @code{@@pxref}, is nearly the
+same as @code{@@xref}, but you use it @emph{only} inside parentheses
+and you do @emph{not} type a comma or period after the command's
+closing brace. The command differs from @code{@@xref} in two
+ways:@refill
+
address@hidden
address@hidden
address@hidden typesets the reference for the printed manual with a lower case
+`see' rather than an upper case `See'address@hidden
+
address@hidden
+The Info formatting commands automatically end the reference with a
+closing colon or address@hidden
address@hidden enumerate
+
+Because one type of formatting automatically inserts closing
+punctuation and the other does not, you should use @code{@@pxref}
address@hidden inside parentheses as part of another sentence. Also, you
+yourself should not insert punctuation after the reference, as you do
+with @code{@@address@hidden
+
address@hidden@@pxref} is designed so that the output looks right and works
+right between parentheses both in printed output and in an Info file.
+In a printed manual, a closing comma or period should not follow a
+cross reference within parentheses; such punctuation is wrong. But in
+an Info file, suitable closing punctuation must follow the cross
+reference so Info can recognize its end. @code{@@pxref} spares you
+the need to use complicated methods to put a terminator into one form
+of the output and not the address@hidden
+
address@hidden
+With one argument, a parenthetical cross reference looks like
+this:@refill
+
address@hidden Flooding
address@hidden
address@hidden storms cause flooding (@@address@hidden@}) @dots{}
address@hidden example
+
address@hidden 800
address@hidden
+which produces
+
address@hidden
address@hidden
address@hidden storms cause flooding (*Note Hurricanes::) @dots{}
address@hidden group
address@hidden example
+
address@hidden
+and
+
address@hidden
address@hidden storms cause flooding (see Section 6.7 [Hurricanes], page 72)
@dots{}
address@hidden quotation
+
+With two arguments, a parenthetical cross reference has this
+template:@refill
+
address@hidden
address@hidden (@@address@hidden@var{node-name}, @address@hidden) @dots{}
address@hidden example
+
address@hidden
+which produces
+
address@hidden
address@hidden (*Note @var{cross-reference-name}: @var{node-name}.) @dots{}
address@hidden example
+
address@hidden
+and
+
address@hidden 1500
address@hidden
address@hidden (see Section @var{nnn} address@hidden, page @var{ppp}) @dots{}
address@hidden quotation
+
address@hidden@@pxref} can be used with up to five arguments just like
address@hidden@@xref} (@pxref{xref, , @code{@@xref}})address@hidden
+
address@hidden
address@hidden note:} Use @code{@@pxref} only as a parenthetical
+reference. Do not try to use @code{@@pxref} as a clause in a sentence.
+It will look bad in either the Info file, the printed output, or
address@hidden
+
+Also, parenthetical cross references look best at the ends of sentences.
+Although you may write them in the middle of a sentence, that location
+breaks up the flow of address@hidden
address@hidden quotation
+
address@hidden inforef, uref, pxref, Cross References
address@hidden @code{@@inforef}
address@hidden Cross references using @code{@@inforef}
address@hidden References using @code{@@inforef}
address@hidden inforef
+
address@hidden@@inforef} is used for cross references to Info files for which
+there are no printed manuals. Even in a printed manual,
address@hidden@@inforef} generates a reference directing the user to look in
+an Info address@hidden
+
+The command takes either two or three arguments, in the following
+order:@refill
+
address@hidden
address@hidden
+The node name.
+
address@hidden
+The cross reference name (optional).
+
address@hidden
+The Info file name.
address@hidden enumerate
+
address@hidden
+Separate the arguments with commas, as with @code{@@xref}. Also, you
+must terminate the reference with a comma or period after the
address@hidden@}}, as you do with @code{@@address@hidden
+
address@hidden
+The template is:
+
address@hidden
+@@address@hidden@var{node-name}, @var{cross-reference-name}, @address@hidden,
address@hidden example
+
address@hidden 800
address@hidden
+Thus,
+
address@hidden
address@hidden
+@@address@hidden, Advanced Info commands, address@hidden,
+for more information.
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+produces
+
address@hidden
address@hidden
+*Note Advanced Info commands: (info)Expert,
+for more information.
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+and
+
address@hidden
+See Info file @file{info}, node @samp{Expert}, for more information.
address@hidden quotation
+
address@hidden 800
address@hidden
+Similarly,
+
address@hidden
address@hidden
+@@address@hidden, , address@hidden, for more information.
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+produces
+
address@hidden
+*Note (info)Expert::, for more information.
address@hidden example
+
address@hidden 800
address@hidden
+and
+
address@hidden
+See Info file @file{info}, node @samp{Expert}, for more information.
address@hidden quotation
+
+The converse of @code{@@inforef} is @code{@@cite}, which is used to
+refer to printed works for which no Info form exists. @xref{cite, ,
address@hidden@@address@hidden
+
+
address@hidden uref
address@hidden @code{@@address@hidden@var{url}[, @var{text}][, @address@hidden
address@hidden uref
address@hidden Uniform resource locator, referring to
address@hidden URL, referring to
+
address@hidden @code{href}, producing HTML
address@hidden@@uref} produces a reference to a uniform resource locator (url).
+It takes one mandatory argument, the url, and two optional arguments
+which control the text that is displayed. In HTML output, @code{@@uref}
+produces a link you can follow.
+
+The second argument, if specified, is the text to display (the default
+is the url itself); in Info and DVI output, but not in HTML output, the
+url is also output.
+
address@hidden Man page, reference to
+The third argument, on the other hand, if specified is also the text to
+display, but the url is @emph{not} output in any format. This is useful
+when the text is already sufficiently referential, as in a man page. If
+the third argument is given, the second argument is ignored.
+
+The simple one argument form, where the url is both the target and the
+text of the link:
+
address@hidden
+The official GNU ftp site is @@address@hidden://ftp.gnu.org/address@hidden
address@hidden example
+
address@hidden produces:
address@hidden
+The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}.
address@hidden display
+
+
+An example of the two-argument form:
address@hidden
+The official @@address@hidden://ftp.gnu.org/gnu, GNU ftp address@hidden
+holds programs and texts.
address@hidden example
+
address@hidden produces:
address@hidden
+The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site}
+holds programs and texts.
address@hidden display
+
address@hidden that is, the Info output is this:
address@hidden
+The official GNU ftp site (ftp://ftp.gnu.org/gnu)
+holds programs and texts.
address@hidden example
+
address@hidden and the HTML output is this:
address@hidden
+The official <a href="ftp://ftp.gnu.org/gnu";>GNU ftp site</a>
+holds programs and texts.
address@hidden example
+
+
+An example of the three-argument form:
address@hidden
+The @@address@hidden/man.cgi/1/ls,,ls(1)@} program @dots{}
address@hidden example
+
address@hidden produces:
address@hidden
+The @uref{/man.cgi/1/ls,,ls(1)} program @dots{}
address@hidden display
+
address@hidden but with HTML:
address@hidden
+The <a href="/man.cgi/1/ls">ls(1)</a> program @dots{}
address@hidden example
+
+To merely indicate a url without creating a link people can follow, use
address@hidden@@url} (@pxref{url, @code{@@url}}).
+
+Some people prefer to display url's in the unambiguous format:
+
address@hidden
+<URL:http://@var{host}/@var{path}>
address@hidden display
+
address@hidden
address@hidden <URL convention, not used
+You can use this form in the input file if you wish. We feel it's not
+necessary to clutter up the output with the extra @samp{<URL:} and
address@hidden>}, since any software that tries to detect url's in text already
+has to detect them without the @samp{<URL:} to be useful.
+
+
address@hidden Marking Text
address@hidden Marking Words and Phrases
address@hidden Paragraph, marking text within
address@hidden Marking words and phrases
address@hidden Words and phrases, marking them
address@hidden Marking text within a paragraph
address@hidden Text, marking up
+
+In Texinfo, you can mark words and phrases in a variety of ways.
+The Texinfo formatters use this information to determine how to
+highlight the text.
+You can specify, for example, whether a word or phrase is a
+defining occurrence, a metasyntactic variable, or a symbol used in a
+program. Also, you can emphasize text, in several different ways.
+
address@hidden
+* Indicating:: How to indicate definitions, files, etc.
+* Emphasis:: How to emphasize text.
address@hidden menu
+
+
address@hidden Indicating, Emphasis, Marking Text, Marking Text
address@hidden Indicating Definitions, Commands, etc.
address@hidden Highlighting text
address@hidden Indicating commands, definitions, etc.
+
+Texinfo has commands for indicating just what kind of object a piece of
+text refers to. For example, metasyntactic variables are marked by
address@hidden@@var}, and code by @code{@@code}. Since the pieces of text are
+labelled by commands that tell what kind of object they are, it is easy
+to change the way the Texinfo formatters prepare such text. (Texinfo is
+an @emph{intentional} formatting language rather than a @emph{typesetting}
+formatting language.)@refill
+
+For example, in a printed manual,
+code is usually illustrated in a typewriter font;
address@hidden@@code} tells @TeX{} to typeset this text in this font. But it
+would be easy to change the way @TeX{} highlights code to use another
+font, and this change would not affect how keystroke examples are
+highlighted. If straight typesetting commands were used in the body
+of the file and you wanted to make a change, you would need to check
+every single occurrence to make sure that you were changing code and
+not something else that should not be address@hidden
+
address@hidden
+* Useful Highlighting:: Highlighting provides useful information.
+* code:: Indicating program code.
+* kbd:: Showing keyboard input.
+* key:: Specifying keys.
+* samp:: A literal sequence of characters.
+* verb:: A verbatim sequence of characters.
+* var:: Indicating metasyntactic variables.
+* env:: Indicating environment variables.
+* file:: Indicating file names.
+* command:: Indicating command names.
+* option:: Indicating option names.
+* dfn:: Specifying definitions.
+* cite:: Referring to books not in the Info system.
+* acronym:: Indicating acronyms.
+* url:: Indicating a World Wide Web reference.
+* email:: Indicating an electronic mail address.
address@hidden menu
+
+
address@hidden Useful Highlighting, code, Indicating, Indicating
address@hidden Highlighting Commands are Useful
+
+The highlighting commands can be used to extract useful information
+from the file, such as lists of functions or file names. It is
+possible, for example, to write a program in Emacs Lisp (or a keyboard
+macro) to insert an index entry after every paragraph that contains
+words or phrases marked by a specified command. You could do this to
+construct an index of functions if you had not already made the
address@hidden
+
+The commands serve a variety of purposes:@refill
+
address@hidden @code
address@hidden @@address@hidden@address@hidden
+Indicate text that is a literal example of a piece of a address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate keyboard address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate the conventional name for a key on a address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate text that is a literal example of a sequence of address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate a metasyntactic address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate an environment address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate the name of a address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate the name of a address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate a command-line address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate the introductory or defining use of a address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate the name of a address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate an address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate a uniform resource locator for the World Wide Web.
+
address@hidden @@address@hidden@var{email-address}[, @address@hidden
+Indicate an electronic mail address.
+
address@hidden table
+
+
address@hidden code
address@hidden @code{@@address@hidden@address@hidden
address@hidden code
+
address@hidden Syntactic tokens, indicating
+Use the @code{@@code} command to indicate text that is a piece of a
+program and which consists of entire syntactic tokens. Enclose the
+text in braces.
+
address@hidden Expressions in a program, indicating
address@hidden Keywords, indicating
address@hidden Reserved words, indicating
+Thus, you should use @code{@@code} for an expression in a program, for
+the name of a variable or function used in a program, or for a
+keyword in a programming language.
+
+Use @code{@@code} for command names in languages that resemble
+programming languages, such as Texinfo. For example, @code{@@code} and
address@hidden@@samp} are produced by writing
@samp{@@address@hidden@@@@address@hidden and
address@hidden@@address@hidden@@@@address@hidden in the Texinfo source,
respectively.
+
address@hidden Case, not altering in @code{@@code}
+It is incorrect to alter the case of a word inside an @code{@@code}
+command when it appears at the beginning of a sentence. Most computer
+languages are case sensitive. In C, for example, @code{Printf} is
+different from the identifier @code{printf}, and most likely is a
+misspelling of it. Even in languages which are not case sensitive, it
+is confusing to a human reader to see identifiers spelled in different
+ways. Pick one spelling and always use that. If you do not want to
+start a sentence with a command name written all in lower case, you
+should rearrange the sentence.
+
+In the printed manual, @code{@@code} causes @TeX{} to typeset the
+argument in a typewriter face. In the Info file, it causes the Info
+formatting commands to use single quotation marks around the text.
+
address@hidden 700
+For example,
+
address@hidden
+The function returns @@address@hidden@}.
address@hidden example
+
address@hidden
+produces this in the printed manual:
+
address@hidden
+The function returns @code{nil}.
address@hidden quotation
+
+
+Here are some cases for which it is preferable not to use @code{@@code}:
+
address@hidden @bullet
address@hidden
+For shell command names such as @command{ls} (use @code{@@command}).
+
address@hidden
+For shell options such as @samp{-c} when such options stand alone (use
address@hidden@@option}).
+
address@hidden
+Also, an entire shell command often looks better if written using
address@hidden@@samp} rather than @code{@@code}. In this case, the rule is to
+choose the more pleasing format.
+
address@hidden
+For environment variable such as @env{TEXINPUTS} (use @code{@@env}).
+
address@hidden
+For a string of characters shorter than a syntactic token. For example,
+if you are writing about @samp{goto-ch}, which is just a part of the
+name for the @code{goto-char} Emacs Lisp function, you should use
address@hidden@@samp}.
+
address@hidden
+In general, when writing about the characters used in a token; for
+example, do not use @code{@@code} when you are explaining what letters
+or printable symbols can be used in the names of functions. (Use
address@hidden@@samp}.) Also, you should not use @code{@@code} to mark text
+that is considered input to programs unless the input is written in a
+language that is like a programming language. For example, you should
+not use @code{@@code} for the keystroke commands of GNU Emacs (use
address@hidden@@kbd} instead) although you may use @code{@@code} for the names
+of the Emacs Lisp functions that the keystroke commands invoke.
+
address@hidden itemize
+
+Since @code{@@command}, @code{@@option}, and @code{@@env} were
+introduced relatively recently, it is acceptable to use @code{@@code} or
address@hidden@@samp} for command names, options, and environment variables.
+The new commands allow you to express the markup more precisely, but
+there is no real harm in using the older commands, and of course the
+long-standing manuals do so.
+
+
address@hidden kbd
address@hidden @code{@@address@hidden@address@hidden
address@hidden kbd
address@hidden Keyboard input
+
+Use the @code{@@kbd} command for characters of input to be typed by
+users. For example, to refer to the characters @kbd{M-a},
address@hidden
+
address@hidden
+@@address@hidden@}
address@hidden example
+
address@hidden
+and to refer to the characters @kbd{M-x shell}, address@hidden
+
address@hidden
+@@address@hidden address@hidden
address@hidden example
+
address@hidden user input
address@hidden slanted typewriter font, for @code{@@kbd}
+The @code{@@kbd} command has the same effect as @code{@@code} in Info,
+but by default produces a different font (slanted typewriter instead of
+normal typewriter) in the printed manual, so users can distinguish the
+characters they are supposed to type from those the computer outputs.
+
address@hidden kbdinputstyle
+Since the usage of @code{@@kbd} varies from manual to manual, you can
+control the font switching with the @code{@@kbdinputstyle} command.
+This command has no effect on Info output. Write this command at the
+beginning of a line with a single word as an argument, one of the
+following:
address@hidden address@hidden, arg to @@kbdinputstyle}
address@hidden address@hidden, arg to @@kbdinputstyle}
address@hidden address@hidden, arg to @@kbdinputstyle}
address@hidden @samp
address@hidden code
+Always use the same font for @code{@@kbd} as @code{@@code}.
address@hidden example
+Use the distinguishing font for @code{@@kbd} only in @code{@@example}
+and similar environments.
address@hidden distinct
+(the default) Always use the distinguishing font for @code{@@kbd}.
address@hidden table
+
+You can embed another @@-command inside the braces of an @code{@@kbd}
+command. Here, for example, is the way to describe a command that
+would be described more verbosely as ``press an @samp{r} and then
+press the @key{RET} key'':@refill
+
address@hidden
+@@address@hidden @@address@hidden@address@hidden
address@hidden example
+
address@hidden
+This produces: @kbd{r @key{RET}}
+
+You also use the @code{@@kbd} command if you are spelling out the letters
+you type; for example:@refill
+
address@hidden
+To give the @@address@hidden@} command,
+type the characters @@address@hidden o g o u t @@address@hidden@address@hidden
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
+To give the @code{logout} command,
+type the characters @kbd{l o g o u t @key{RET}}.
address@hidden quotation
+
+(Also, this example shows that you can add spaces for clarity. If you
+really want to mention a space character as one of the characters of
+input, write @kbd{@@address@hidden@}} for it.)@refill
+
+
address@hidden key, samp, kbd, Indicating
address@hidden node-name, next, previous, up
address@hidden @code{@@address@hidden@address@hidden
address@hidden key
+
+Use the @code{@@key} command for the conventional name for a key on a
+keyboard, as in:@refill
+
address@hidden
+@@address@hidden@}
address@hidden example
+
+You can use the @code{@@key} command within the argument of an
address@hidden@@kbd} command when the sequence of characters to be typed
+includes one or more keys that are described by address@hidden
+
address@hidden 700
+For example, to produce @kbd{C-x @key{ESC}} you would type:@refill
+
address@hidden
+@@address@hidden @@address@hidden@address@hidden
address@hidden example
+
+Here is a list of the recommended names for keys:
address@hidden Recommended names for keys
address@hidden Keys, recommended names
address@hidden Names recommended for keys
address@hidden Abbreviations for keys
+
address@hidden
address@hidden @t
address@hidden SPC
+Space
address@hidden RET
+Return
address@hidden LFD
+Linefeed (however, since most keyboards nowadays do not have a Linefeed key,
+it might be better to call this character @kbd{C-j}.
address@hidden TAB
+Tab
address@hidden BS
+Backspace
address@hidden ESC
+Escape
address@hidden DEL
+Delete
address@hidden SHIFT
+Shift
address@hidden CTRL
+Control
address@hidden META
+Meta
address@hidden table
address@hidden quotation
+
address@hidden META key
+There are subtleties to handling words like `meta' or `ctrl' that are
+names of modifier keys. When mentioning a character in which the
+modifier key is used, such as @kbd{Meta-a}, use the @code{@@kbd} command
+alone; do not use the @code{@@key} command; but when you are referring
+to the modifier key in isolation, use the @code{@@key} command. For
+example, write @samp{@@address@hidden@}} to produce @kbd{Meta-a} and
address@hidden@@address@hidden@}} to produce @key{META}.
+
address@hidden I don't think this is a good explanation.
address@hidden I think it will puzzle readers more than it clarifies matters.
-- rms.
address@hidden In other words, use @code{@@kbd} for what you do, and use
@code{@@key}
address@hidden for what you talk about: ``Press @code{@@address@hidden@}} to
move point to
address@hidden the beginning of the sentence. The @code{@@address@hidden@}}
key is often in
address@hidden the lower left of the keyboard.''@refill
+
address@hidden samp
address@hidden @code{@@address@hidden@address@hidden
address@hidden samp
+
+Use the @code{@@samp} command to indicate text that is a literal example
+or `sample' of a sequence of characters in a file, string, pattern, etc.
+Enclose the text in braces. The argument appears within single
+quotation marks in both the Info file and the printed manual; in
+addition, it is printed in a fixed-width address@hidden
+
address@hidden
+To match @@address@hidden@} at the end of the line,
+use the regexp @@address@hidden@}.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+To match @samp{foo} at the end of the line, use the regexp
address@hidden@refill
address@hidden quotation
+
+Any time you are referring to single characters, you should use
address@hidden@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate.
+Also, you may use @code{@@samp} for entire statements in C and for entire
+shell commands---in this case, @code{@@samp} often looks better than
address@hidden@@code}. Basically, @code{@@samp} is a catchall for whatever is
+not covered by @code{@@code}, @code{@@kbd}, or @code{@@address@hidden
+
+Only include punctuation marks within braces if they are part of the
+string you are specifying. Write punctuation marks outside the braces
+if those punctuation marks are part of the English text that surrounds
+the string. In the following sentence, for example, the commas and
+period are outside of the braces:@refill
+
address@hidden
address@hidden
+In English, the vowels are @@address@hidden@}, @@address@hidden@},
+@@address@hidden@}, @@address@hidden@}, @@address@hidden@}, and sometimes
+@@address@hidden@}.
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
+In English, the vowels are @samp{a}, @samp{e},
address@hidden, @samp{o}, @samp{u}, and sometimes
address@hidden
address@hidden quotation
+
+
address@hidden verb
address@hidden @code{@@address@hidden<char>@var{text}<char>@}
address@hidden verb
address@hidden Verbatim in-line text
+
address@hidden Delimiter character, for verbatim
+Use the @code{@@verb} command to print a verbatim sequence of
+characters.
+
+Like address@hidden's @code{\verb} command, the verbatim text can be quoted
using
+any unique delimiter character. Enclose the verbatim text, including the
+delimiters, in braces. Text is printed in a fixed-width font:
+
address@hidden
+How many @@address@hidden|@@|@}-escapes does one need to print this
+@@address@hidden@@a @@b @@address@hidden string or
@@address@hidden@@'address@hidden@address@hidden@address@hidden this?
address@hidden example
+
address@hidden
+produces
+
address@hidden
+How many @verb{|@ |}-escapes does one need to print this
address@hidden@a @b @c.} string or these @verb{+@'e?`{}!`\+} this?
address@hidden example
+
+This is in contrast to @code{@@samp} (see the previous
+section), whose argument is normal Texinfo text, where the characters
address@hidden@@@address@hidden are special; with @code{@@verb}, nothing is
special except
+the delimiter character you choose.
+
+
address@hidden var
address@hidden @code{@@address@hidden@address@hidden
address@hidden var
+
+Use the @code{@@var} command to indicate metasyntactic variables. A
address@hidden variable} is something that stands for another piece of
+text. For example, you should use a metasyntactic variable in the
+documentation of a function to describe the arguments that are passed
+to that address@hidden
+
+Do not use @code{@@var} for the names of particular variables in
+programming languages. These are specific names from a program, so
address@hidden@@code} is correct for them (@pxref{code}). For example, the
+Emacs Lisp variable @code{texinfo-tex-command} is not a metasyntactic
+variable; it is properly formatted using @code{@@code}.
+
+Do not use @code{@@var} for environment variables either; @code{@@env}
+is correct for them (see the next section).
+
+The effect of @code{@@var} in the Info file is to change the case of the
+argument to all upper case. In the printed manual and HTML output, the
+argument is printed in slanted type.
+
address@hidden 700
+For example,
+
address@hidden
+To delete file @@address@hidden@},
+type @@address@hidden @@address@hidden@address@hidden
address@hidden example
+
address@hidden
+produces
+
address@hidden
+To delete file @var{filename}, type @samp{rm @var{filename}}.
address@hidden quotation
+
address@hidden
+(Note that @code{@@var} may appear inside @code{@@code},
address@hidden@@samp}, @code{@@file}, etc.)@refill
+
+Write a metasyntactic variable all in lower case without spaces, and
+use hyphens to make it more readable. Thus, the Texinfo source for
+the illustration of how to begin a Texinfo manual looks like
+this:@refill
+
address@hidden
address@hidden
+\input texinfo
+@@@@setfilename @@address@hidden@}
+@@@@settitle @@address@hidden@}
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
address@hidden
+\input texinfo
+@@setfilename @var{info-file-name}
+@@settitle @var{name-of-manual}
address@hidden group
address@hidden example
+
+In some documentation styles, metasyntactic variables are shown with
+angle brackets, for example:@refill
+
address@hidden
address@hidden, type rm <filename>
address@hidden example
+
address@hidden
+However, that is not the style that Texinfo uses. (You can, of
+course, modify the sources to @file{texinfo.tex} and the Info formatting
commands
+to output the @code{<@dots{}>} format if you wish.)@refill
+
+
address@hidden env
address@hidden @code{@@address@hidden@address@hidden
address@hidden env
+
+Use the @code{@@env} command to indicate environment variables, as used
+by many operating systems, including GNU. Do not use it for
+metasyntactic variables; use @code{@@var} instead (see the previous
+section).
+
address@hidden@@env} is equivalent to @code{@@code} in its effects.
+For example:
+
address@hidden
+The @@address@hidden@} environment variable @dots{}
address@hidden example
address@hidden produces
address@hidden
+The @env{PATH} environment variable @dots{}
address@hidden quotation
+
+
address@hidden file
address@hidden @code{@@address@hidden@address@hidden
address@hidden file
+
+Use the @code{@@file} command to indicate text that is the name of a
+file, buffer, or directory, or is the name of a node in Info. You can
+also use the command for file name suffixes. Do not use @code{@@file}
+for symbols in a programming language; use @code{@@code}.
+
+Currently, @code{@@file} is equivalent to @code{@@samp} in its effects.
+For example,@refill
+
address@hidden
+The @@address@hidden@} files are in
+the @@address@hidden/usr/local/emacs/address@hidden directory.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+The @file{.el} files are in
+the @file{/usr/local/emacs/lisp} directory.
address@hidden quotation
+
+
address@hidden command
address@hidden @code{@@address@hidden@address@hidden
address@hidden command
address@hidden Command names, indicating
address@hidden Program names, indicating
+
+Use the @code{@@command} command to indicate command names, such as
address@hidden or @command{cc}.
+
address@hidden@@command} is equivalent to @code{@@code} in its effects.
+For example:
+
address@hidden
+The command @@address@hidden@} lists directory contents.
address@hidden example
address@hidden produces
address@hidden
+The command @command{ls} lists directory contents.
address@hidden quotation
+
+You should write the name of a program in the ordinary text font, rather
+than using @code{@@command}, if you regard it as a new English word,
+such as `Emacs' or `Bison'.
+
+When writing an entire shell command invocation, as in @samp{ls -l},
+you should use either @code{@@samp} or @code{@@code} at your discretion.
+
+
address@hidden option
address@hidden @code{@@address@hidden@address@hidden
address@hidden option
+
+Use the @code{@@option} command to indicate a command-line option; for
+example, @option{-l} or @option{--version} or
address@hidden@var{filename}}.
+
address@hidden@@option} is equivalent to @code{@@samp} in its effects.
+For example:
+
address@hidden
+The option @@address@hidden@} produces a long listing.
address@hidden example
address@hidden produces
address@hidden
+The option @option{-l} produces a long listing.
address@hidden quotation
+
+In tables, putting options inside @code{@@code} produces a
+more pleasing effect.
+
address@hidden dfn
address@hidden node-name, next, previous, up
address@hidden @code{@@address@hidden@address@hidden
address@hidden dfn
+
+Use the @code{@@dfn} command to identify the introductory or defining
+use of a technical term. Use the command only in passages whose
+purpose is to introduce a term which will be used again or which the
+reader ought to know. Mere passing mention of a term for the first
+time does not deserve @code{@@dfn}. The command generates italics in
+the printed manual, and double quotation marks in the Info file. For
+example:@refill
+
address@hidden
+Getting rid of a file is called @@address@hidden@} it.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+Getting rid of a file is called @dfn{deleting} it.
address@hidden quotation
+
+As a general rule, a sentence containing the defining occurrence of a
+term should be a definition of the term. The sentence does not need
+to say explicitly that it is a definition, but it should contain the
+information of a definition---it should make the meaning clear.
+
address@hidden cite
address@hidden @code{@@address@hidden@address@hidden
address@hidden cite
+
+Use the @code{@@cite} command for the name of a book that lacks a
+companion Info file. The command produces italics in the printed
+manual, and quotation marks in the Info file.
+
+If a book is written in Texinfo, it is better to use a cross reference
+command since a reader can easily follow such a reference in Info.
address@hidden, , @code{@@xref}}.
+
+
+
+
address@hidden acronym
address@hidden @code{@@address@hidden@address@hidden
address@hidden acronym
+
address@hidden NASA, as acronym
address@hidden F.B.I., as acronym
address@hidden Abbreviations, tagging
address@hidden Acronyms, tagging
+Use the @code{@@acronym} command for abbreviations written in all
+capital letters, such as address@hidden'. The abbreviation is given as
+the single argument in braces, as in @samp{@@address@hidden@}}. As
+a matter of style, or for particular abbreviations, you may prefer to
+use periods, as in @samp{@@address@hidden@}}.
+
+In @TeX{} and HTML, the argument is printed in a slightly smaller font
+size. In Info or plain text output, this command changes nothing.
+
+
address@hidden url
address@hidden @code{@@address@hidden@address@hidden
address@hidden url
address@hidden Uniform resource locator, indicating
address@hidden URL, indicating
+
+Use the @code{@@url} command to indicate a uniform resource locator on
+the World Wide Web. This is analogous to @code{@@file}, @code{@@var},
+etc., and is purely for markup purposes. It does not produce a link you
+can follow in HTML output (use the @code{@@uref} command for that,
address@hidden,, @code{@@uref}}). It is useful for url's which do
+not actually exist. For example:
+
address@hidden Two lines because one is too long for smallbook format.
address@hidden
+For example, the url might be @@address@hidden://example.org/address@hidden
address@hidden example
+
address@hidden which produces:
+
address@hidden
+For example, the url might be @url{http://example.org/path}.
address@hidden display
+
+
address@hidden email
address@hidden @code{@@address@hidden@var{email-address}[, @address@hidden
address@hidden email
+
+Use the @code{@@email} command to indicate an electronic mail address.
+It takes one mandatory argument, the address, and one optional argument, the
+text to display (the default is the address itself).
+
address@hidden mailto link
+In Info and @TeX{}, the address is shown in angle brackets, preceded by
+the text to display if any. In HTML output, @code{@@email} produces a
address@hidden link that usually brings up a mail composition window.
+For example:
+
address@hidden
+Send bug reports to @@address@hidden@@@@address@hidden,
+suggestions to the @@address@hidden@@@@gnu.org, same address@hidden
address@hidden example
address@hidden produces
address@hidden
+Send bug reports to @email{bug-texinfo@@gnu.org},
+suggestions to the @email{bug-texinfo@@gnu.org, same place}.
address@hidden display
+
+
address@hidden Emphasis
address@hidden node-name, next, previous, up
address@hidden Emphasizing Text
address@hidden Emphasizing text
+
+Usually, Texinfo changes the font to mark words in the text according to
+what category the words belong to; an example is the @code{@@code} command.
+Most often, this is the best way to mark words.
+However, sometimes you will want to emphasize text without indicating a
+category. Texinfo has two commands to do this. Also, Texinfo has
+several commands that specify the font in which @TeX{} will typeset
+text. These commands have no effect on Info and only one of them,
+the @code{@@r} command, has any regular address@hidden
+
address@hidden
+* emph & strong:: How to emphasize text in Texinfo.
+* Smallcaps:: How to use the small caps font.
+* Fonts:: Various font commands for printed output.
address@hidden menu
+
address@hidden emph & strong
address@hidden @code{@@address@hidden@address@hidden and
@code{@@address@hidden@address@hidden
address@hidden Emphasizing text, font for
address@hidden emph
address@hidden strong
+
+The @code{@@emph} and @code{@@strong} commands are for emphasis;
address@hidden@@strong} is stronger. In printed output, @code{@@emph} produces
address@hidden and @code{@@strong} produces @strong{bold}.
+
address@hidden 800
+For example,
+
address@hidden
address@hidden
+@@quotation
+@@address@hidden:@} @@address@hidden * address@hidden removes
@@address@hidden@}
+files in the directory.
+@@end quotation
address@hidden group
address@hidden example
+
address@hidden
+produces:
+
address@hidden
+ *Caution*: `rm * .[^.]*' removes _all_
+ files in the directory.
address@hidden example
+
+The @code{@@strong} command is seldom used except to mark what is, in
+effect, a typographical element, such as the word `Caution' in the
+preceding example.
+
+In the Info output, @code{@@emph} surrounds the text with underscores
+(@samp{_}), and @code{@@strong} puts asterisks around the text.
+
address@hidden
address@hidden:} Do not use @code{@@strong} with the word @samp{Note};
+Info will mistake the combination for a cross reference. Use a phrase
+such as @strong{Please note} or @strong{Caution} instead.
address@hidden quotation
+
+
address@hidden Smallcaps
address@hidden @code{@@address@hidden@address@hidden: The Small Caps Font
address@hidden Small caps font
address@hidden sc @r{(small caps font)}
+
+Use the @samp{@@sc} command to set text in the printed and the HTML
+output in @sc{a small caps font} and set text in the Info file in upper
+case letters. Write the text you want to be in small caps (where
+possible) between braces in lower case, like this:
+
address@hidden
+The @@address@hidden@} and @@address@hidden@} are technical societies.
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
+The @sc{acm} and @sc{ieee} are technical societies.
address@hidden display
+
address@hidden typesets the small caps font in a manner that prevents the
+letters from `jumping out at you on the page'. This makes small caps
+text easier to read than text in all upper case---but it's usually
+better to use regular mixed case anyway. The Info formatting commands
+set all small caps text in upper case. In HTML, the text is upper-cased
+and a smaller font is used to render it.
+
+If the text between the braces of an @code{@@sc} command is uppercase,
address@hidden typesets in FULL-SIZE CAPITALS. Use full-size capitals
+sparingly, if ever, and since it's redundant to mark all-uppercase text
+with @code{@@sc}, @command{makeinfo} warns about such usage.
+
+You may also use the small caps font for a jargon word such as
address@hidden (a @sc{nasa} word meaning `abort to orbit').
+
+There are subtleties to using the small caps font with a jargon word
+such as @sc{cdr}, a word used in Lisp programming. In this case, you
+should use the small caps font when the word refers to the second and
+subsequent elements of a list (the @sc{cdr} of the list), but you
+should use @samp{@@code} when the word refers to the Lisp function of
+the same spelling.
+
+
address@hidden Fonts
address@hidden Fonts for Printing, Not Info
address@hidden Fonts for printing, not for Info
address@hidden i @r{(italic font)}
address@hidden b @r{(bold font)}
address@hidden t @r{(typewriter font)}
address@hidden r @r{(Roman font)}
+
+Texinfo provides four font commands that specify font changes in the
+printed manual but have no effect in the Info file. @code{@@i}
+requests @i{italic} font (in some versions of @TeX{}, a slanted font
+is used), @code{@@b} requests @b{bold} face, @code{@@t} requests the
address@hidden, typewriter-style font used by @code{@@code}, and @code{@@r}
requests a
address@hidden font, which is the usual font in which text is printed. All
+four commands apply to an argument that follows, surrounded by
address@hidden
+
+Only the @code{@@r} command has much use: in example programs, you
+can use the @code{@@r} command to convert code comments from the
+fixed-width font to a roman font. This looks better in printed
address@hidden
+
address@hidden 700
+For example,
+
address@hidden
address@hidden
+@@lisp
+(+ 2 2) ; @@address@hidden two plus address@hidden
+@@end lisp
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
+(+ 2 2) ; @r{Add two plus two.}
address@hidden lisp
+
+If possible, you should avoid using the other three font commands. If
+you need to use one, it probably indicates a gap in the Texinfo
+language.
+
+
address@hidden Quotations and Examples
address@hidden Quotations and Examples
+
+Quotations and examples are blocks of text consisting of one or more
+whole paragraphs that are set off from the bulk of the text and
+treated differently. They are usually address@hidden
+
+In Texinfo, you always begin a quotation or example by writing an
+@@-command at the beginning of a line by itself, and end it by writing
+an @code{@@end} command that is also at the beginning of a line by
+itself. For instance, you begin an example by writing @code{@@example}
+by itself at the beginning of a line and end the example by writing
address@hidden@@end example} on a line by itself, at the beginning of that
+line.
address@hidden end
+
address@hidden
+* Block Enclosing Commands:: Different constructs for different purposes.
+* quotation:: Writing a quotation.
+* example:: Writing an example in a fixed-width font.
+* verbatim:: Writing a verbatim example.
+* verbatiminclude:: Including a file verbatim.
+* lisp:: Illustrating Lisp code.
+* small:: Forms for @code{@@smallbook}.
+* display:: Writing an example in the current font.
+* format:: Writing an example without narrowed margins.
+* exdent:: Undo indentation on a line.
+* flushleft & flushright:: Pushing text flush left or flush right.
+* noindent:: Preventing paragraph indentation.
+* cartouche:: Drawing rounded rectangles around examples.
address@hidden menu
+
+
address@hidden Block Enclosing Commands
address@hidden Block Enclosing Commands
+
+Here are commands for quotations and examples, explained further in the
+following sections:
+
address@hidden @code
address@hidden @@quotation
+Indicate text that is quoted. The text is filled, indented, and
+printed in a roman font by default.
+
address@hidden @@example
+Illustrate code, commands, and the like. The text is printed
+in a fixed-width font, and indented but not filled.
+
address@hidden @@verbatim
+Mark a piece of text that is to be printed verbatim; no character
+substitutions are made and all commands are ignored, until the next
address@hidden@@end verbatim}. The text is printed in a fixed-width font,
+and not indented or filled. Extra spaces and blank lines are
+significant, and tabs are expanded.
+
address@hidden @@smallexample
+Same as @code{@@example}, except that in @TeX{} this command typesets
+text in a smaller font.
+
address@hidden @@lisp
+Like @code{@@example}, but specifically for illustrating Lisp code. The
+text is printed in a fixed-width font, and indented but not filled.
+
address@hidden @@smalllisp
+Is to @code{@@lisp} as @code{@@smallexample} is to @code{@@example}.
+
address@hidden @@display
+Display illustrative text. The text is indented but not filled, and
+no font is selected (so, by default, the font is roman)address@hidden
+
address@hidden @@smalldisplay
+Is to @code{@@display} as @code{@@smallexample} is to @code{@@example}.
+
address@hidden @@format
+Like @code{@@display} (the text is not filled and no font is selected),
+but the text is not indented.
+
address@hidden @@smallformat
+Is to @code{@@format} as @code{@@smallexample} is to @code{@@example}.
address@hidden table
+
+The @code{@@exdent} command is used within the above constructs to
+undo the indentation of a line.
+
+The @code{@@flushleft} and @code{@@flushright} commands are used to line
+up the left or right margins of unfilled address@hidden
+
+The @code{@@noindent} command may be used after one of the above
+constructs to prevent the following text from being indented as a new
+paragraph.
+
+You can use the @code{@@cartouche} command within one of the above
+constructs to highlight the example or quotation by drawing a box with
+rounded corners around it. @xref{cartouche, , Drawing Cartouches Around
+Examples}.
+
+
address@hidden quotation
address@hidden @code{@@quotation}
address@hidden Quotations
address@hidden quotation
+
+The text of a quotation is processed normally except that:
+
address@hidden @bullet
address@hidden
+the margins are closer to the center of the page, so the whole of the
+quotation is indented;@refill
+
address@hidden
+the first lines of paragraphs are indented no more than other
+lines;@refill
+
address@hidden
+in the printed output, interparagraph spacing is address@hidden
address@hidden itemize
+
address@hidden
+This is an example of text written between an @code{@@quotation}
+command and an @code{@@end quotation} command. An @code{@@quotation}
+command is most often used to indicate text that is excerpted from
+another (real or hypothetical) printed address@hidden
address@hidden quotation
+
+Write an @code{@@quotation} command as text on a line by itself. This
+line will disappear from the output. Mark the end of the quotation
+with a line beginning with and containing only @code{@@end quotation}.
+The @code{@@end quotation} line will likewise disappear from the
+output. Thus, the following,@refill
+
address@hidden
+@@quotation
+This is
+a foo.
+@@end quotation
address@hidden example
+
address@hidden
+produces
+
address@hidden
+This is a foo.
address@hidden quotation
+
+
address@hidden example
address@hidden @code{@@example}: Example Text
address@hidden Examples, formatting them
address@hidden Formatting examples
address@hidden example
+
+The @code{@@example} command is used to indicate an example that is
+not part of the running text, such as computer input or output.
+
address@hidden
address@hidden
+This is an example of text written between an
address@hidden@@example} command
+and an @code{@@end example} command.
+The text is indented but not filled.
address@hidden group
+
address@hidden
+In the printed manual, the text is typeset in a
+fixed-width font, and extra spaces and blank lines are
+significant. In the Info file, an analogous result is
+obtained by indenting each line with five spaces.
address@hidden group
address@hidden example
+
+Write an @code{@@example} command at the beginning of a line by itself.
+Mark the end of the example
+with an @code{@@end example} command, also written at the beginning of a
+line by address@hidden
+
address@hidden 700
+For example,
+
address@hidden
+@@example
+mv foo bar
+@@end example
address@hidden example
+
address@hidden
+produces
+
address@hidden
+mv foo bar
address@hidden example
+
+The lines containing @code{@@example} and @code{@@end example}
+will disappear from the output.
+To make the output look good,
+you should put a blank line before the
address@hidden@@example} and another blank line after the @code{@@end example}.
+Note that blank lines inside the beginning
address@hidden@@example} and the ending @code{@@end example} will appear in
+the address@hidden
+
address@hidden
address@hidden:} Do not use tabs in the lines of an example or anywhere
+else in Texinfo (except in verbatim environments)! The @TeX{}
+implementation of Texinfo treats tabs as single spaces, and that is not
+what they look like. (If necessary, in Emacs, you can use @kbd{M-x
+untabify} to convert tabs in a region to multiple spaces.)@refill
address@hidden quotation
+
+Examples are often, logically speaking, ``in the middle'' of a
+paragraph, and the text that continues after an example should not be
+indented. The @code{@@noindent} command prevents a piece of text from
+being indented as if it were a new paragraph.
+(@xref{noindent}.)
+
+(The @code{@@code} command is used for examples of code that are
+embedded within sentences, not set off from preceding and following
+text. @xref{code, , @code{@@code}}.)
+
+
address@hidden verbatim
address@hidden @code{@@verbatim}: Literal Text
address@hidden verbatim
address@hidden Verbatim environment
+
+Use the @code{@@verbatim} environment for printing of text that may
+contain special characters or commands that should not be interpreted,
+such as computer input or output (@code{@@example} interprets its text
+as regular Texinfo commands). This is especially useful for including
+automatically generated output in a Texinfo manual. Here is an example;
+the output you see is just the same as the input, with a line
address@hidden@@verbatim} before and a line @code{@@end verbatim} after.
+
address@hidden
+This is an example of text written in a @verbatim
+block. No character substitutions are made. All commands
+are ignored, until `<at>end verbatim'.
+
+In the printed manual, the text is typeset in a
+fixed-width font, and not indented or filled. All
+spaces and blank lines are significant, including tabs.
address@hidden verbatim
+
+Write a @code{@@verbatim} command at the beginning of a line by itself.
+This line will disappear from the output. Mark the end of the verbatim
+block with a @code{@@end verbatim} command, also written at the
+beginning of a line by itself. The @code{@@end verbatim} will also
+disappear from the output.
+
+For example:
address@hidden oops, got to trick this a bit: can't use @end verbatim inside
@verbatim
+
address@hidden
address@hidden @@verbatim
address@hidden @{
address@hidden <tab>@@command with strange characters: @@'e
address@hidden expand<tab>me
address@hidden @}
address@hidden @@end verbatim
address@hidden example
+
address@hidden
+produces
+
address@hidden
+{
+ @command with strange characters: @'e
+expand me
+}
address@hidden verbatim
+
+Since the lines containing @code{@@verbatim} and @code{@@end verbatim}
+produce no output, tyically you should put a blank line before the
address@hidden@@verbatim} and another blank line after the @code{@@end
+verbatim}. Blank lines between the beginning @code{@@verbatim} and the
+ending @code{@@end verbatim} will appear in the output.
+
+
address@hidden verbatiminclude
address@hidden @code{@@verbatiminclude} @var{file}: Include a File Verbatim
address@hidden Verbatim, include file
address@hidden Including a file verbatim
address@hidden verbatiminclude
+
+You can include the exact contents of a file in the document with the
address@hidden@@verbatiminclude} command:
+
address@hidden
+@@verbatiminclude @var{filename}
address@hidden example
+
+The contents of @var{filename} is printed in a verbatim environment
+(@pxref{verbatim,,@code{@@verbatim}}). Generally, the file is printed
+exactly as it is, with all special characters and white space retained.
+
+
address@hidden lisp
address@hidden @code{@@lisp}: Marking a Lisp Example
address@hidden lisp
address@hidden Lisp example
+
+The @code{@@lisp} command is used for Lisp code. It is synonymous
+with the @code{@@example} command.
+
address@hidden
+This is an example of text written between an
address@hidden@@lisp} command and an @code{@@end lisp} command.
address@hidden lisp
+
+Use @code{@@lisp} instead of @code{@@example} to preserve information
+regarding the nature of the example. This is useful, for example, if
+you write a function that evaluates only and all the Lisp code in a
+Texinfo file. Then you can use the Texinfo file as a Lisp
address@hidden would be straightforward to extend Texinfo to work
+in a similar fashion for C, Fortran, or other languages.}
+
+Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by
address@hidden
+
+
address@hidden small
address@hidden @code{@@address@hidden Block Commands
address@hidden Small examples
address@hidden Examples in smaller fonts
address@hidden Lisp examples in smaller fonts
address@hidden smalldisplay
address@hidden smallexample
address@hidden smallformat
address@hidden smalllisp
+
+In addition to the regular @code{@@example} and @code{@@lisp} commands,
+Texinfo has ``small'' example-style commands. These are
address@hidden@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, and
address@hidden@@smalllisp}.
+
+In @TeX{}, the @code{@@address@hidden commands typeset text in a smaller
+font than the non-small example commands. Consequently, many examples
+containing long lines fit on a page without needing to be shortened.
+
+In Info, the @code{@@address@hidden commands are equivalent to their
+non-small companion commands.
+
+Mark the end of an @code{@@address@hidden block with a corresponding
address@hidden@@end address@hidden For example, pair @code{@@smallexample} with
address@hidden@@end smallexample}.
+
address@hidden
+This is an example of text written between @code{@@smallexample} and
address@hidden@@end smallexample}. In Info this text appears in its normal
size;
+but in a 7 by 9.25 inch manual, this text appears in a smaller font.
address@hidden smallexample
+
+The @code{@@address@hidden commands make it easier to prepare manuals
+without forcing you to edit examples by hand to fit them onto narrower
+pages.
+
+As a general rule, a printed document looks better if you use only one
+of (for example) @code{@@example} or in @code{@@smallexample}
+consistently within a chapter. Only occasionally should you mix the two
+formats.
+
address@hidden, , Printing ``Small'' Books}, for more information
+about the @code{@@smallbook} command.
+
+
address@hidden display
address@hidden @code{@@display} and @code{@@smalldisplay}
address@hidden Display formatting
address@hidden display
+
+The @code{@@display} command begins a kind of example. It is like the
address@hidden@@example} command
+except that, in
+a printed manual, @code{@@display} does not select the fixed-width
+font. In fact, it does not specify the font at all, so that the text
+appears in the same font it would have appeared in without the
address@hidden@@display} address@hidden
+
address@hidden
+This is an example of text written between an @code{@@display} command
+and an @code{@@end display} command. The @code{@@display} command
+indents the text, but does not fill it.
address@hidden display
+
address@hidden smalldisplay
+Texinfo also provides a command @code{@@smalldisplay}, which is like
address@hidden@@display} but uses a smaller font in @code{@@smallbook} format.
address@hidden
+
+
address@hidden format
address@hidden @code{@@format} and @code{@@smallformat}
address@hidden format
+
+The @code{@@format} command is similar to @code{@@example} except
+that, in the printed manual, @code{@@format} does not select the
+fixed-width font and does not narrow the address@hidden
+
address@hidden
+This is an example of text written between an @code{@@format} command
+and an @code{@@end format} command. As you can see
+from this example,
+the @code{@@format} command does not fill the text.
address@hidden format
+
address@hidden smallformat
+Texinfo also provides a command @code{@@smallformat}, which is like
address@hidden@@format} but uses a smaller font in @code{@@smallbook} format.
address@hidden
+
+
+
address@hidden exdent
address@hidden @code{@@exdent}: Undoing a Line's Indentation
address@hidden Indentation undoing
address@hidden exdent
+
+The @code{@@exdent} command removes any indentation a line might have.
+The command is written at the beginning of a line and applies only to
+the text that follows the command that is on the same line. Do not use
+braces around the text. In a printed manual, the text on an
address@hidden@@exdent} line is printed in the roman address@hidden
+
address@hidden@@exdent} is usually used within examples. Thus,@refill
+
address@hidden
address@hidden
+@@example
+This line follows an @@@@example command.
+@@exdent This line is exdented.
+This line follows the exdented line.
+The @@@@end example comes on the next line.
+@@end group
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+This line follows an @@example command.
address@hidden This line is exdented.
+This line follows the exdented line.
+The @@end example comes on the next line.
address@hidden group
address@hidden example
+
+In practice, the @code{@@exdent} command is rarely used.
+Usually, you un-indent text by ending the example and
+returning the page to its normal address@hidden
+
+
address@hidden flushleft & flushright
address@hidden @code{@@flushleft} and @code{@@flushright}
address@hidden flushleft
address@hidden flushright
address@hidden ragged right
address@hidden ragged left
+
+The @code{@@flushleft} and @code{@@flushright} commands line up the
+ends of lines on the left and right margins of a page,
+but do not fill the text. The commands are written on lines of their
+own, without braces. The @code{@@flushleft} and @code{@@flushright}
+commands are ended by @code{@@end flushleft} and @code{@@end
+flushright} commands on lines of their address@hidden
+
address@hidden 1500
+For example,
+
address@hidden
address@hidden
+@@flushleft
+This text is
+written flushleft.
+@@end flushleft
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+This text is
+written flushleft.
address@hidden flushleft
address@hidden quotation
+
+
address@hidden@@flushright} produces the type of indentation often used in the
+return address of letters. For example,
+
address@hidden
address@hidden
+@@flushright
+Here is an example of text written
+flushright. The @@address@hidden@@address@hidden command
+right justifies every line but leaves the
+left end ragged.
+@@end flushright
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
+Here is an example of text written
+flushright. The @code{@@flushright} command
+right justifies every line but leaves the
+left end ragged.
address@hidden flushright
+
+
address@hidden noindent
address@hidden @code{@@noindent}: Omitting Indentation
address@hidden noindent
+
+An example or other inclusion can break a paragraph into segments.
+Ordinarily, the formatters indent text that follows an example as a new
+paragraph. However, you can prevent this by writing @code{@@noindent}
+at the beginning of a line by itself preceding the continuation
address@hidden
+
address@hidden 1500
+For example:
+
address@hidden
address@hidden
+@@example
+This is an example
+@@end example
+
+@@noindent
+This line is not indented. As you can see, the
+beginning of the line is fully flush left with the line
+that follows after it. (This whole example is between
+@@address@hidden@@@@address@hidden and @@address@hidden@@@@end address@hidden)
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+This is an example
address@hidden example
address@hidden
+% Remove extra vskip; this is a kludge to counter the effect of display
+\vskip-3.5\baselineskip
address@hidden tex
+
address@hidden
+This line is not indented. As you can see, the
+beginning of the line is fully flush left with the line
+that follows after it. (This whole example is between
address@hidden@@display} and @code{@@end display}.)
address@hidden display
+
+To adjust the number of blank lines properly in the Info file output,
+remember that the line containing @code{@@noindent} does not generate a
+blank line, and neither does the @code{@@end example} address@hidden
+
+In the Texinfo source file for this manual, each line that says
+`produces' is preceded by a line containing @code{@@address@hidden
+
+Do not put braces after an @code{@@noindent} command; they are not
+necessary, since @code{@@noindent} is a command used outside of
+paragraphs (@pxref{Command Syntax})address@hidden
+
+
address@hidden cartouche
address@hidden @code{@@cartouche}: Rounded Rectangles Around Examples
address@hidden cartouche
address@hidden Box with rounded corners
address@hidden Rounded rectangles, around examples
+
+In a printed manual, the @code{@@cartouche} command draws a box with
+rounded corners around its contents. You can use this command to
+further highlight an example or quotation. For instance, you could
+write a manual in which one type of example is surrounded by a cartouche
+for emphasis.
+
address@hidden@@cartouche} affects only the printed manual; it has no effect in
+other output files.
+
address@hidden 1500
+For example,
+
address@hidden
address@hidden
+@@example
+@@cartouche
+% pwd
+/usr/local/share/emacs
+@@end cartouche
+@@end example
address@hidden group
address@hidden example
+
address@hidden
+surrounds the two-line example with a box with rounded corners, in the
+printed manual.
+
+
+
address@hidden Lists and Tables
address@hidden Lists and Tables
address@hidden Making lists and tables
address@hidden Lists and tables, making
address@hidden Tables and lists, making
+
+Texinfo has several ways of making lists and tables. Lists can be
+bulleted or numbered; two-column tables can highlight the items in
+the first column; multi-column tables are also supported.
+
address@hidden
+* Introducing Lists:: Texinfo formats lists for you.
+* itemize:: How to construct a simple list.
+* 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.
address@hidden menu
+
address@hidden Introducing Lists, itemize, Lists and Tables, Lists and Tables
address@hidden Introducing Lists
+
+Texinfo automatically indents the text in lists or tables, and numbers
+an enumerated list. This last feature is useful if you modify the
+list, since you do not need to renumber it address@hidden
+
+Numbered lists and tables begin with the appropriate @@-command at the
+beginning of a line, and end with the corresponding @code{@@end}
+command on a line by itself. The table and itemized-list commands
+also require that you write formatting information on the same line as
+the beginning @@address@hidden
+
+Begin an enumerated list, for example, with an @code{@@enumerate}
+command and end the list with an @code{@@end enumerate} command.
+Begin an itemized list with an @code{@@itemize} command, followed on
+the same line by a formatting command such as @code{@@bullet}, and end
+the list with an @code{@@end itemize} address@hidden
address@hidden end
+
+Precede each element of a list with an @code{@@item} or @code{@@itemx}
address@hidden
+
address@hidden 1
address@hidden
+Here is an itemized list of the different kinds of table and lists:@refill
+
address@hidden @bullet
address@hidden
+Itemized lists with and without bullets.
+
address@hidden
+Enumerated lists, using numbers or letters.
+
address@hidden
+Two-column tables with highlighting.
address@hidden itemize
+
address@hidden 1
address@hidden
+Here is an enumerated list with the same items:@refill
+
address@hidden
address@hidden
+Itemized lists with and without bullets.
+
address@hidden
+Enumerated lists, using numbers or letters.
+
address@hidden
+Two-column tables with highlighting.
address@hidden enumerate
+
address@hidden 1
address@hidden
+And here is a two-column table with the same items and their
address@hidden@@-commands}:@refill
+
address@hidden @code
address@hidden @@itemize
+Itemized lists with and without bullets.
+
address@hidden @@enumerate
+Enumerated lists, using numbers or letters.
+
address@hidden @@table
address@hidden @@ftable
address@hidden @@vtable
+Two-column tables, optionally with indexing.
address@hidden table
+
+
address@hidden itemize
address@hidden @code{@@itemize}: Making an Itemized List
address@hidden Itemization
address@hidden itemize
+
+The @code{@@itemize} command produces sequences of indented
+paragraphs, with a bullet or other mark inside the left margin
+at the beginning of each paragraph for which such a mark is address@hidden
+
address@hidden @code{@@w}, for blank items
+Begin an itemized list by writing @code{@@itemize} at the beginning of
+a line. Follow the command, on the same line, with a character or a
+Texinfo command that generates a mark. Usually, you will write
address@hidden@@bullet} after @code{@@itemize}, but you can use
address@hidden@@minus}, or any command or character that results in a single
+character in the Info file. If you don't want any mark at all, use
address@hidden@@w}. (When you write the mark command such as
address@hidden@@bullet} after an @code{@@itemize} command, you may omit the
address@hidden@address@hidden) If you don't specify a mark command, the
default is
address@hidden@@bullet}.
+
+Write the text of the indented paragraphs themselves after the
address@hidden@@itemize}, up to another line that says @code{@@end
address@hidden
+
address@hidden item
+Before each paragraph for which a mark in the margin is desired, write a
+line that says just @code{@@item}. It is ok to have text following the
address@hidden@@item}.
+
+Usually, you should put a blank line before an @code{@@item}. This
+puts a blank line in the Info file. (@TeX{} inserts the proper
+interline whitespace in either case.) Except when the entries are
+very brief, these blank lines make the list look address@hidden
+
+Here is an example of the use of @code{@@itemize}, followed by the
+output it produces. @code{@@bullet} produces an @samp{*} in Info and a
+round dot in @TeX{}.
+
address@hidden
address@hidden
+@@itemize @@bullet
+@@item
+Some text for foo.
+
+@@item
+Some text
+for bar.
+@@end itemize
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
address@hidden @bullet
address@hidden
+Some text for foo.
+
address@hidden
+Some text
+for bar.
address@hidden itemize
address@hidden quotation
+
+Itemized lists may be embedded within other itemized lists. Here is a
+list marked with dashes embedded in a list marked with bullets:@refill
+
address@hidden
address@hidden
+@@itemize @@bullet
+@@item
+First item.
+
+@@itemize @@minus
+@@item
+Inner item.
+
+@@item
+Second inner item.
+@@end itemize
+
+@@item
+Second outer item.
+@@end itemize
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
address@hidden @bullet
address@hidden
+First item.
+
address@hidden @minus
address@hidden
+Inner item.
+
address@hidden
+Second inner item.
address@hidden itemize
+
address@hidden
+Second outer item.
address@hidden itemize
address@hidden quotation
+
+
address@hidden enumerate
address@hidden @code{@@enumerate}: Making a Numbered or Lettered List
address@hidden Enumeration
address@hidden enumerate
+
address@hidden@@enumerate} is like @code{@@itemize} (@pxref{itemize,,
address@hidden@@itemize}}), except that the labels on the items are
+successive integers or letters instead of bullets.
+
+Write the @code{@@enumerate} command at the beginning of a line. The
+command does not require an argument, but accepts either a number or a
+letter as an option. Without an argument, @code{@@enumerate} starts the
+list with the number @samp{1}. With a numeric argument, such as
address@hidden, the command starts the list with that number. With an upper
+or lower case letter, such as @samp{a} or @samp{A}, the command starts
+the list with that letter.
+
+Write the text of the enumerated list in the same way you write an
+itemized list: put @code{@@item} on a line of its own before the start
+of each paragraph that you want enumerated. Do not write any other text
+on the line beginning with @code{@@item}.
+
+You should put a blank line between entries in the list.
+This generally makes it easier to read the Info file.
+
address@hidden 1500
+Here is an example of @code{@@enumerate} without an argument:
+
address@hidden
address@hidden
+@@enumerate
+@@item
+Underlying causes.
+
+@@item
+Proximate causes.
+@@end enumerate
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden
address@hidden
+Underlying causes.
+
address@hidden
+Proximate causes.
address@hidden enumerate
address@hidden 1
+Here is an example with an argument of @kbd{3}:@refill
address@hidden 1
address@hidden
address@hidden
+@@enumerate 3
+@@item
+Predisposing causes.
+
+@@item
+Precipitating causes.
+
+@@item
+Perpetuating causes.
+@@end enumerate
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden 3
address@hidden
+Predisposing causes.
+
address@hidden
+Precipitating causes.
+
address@hidden
+Perpetuating causes.
address@hidden enumerate
address@hidden 1
+Here is a brief summary of the alternatives. The summary is constructed
+using @code{@@enumerate} with an argument of @address@hidden
address@hidden 1
address@hidden a
address@hidden
address@hidden@@enumerate}
+
+Without an argument, produce a numbered list, starting with the number
address@hidden
+
address@hidden
address@hidden@@enumerate @var{positive-integer}}
+
+With a (positive) numeric argument, start a numbered list with that
+number. You can use this to continue a list that you interrupted with
+other address@hidden
+
address@hidden
address@hidden@@enumerate @var{upper-case-letter}}
+
+With an upper case letter as argument, start a list
+in which each item is marked
+by a letter, beginning with that upper case address@hidden
+
address@hidden
address@hidden@@enumerate @var{lower-case-letter}}
+
+With a lower case letter as argument, start a list
+in which each item is marked by
+a letter, beginning with that lower case address@hidden
address@hidden enumerate
+
+You can also nest enumerated lists, as in an address@hidden
+
address@hidden Two-column Tables, Multi-column Tables, enumerate, Lists and
Tables
address@hidden Making a Two-column Table
address@hidden Tables, making two-column
address@hidden table
+
address@hidden@@table} is similar to @code{@@itemize} (@pxref{itemize,,
address@hidden@@itemize}}), but allows you to specify a name or heading line for
+each item. The @code{@@table} command is used to produce two-column
+tables, and is especially useful for glossaries, explanatory
+exhibits, and command-line option summaries.
+
address@hidden
+* table:: How to construct a two-column table.
+* ftable vtable:: Automatic indexing for two-column tables.
+* itemx:: How to put more entries in the first column.
address@hidden menu
+
address@hidden table, ftable vtable, Two-column Tables, Two-column Tables
address@hidden Using the @code{@@table} Command
+
+Use the @code{@@table} command to produce two-column address@hidden
+
+Write the @code{@@table} command at the beginning of a line and follow
+it on the same line with an argument that is a Texinfo ``indicating''
+command such as @code{@@code}, @code{@@samp}, @code{@@var}, or
address@hidden@@kbd} (@pxref{Indicating}). Although these commands are usually
+followed by arguments in braces, in this case you use the command name
+without an argument because @code{@@item} will supply the argument.
+This command will be applied to the text that goes into the first column
+of each item and determines how it will be highlighted. For example,
address@hidden@@code} will cause the text in the first column to be highlighted
+with an @code{@@code} command. (We recommend @code{@@code} for
address@hidden@@table}'s of command-line options.)
+
address@hidden asis
+You may also choose to use the @code{@@asis} command as an argument to
address@hidden@@table}. @code{@@asis} is a command that does nothing; if you
+use this command after @code{@@table}, @TeX{} and the Info formatting
+commands output the first column entries without added highlighting
+(``as is'')address@hidden
+
+(The @code{@@table} command may work with other commands besides those
+listed here. However, you can only use commands that normally take
+arguments in braces.)@refill
+
address@hidden item
+Begin each table entry with an @code{@@item} command at the beginning
+of a line. Write the first column text on the same line as the
address@hidden@@item} command. Write the second column text on the line
+following the @code{@@item} line and on subsequent lines. (You do not
+need to type anything for an empty second column entry.) You may
+write as many lines of supporting text as you wish, even several
+paragraphs. But only text on the same line as the @code{@@item} will
+be placed in the first column, including any footnote.
+
+Normally, you should put a blank line before an @code{@@item} line.
+This puts a blank like in the Info file. Except when the entries are
+very brief, a blank line looks address@hidden
+
address@hidden 1500
+The following table, for example, highlights the text in the first
+column with an @code{@@samp} command:@refill
+
address@hidden
address@hidden
+@@table @@samp
+@@item foo
+This is the text for
+@@address@hidden@}.
+
+@@item bar
+Text for @@address@hidden@}.
+@@end table
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden @samp
address@hidden foo
+This is the text for
address@hidden
address@hidden bar
+Text for @samp{bar}.
address@hidden table
+
+If you want to list two or more named items with a single block of
+text, use the @code{@@itemx} command. (@xref{itemx, ,
address@hidden@@itemx}}.)@refill
+
+
address@hidden ftable vtable
address@hidden @code{@@ftable} and @code{@@vtable}
address@hidden Tables with indexes
address@hidden Indexing table entries automatically
address@hidden ftable
address@hidden vtable
+
+The @code{@@ftable} and @code{@@vtable} commands are the same as the
address@hidden@@table} command except that @code{@@ftable} automatically enters
+each of the items in the first column of the table into the index of
+functions and @code{@@vtable} automatically enters each of the items in
+the first column of the table into the index of variables. This
+simplifies the task of creating indices. Only the items on the same
+line as the @code{@@item} commands are indexed, and they are indexed in
+exactly the form that they appear on that line. @xref{Indices},
+for more information about address@hidden
+
+Begin a two-column table using @code{@@ftable} or @code{@@vtable} by
+writing the @@-command at the beginning of a line, followed on the same
+line by an argument that is a Texinfo command such as @code{@@code},
+exactly as you would for an @code{@@table} command; and end the table
+with an @code{@@end ftable} or @code{@@end vtable} command on a line by
+itself.
+
+See the example for @code{@@table} in the previous section.
+
address@hidden itemx
address@hidden @code{@@itemx}
address@hidden Two named items for @code{@@table}
address@hidden itemx
+
+Use the @code{@@itemx} command inside a table when you have two or more
+first column entries for the same item, each of which should appear on a
+line of its own. Use @code{@@itemx} for all but the first entry;
address@hidden@@itemx} should always follow an @code{@@item} command. The
address@hidden@@itemx} command works exactly like @code{@@item} except that it
+does not generate extra vertical space above the first column text.
+
+For example,
+
address@hidden
address@hidden
+@@table @@code
+@@item upcase
+@@itemx downcase
+These two functions accept a character or a string as
+argument, and return the corresponding upper case (lower
+case) character or string.
+@@end table
address@hidden group
address@hidden example
+
address@hidden
+This produces:
+
address@hidden @code
address@hidden upcase
address@hidden downcase
+These two functions accept a character or a string as
+argument, and return the corresponding upper case (lower
+case) character or address@hidden
address@hidden table
+
address@hidden
+(Note also that this example illustrates multi-line supporting text in
+a two-column table.)@refill
+
+
address@hidden Multi-column Tables, , Two-column Tables, Lists and Tables
address@hidden Multi-column Tables
address@hidden Tables, making multi-column
address@hidden multitable
+
address@hidden@@multitable} allows you to construct tables with any number of
+columns, with each column having any width you like.
+
+You define the column widths on the @code{@@multitable} line itself, and
+write each row of the actual table following an @code{@@item} command,
+with columns separated by an @code{@@tab} command. Finally, @code{@@end
+multitable} completes the table. Details in the sections below.
+
address@hidden
+* Multitable Column Widths:: Defining multitable column widths.
+* Multitable Rows:: Defining multitable rows, with examples.
address@hidden menu
+
address@hidden Multitable Column Widths
address@hidden Multitable Column Widths
address@hidden Multitable column widths
address@hidden Column widths, defining for multitables
address@hidden Widths, defining multitable column
+
+You can define the column widths for a multitable in two ways: as
+fractions of the line length; or with a prototype row. Mixing the two
+methods is not supported. In either case, the widths are defined
+entirely on the same line as the @code{@@multitable} command.
+
address@hidden
address@hidden
address@hidden columnfractions
address@hidden Line length, column widths as fraction of
+To specify column widths as fractions of the line length, write
address@hidden@@columnfractions} and the decimal numbers (presumably less than
+1) after the @code{@@multitable} command, as in:
+
address@hidden
+@@multitable @@columnfractions .33 .33 .33
address@hidden example
+
address@hidden The fractions need not add up exactly to 1.0, as these do
+not. This allows you to produce tables that do not need the full line
+length. You can use a leading zero if you wish.
+
address@hidden
address@hidden Prototype row, column widths defined by
+To specify a prototype row, write the longest entry for each column
+enclosed in braces after the @code{@@multitable} command. For example:
+
address@hidden
+@@multitable @{some text for column address@hidden @{for column address@hidden
address@hidden example
+
address@hidden
+The first column will then have the width of the typeset `some text for
+column one', and the second column the width of `for column two'.
+
+The prototype entries need not appear in the table itself.
+
+Although we used simple text in this example, the prototype entries can
+contain Texinfo commands; markup commands such as @code{@@code} are
+particularly likely to be useful.
+
address@hidden enumerate
+
+
address@hidden Multitable Rows, , Multitable Column Widths, Multi-column Tables
address@hidden Multitable Rows
address@hidden Multitable rows
address@hidden Rows, of a multitable
+
address@hidden item
address@hidden tab
+After the @code{@@multitable} command defining the column widths (see
+the previous section), you begin each row in the body of a multitable
+with @code{@@item}, and separate the column entries with @code{@@tab}.
+Line breaks are not special within the table body, and you may break
+input lines in your source file as necessary.
+
+Here is a complete example of a multi-column table (the text is from
address@hidden GNU Emacs Manual}, @pxref{Split Window,, Splitting Windows,
+emacs, The GNU Emacs Manual}):
+
address@hidden
+@@multitable @@columnfractions .15 .45 .4
+@@item Key @@tab Command @@tab Description
+@@item C-x 2
+@@tab @@address@hidden@}
+@@tab Split the selected window into two windows,
+with one above the other.
+@@item C-x 3
+@@tab @@address@hidden@}
+@@tab Split the selected window into two windows
+positioned side by side.
+@@item C-Mouse-2
+@@tab
+@@tab In the mode line or scroll bar of a window,
+split that window.
+@@end multitable
address@hidden example
+
address@hidden produces:
+
address@hidden @columnfractions .15 .45 .4
address@hidden Key @tab Command @tab Description
address@hidden C-x 2
address@hidden @code{split-window-vertically}
address@hidden Split the selected window into two windows,
+with one above the other.
address@hidden C-x 3
address@hidden @code{split-window-horizontally}
address@hidden Split the selected window into two windows
+positioned side by side.
address@hidden C-Mouse-2
address@hidden
address@hidden In the mode line or scroll bar of a window,
+split that window.
address@hidden multitable
+
+
address@hidden Indices, Insertions, Lists and Tables, Top
address@hidden node-name, next, previous, up
address@hidden Indices
address@hidden Indices
+
+Using Texinfo, you can generate indices without having to sort and
+collate entries manually. In an index, the entries are listed in
+alphabetical order, together with information on how to find the
+discussion of each entry. In a printed manual, this information
+consists of page numbers. In an Info file, this information is a menu
+entry leading to the first node address@hidden
+
+Texinfo provides several predefined kinds of index: an index
+for functions, an index for variables, an index for concepts, and so
+on. You can combine indices or use them for other than their
+canonical purpose. If you wish, you can define your own address@hidden
+
address@hidden
+* Index Entries:: Choose different words for index entries.
+* Predefined Indices:: Use different indices for different kinds
+ of entry.
+* Indexing Commands:: How to make an index entry.
+* Combining Indices:: How to combine indices.
+* New Indices:: How to define your own indices.
address@hidden menu
+
address@hidden Index Entries, Predefined Indices, Indices, Indices
address@hidden node-name, next, previous, up
address@hidden Making Index Entries
address@hidden Index entries, making
address@hidden Entries, making index
+
+When you are making index entries, it is good practice to think of the
+different ways people may look for something. Different people
address@hidden not} think of the same words when they look something up. A
+helpful index will have items indexed under all the different words
+that people may use. For example, one reader may think it obvious that
+the two-letter names for indices should be listed under ``Indices,
+two-letter names'', since the word ``Index'' is the general concept.
+But another reader may remember the specific concept of two-letter
+names and search for the entry listed as ``Two letter names for
+indices''. A good index will have both entries and will help both
address@hidden
+
+Like typesetting, the construction of an index is a highly skilled,
+professional art, the subtleties of which are not appreciated until you
+need to do it address@hidden
+
address@hidden Indices & Menus}, for information about printing an index
+at the end of a book or creating an index menu in an Info address@hidden
+
address@hidden Predefined Indices, Indexing Commands, Index Entries, Indices
address@hidden node-name, next, previous, up
address@hidden Predefined Indices
+
+Texinfo provides six predefined indices:@refill
+
address@hidden @bullet
address@hidden
+A @dfn{concept index} listing concepts that are address@hidden
+
address@hidden
+A @dfn{function index} listing functions (such as entry points of
+libraries)address@hidden
+
address@hidden
+A @dfn{variables index} listing variables (such as global variables
+of libraries)address@hidden
+
address@hidden
+A @dfn{keystroke index} listing keyboard address@hidden
+
address@hidden
+A @dfn{program index} listing names of address@hidden
+
address@hidden
+A @dfn{data type index} listing data types (such as structures defined in
+header files)address@hidden
address@hidden itemize
+
address@hidden
+Not every manual needs all of these, and most manuals use two or three
+of them. This manual has two indices: a
+concept index and an @@-command index (that is actually the function
+index but is called a command index in the chapter heading). Two or
+more indices can be combined into one using the @code{@@synindex} or
address@hidden@@syncodeindex} commands. @xref{Combining address@hidden
+
address@hidden Indexing Commands, Combining Indices, Predefined Indices, Indices
address@hidden node-name, next, previous, up
address@hidden Defining the Entries of an Index
address@hidden Defining indexing entries
address@hidden Index entries
address@hidden Entries for an index
address@hidden Specifying index entries
address@hidden Creating index entries
+
+The data to make an index come from many individual indexing commands
+scattered throughout the Texinfo source file. Each command says to add
+one entry to a particular index; after formatting, the index will give
+the current page number or node name as the address@hidden
+
+An index entry consists of an indexing command at the beginning of a
+line followed, on the rest of the line, by the address@hidden
+
+For example, this section begins with the following five entries for
+the concept index:@refill
+
address@hidden
+@@cindex Defining indexing entries
+@@cindex Index entries
+@@cindex Entries for an index
+@@cindex Specifying index entries
+@@cindex Creating index entries
address@hidden example
+
+Each predefined index has its own indexing address@hidden@@cindex}
+for the concept index, @code{@@findex} for the function index, and so
address@hidden
+
address@hidden Writing index entries
address@hidden Index entry writing
+Concept index entries consist of text. The best way to write an index
+is to choose entries that are terse yet clear. If you can do this,
+the index often looks better if the entries are not capitalized, but
+written just as they would appear in the middle of a sentence.
+(Capitalize proper names and acronyms that always call for upper case
+letters.) This is the case convention we use in most GNU manuals'
+indices.
+
+If you don't see how to make an entry terse yet clear, make it longer
+and clear---not terse and confusing. If many of the entries are several
+words long, the index may look better if you use a different convention:
+to capitalize the first word of each entry. But do not capitalize a
+case-sensitive name such as a C or Lisp function name or a shell
+command; that would be a spelling error.
+
+Whichever case convention you use, please use it consistently!
+
+Entries in indices other than the concept index are symbol names in
+programming languages, or program names; these names are usually
+case-sensitive, so use upper and lower case as required for them.
+
+By default, entries for a concept index are printed in a small roman
+font and entries for the other indices are printed in a small
address@hidden@@code} font. You may change the way part of an entry is
+printed with the usual Texinfo commands, such as @code{@@file} for
+file names and @code{@@emph} for emphasis (@pxref{Marking
+Text})address@hidden
address@hidden Index font types
+
address@hidden Predefined indexing commands
address@hidden Indexing commands, predefined
+The six indexing commands for predefined indices are:
+
address@hidden @code
address@hidden @@cindex @var{concept}
address@hidden cindex
+Make an entry in the concept index for @address@hidden
+
address@hidden @@findex @var{function}
address@hidden findex
+Make an entry in the function index for @address@hidden
+
address@hidden @@vindex @var{variable}
address@hidden vindex
+Make an entry in the variable index for @address@hidden
+
address@hidden @@kindex @var{keystroke}
address@hidden kindex
+Make an entry in the key index for @address@hidden
+
address@hidden @@pindex @var{program}
address@hidden pindex
+Make an entry in the program index for @address@hidden
+
address@hidden @@tindex @var{data type}
address@hidden tindex
+Make an entry in the data type index for @var{data address@hidden
address@hidden table
+
address@hidden
address@hidden:} Do not use a colon in an index entry. In Info, a
+colon separates the menu entry name from the node name, so a colon in
+the entry itself confuses Info. @xref{Menu Parts, , The Parts of a
+Menu}, for more information about the structure of a menu entry.
address@hidden quotation
+
+You are not actually required to use the predefined indices for their
+canonical purposes. For example, suppose you wish to index some C
+preprocessor macros. You could put them in the function index along
+with actual functions, just by writing @code{@@findex} commands for
+them; then, when you print the ``Function Index'' as an unnumbered
+chapter, you could give it the title `Function and Macro Index' and
+all will be consistent for the reader. Or you could put the macros in
+with the data types by writing @code{@@tindex} commands for them, and
+give that index a suitable title so the reader will understand.
+(@xref{Printing Indices & Menus}.)@refill
+
address@hidden Combining Indices, New Indices, Indexing Commands, Indices
address@hidden node-name, next, previous, up
address@hidden Combining Indices
address@hidden Combining indices
address@hidden Indices, combining them
+
+Sometimes you will want to combine two disparate indices such as functions
+and concepts, perhaps because you have few enough of one of them that
+a separate index for them would look address@hidden
+
+You could put functions into the concept index by writing
address@hidden@@cindex} commands for them instead of @code{@@findex} commands,
+and produce a consistent manual by printing the concept index with the
+title `Function and Concept Index' and not printing the `Function
+Index' at all; but this is not a robust procedure. It works only if
+your document is never included as part of another
+document that is designed to have a separate function index; if your
+document were to be included with such a document, the functions from
+your document and those from the other would not end up together.
+Also, to make your function names appear in the right font in the
+concept index, you would need to enclose every one of them between
+the braces of @code{@@address@hidden
+
address@hidden
+* syncodeindex:: How to merge two indices, using @code{@@code}
+ font for the merged-from index.
+* synindex:: How to merge two indices, using the
+ default font of the merged-to index.
address@hidden menu
+
address@hidden syncodeindex
address@hidden @code{@@syncodeindex}
address@hidden syncodeindex
+
+When you want to combine functions and concepts into one index, you
+should index the functions with @code{@@findex} and index the concepts
+with @code{@@cindex}, and use the @code{@@syncodeindex} command to
+redirect the function index entries into the concept address@hidden
address@hidden syncodeindex
+
+The @code{@@syncodeindex} command takes two arguments; they are the name
+of the index to redirect, and the name of the index to redirect it to.
+The template looks like this:@refill
+
address@hidden
+@@syncodeindex @var{from} @var{to}
address@hidden example
+
address@hidden Predefined names for indices
address@hidden Two letter names for indices
address@hidden Indices, two letter names
address@hidden Names for indices
+For this purpose, the indices are given two-letter names:@refill
+
address@hidden @samp
address@hidden cp
+concept index
address@hidden fn
+function index
address@hidden vr
+variable index
address@hidden ky
+key index
address@hidden pg
+program index
address@hidden tp
+data type index
address@hidden table
+
+Write an @code{@@syncodeindex} command before or shortly after the
+end-of-header line at the beginning of a Texinfo file. For example,
+to merge a function index with a concept index, write the
+following:@refill
+
address@hidden
+@@syncodeindex fn cp
address@hidden example
+
address@hidden
+This will cause all entries designated for the function index to merge
+in with the concept index address@hidden
+
+To merge both a variables index and a function index into a concept
+index, write the following:@refill
+
address@hidden
address@hidden
+@@syncodeindex vr cp
+@@syncodeindex fn cp
address@hidden group
address@hidden example
+
address@hidden Fonts for indices
+The @code{@@syncodeindex} command puts all the entries from the `from'
+index (the redirected index) into the @code{@@code} font, overriding
+whatever default font is used by the index to which the entries are
+now directed. This way, if you direct function names from a function
+index into a concept index, all the function names are printed in the
address@hidden@@code} font as you would address@hidden
+
address@hidden synindex, , syncodeindex, Combining Indices
address@hidden @code{@@synindex}
address@hidden synindex
+
+The @code{@@synindex} command is nearly the same as the
address@hidden@@syncodeindex} command, except that it does not put the
+`from' index entries into the @code{@@code} font; rather it puts
+them in the roman font. Thus, you use @code{@@synindex} when you
+merge a concept index into a function address@hidden
+
address@hidden Indices & Menus}, for information about printing an index
+at the end of a book or creating an index menu in an Info address@hidden
+
address@hidden New Indices, , Combining Indices, Indices
address@hidden Defining New Indices
address@hidden Defining new indices
address@hidden Indices, defining new
address@hidden New index defining
address@hidden defindex
address@hidden defcodeindex
+
+In addition to the predefined indices, you may use the
address@hidden@@defindex} and @code{@@defcodeindex} commands to define new
+indices. These commands create new indexing @@-commands with which
+you mark index entries. The @code{@@defindex }command is used like
+this:@refill
+
address@hidden
+@@defindex @var{name}
address@hidden example
+
+The name of an index should be a two letter word, such as @samp{au}.
+For example:@refill
+
address@hidden
+@@defindex au
address@hidden example
+
+This defines a new index, called the @samp{au} index. At the same
+time, it creates a new indexing command, @code{@@auindex}, that you
+can use to make index entries. Use the new indexing command just as
+you would use a predefined indexing address@hidden
+
+For example, here is a section heading followed by a concept index
+entry and two @samp{au} index address@hidden
+
address@hidden
+@@section Cognitive Semantics
+@@cindex kinesthetic image schemas
+@@auindex Johnson, Mark
+@@auindex Lakoff, George
address@hidden example
+
address@hidden
+(Evidently, @samp{au} serves here as an abbreviation for ``author''.)
+Texinfo constructs the new indexing command by concatenating the name
+of the index with @samp{index}; thus, defining an @samp{au} index
+leads to the automatic creation of an @code{@@auindex} address@hidden
+
+Use the @code{@@printindex} command to print the index, as you do with
+the predefined indices. For example:@refill
+
address@hidden
address@hidden
+@@node Author Index, Subject Index, , Top
+@@unnumbered Author Index
+
+@@printindex au
address@hidden group
address@hidden example
+
+The @code{@@defcodeindex} is like the @code{@@defindex} command, except
+that, in the printed output, it prints entries in an @code{@@code} font
+instead of a roman font. Thus, it parallels the @code{@@findex} command
+rather than the @code{@@cindex} address@hidden
+
+You should define new indices within or right after the end-of-header
+line of a Texinfo file, before any @code{@@synindex} or
address@hidden@@syncodeindex} commands (@pxref{Texinfo File Header}).
+
+
address@hidden Insertions
address@hidden Special Insertions
address@hidden Inserting special characters and symbols
address@hidden Special insertions
+
+Texinfo provides several commands for inserting characters that have
+special meaning in Texinfo, such as braces, and for other graphic
+elements that do not correspond to simple characters you can type.
+
+
address@hidden
+* Braces Atsigns:: How to insert braces, @samp{@@}.
+* Inserting Space:: How to insert the right amount of space
+ within a sentence.
+* Inserting Accents:: How to insert accents and special characters.
+* Dots Bullets:: How to insert dots and bullets.
+* TeX and copyright:: How to insert the @TeX{} logo
+ and the copyright symbol.
+* pounds:: How to insert the pounds currency symbol.
+* minus:: How to insert a minus sign.
+* math:: How to format a mathematical expression.
+* Glyphs:: How to indicate results of evaluation,
+ expansion of macros, errors, etc.
+* Footnotes:: How to include footnotes.
+* Images:: How to include graphics.
address@hidden menu
+
+
address@hidden Braces Atsigns, Inserting Space, Insertions, Insertions
address@hidden Inserting @@ and Braces
address@hidden Inserting @@, braces
address@hidden Braces, inserting
address@hidden Special characters, commands to insert
address@hidden Commands to insert special characters
+
address@hidden@@} and curly braces are special characters in Texinfo. To insert
+these characters so they appear in text, you must put an @samp{@@} in
+front of these characters to prevent Texinfo from misinterpreting
+them.
+
+Do not put braces after any of these commands; they are not
+necessary.
+
address@hidden
+* Inserting An Atsign:: How to insert @samp{@@}.
+* Inserting Braces:: How to insert @address@hidden and
@address@hidden
address@hidden menu
+
address@hidden Inserting An Atsign, Inserting Braces, Braces Atsigns, Braces
Atsigns
address@hidden Inserting @samp{@@} with @@@@
address@hidden @@ @r{(literal @samp{@@})}
+
address@hidden@@@@} stands for a single @samp{@@} in either printed or Info
+output.
+
+Do not put braces after an @code{@@@@} command.
+
+
address@hidden Inserting Braces
address@hidden Inserting @address@hidden and @address@hidden @@@{ and @@@}
address@hidden @{ @r{(literal @address@hidden)}
address@hidden @} @r{(literal @address@hidden)}
+
address@hidden@@@{} stands for a single @address@hidden in either printed or
Info
+output.
+
address@hidden@@@}} stands for a single @address@hidden in either printed or
Info
+output.
+
+Do not put braces after either an @code{@@@{} or an @code{@@@}}
+command.
+
+
address@hidden Inserting Space
address@hidden Inserting Space
+
address@hidden Inserting space
address@hidden Spacing, inserting
+The following sections describe commands that control spacing of various
+kinds within and after sentences.
+
address@hidden
+* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
+* Ending a Sentence:: Sometimes it does.
+* Multiple Spaces:: Inserting multiple spaces.
+* dmn:: How to format a dimension.
address@hidden menu
+
+
address@hidden Not Ending a Sentence
address@hidden Not Ending a Sentence
+
address@hidden Not ending a sentence
address@hidden Sentence non-ending punctuation
address@hidden Periods, inserting
+Depending on whether a period or exclamation point or question mark is
+inside or at the end of a sentence, less or more space is inserted after
+a period in a typeset manual. Since it is not always possible
+to determine when a period ends a sentence and when it is used
+in an abbreviation, special commands are needed in some circumstances.
+Usually, Texinfo can guess how to handle periods, so you do not need to
+use the special commands; you just enter a period as you would if you
+were using a typewriter, which means you put two spaces after the
+period, question mark, or exclamation mark that ends a sentence.
+
address@hidden <colon> @r{(suppress widening)}
+Use the @code{@@:}@: command after a period, question mark,
+exclamation mark, or colon that should not be followed by extra space.
+For example, use @code{@@:}@: after periods that end abbreviations
+which are not at the ends of sentences.
+
+For example,
+
address@hidden
+The s.o.p.@@: has three parts @dots{}
+The s.o.p. has three parts @dots{}
address@hidden example
+
address@hidden
+produces
+
address@hidden
+The s.o.p.@: has three parts @address@hidden
+The s.o.p. has three parts @dots{}
address@hidden quotation
+
address@hidden
+(Incidentally, @samp{s.o.p.} is an abbreviation for ``Standard Operating
+Procedure''.)
+
address@hidden@@:} has no effect on the Info output. Do not put braces after
address@hidden@@:}.
+
+
address@hidden Ending a Sentence, Multiple Spaces, Not Ending a Sentence,
Inserting Space
address@hidden Ending a Sentence
+
address@hidden Ending a Sentence
address@hidden Sentence ending punctuation
+
address@hidden . @r{(end of sentence)}
address@hidden ! @r{(end of sentence)}
address@hidden ? @r{(end of sentence)}
+Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an
+exclamation point, and @code{@@?}@: instead of a question mark at the end
+of a sentence that ends with a single capital letter. Otherwise, @TeX{}
+will think the letter is an abbreviation and will not insert the correct
+end-of-sentence spacing. Here is an example:
+
address@hidden
+Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@.
+Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+Give it to M.I.B. and to address@hidden Also, give it to address@hidden@*
+Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
address@hidden quotation
+
+In the Info file output, @code{@@.}@: is equivalent to a simple
address@hidden; likewise for @code{@@!}@: and @code{@@?}@:.
+
+The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to
+work well with the Emacs sentence motion commands (@pxref{Sentences,,,
+emacs, The GNU Emacs Manual}).
+
+Do not put braces after any of these commands.
+
+
address@hidden Multiple Spaces, dmn, Ending a Sentence, Inserting Space
address@hidden Multiple Spaces
+
address@hidden Multiple spaces
address@hidden Whitespace, inserting
address@hidden Space, inserting horizontal
address@hidden (space)
address@hidden (tab)
address@hidden (newline)
+
+Ordinarily, @TeX{} collapses multiple whitespace characters (space, tab,
+and newline) into a single space. Info output, on the other hand,
+preserves whitespace as you type it, except for changing a newline into
+a space; this is why it is important to put two spaces at the end of
+sentences in Texinfo documents.
+
+Occasionally, you may want to actually insert several consecutive
+spaces, either for purposes of example (what your program does with
+multiple spaces as input), or merely for purposes of appearance in
+headings or lists. Texinfo supports three commands:
address@hidden@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all of
+which insert a single space into the output. (Here,
address@hidden@@@kbd{SPACE}} represents an @samp{@@} character followed by a
+space, i.e., @samp{@@ }, and @kbd{TAB} and @kbd{NL} represent the tab
+character and end-of-line, i.e., when @samp{@@} is the last character on
+a line.)
+
+For example,
address@hidden
+Spacey@@ @@ @@ @@
+example.
address@hidden example
+
address@hidden produces
+
address@hidden
+Spacey@ @ @ @
+example.
address@hidden example
+
+Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by
address@hidden@@multitable} (@pxref{Multi-column Tables}).
+
+Do not follow any of these commands with braces.
+
+To produce a non-breakable space, see @ref{w, non-breakable space}.
+
+
address@hidden dmn
address@hidden @code{@@address@hidden@address@hidden: Format a Dimension
address@hidden Thin space between number, dimension
address@hidden Dimension formatting
address@hidden Format a dimension
address@hidden dmn
+
+At times, you may want to write @address@hidden or
address@hidden@dmn{in}} with little or no space between the number and the
+abbreviation for the dimension. You can use the @code{@@dmn} command
+to do this. On seeing the command, @TeX{} inserts just enough space
+for proper typesetting; the Info formatting commands insert no space
+at all, since the Info file does not require it.
+
+To use the @code{@@dmn} command, write the number and then follow it
+immediately, with no intervening space, by @code{@@dmn}, and then by
+the dimension within braces. For example,
+
address@hidden
+A4 paper is 8.27@@address@hidden@} wide.
address@hidden example
+
address@hidden
+produces
+
address@hidden
+A4 paper is address@hidden wide.
address@hidden quotation
+
+Not everyone uses this style. Some people prefer @address@hidden in.@@:}}
+or @address@hidden inches}} to @samp{8.27@@address@hidden@}} in the Texinfo
file.
+In these cases, however, the formatters may insert a line break between
+the number and the dimension, so use @code{@@w} (@pxref{w}). Also, if
+you write a period after an abbreviation within a sentence, you should
+write @samp{@@:} after the period to prevent @TeX{} from inserting extra
+whitespace, as shown here. @xref{Not Ending a Sentence}.
+
+
address@hidden Inserting Accents
address@hidden Inserting Accents
+
address@hidden Inserting accents
address@hidden Accents, inserting
address@hidden Floating accents, inserting
+
+Here is a table with the commands Texinfo provides for inserting
+floating accents. The commands with non-alphabetic names do not take
+braces around their argument (which is taken to be the next character).
+(Exception: @code{@@,} @emph{does} take braces around its argument.)
+This is so as to make the source as convenient to type and read as
+possible, since accented characters are very common in some languages.
+
address@hidden " @r{(umlaut accent)}
address@hidden Umlaut accent
address@hidden ' @r{(umlaut accent)}
address@hidden Acute accent
address@hidden = @r{(macron accent)}
address@hidden Macron accent
address@hidden ^ @r{(circumflex accent)}
address@hidden Circumflex accent
address@hidden ` @r{(grave accent)}
address@hidden Grave accent
address@hidden ~ @r{(tilde accent)}
address@hidden Tilde accent
address@hidden , @r{(cedilla accent)}
address@hidden Cedilla accent
address@hidden dotaccent
address@hidden Dot accent
address@hidden H @r{(Hungarian umlaut accent)}
address@hidden Hungarian umlaut accent
address@hidden ringaccent
address@hidden Ring accent
address@hidden tieaccent
address@hidden Tie-after accent
address@hidden u @r{(breve accent)}
address@hidden Breve accent
address@hidden ubaraccent
address@hidden Underbar accent
address@hidden udotaccent
address@hidden Underdot accent
address@hidden v @r{(check accent)}
address@hidden Check accent
address@hidden {@@address@hidden@}} {Output} {macron/overbar accent}
address@hidden Command @tab Output @tab What
address@hidden @t{@@"o} @tab @"o @tab umlaut accent
address@hidden @t{@@'o} @tab @'o @tab acute accent
address@hidden @t{@@,@address@hidden @tab @,{c} @tab cedilla
accent
address@hidden @t{@@=o} @tab @=o @tab macron/overbar
accent
address@hidden @t{@@^o} @tab @^o @tab circumflex accent
address@hidden @t{@@`o} @tab @`o @tab grave accent
address@hidden @t{@@~o} @tab @~o @tab tilde accent
address@hidden @t{@@address@hidden@}} @tab @dotaccent{o} @tab overdot accent
address@hidden @t{@@address@hidden@}} @tab @H{o} @tab long
Hungarian umlaut
address@hidden @t{@@address@hidden@}} @tab @ringaccent{o} @tab ring accent
address@hidden @t{@@address@hidden@}} @tab @tieaccent{oo} @tab tie-after accent
address@hidden @t{@@address@hidden@}} @tab @u{o} @tab breve
accent
address@hidden @t{@@address@hidden@}} @tab @ubaraccent{o} @tab underbar accent
address@hidden @t{@@address@hidden@}} @tab @udotaccent{o} @tab underdot accent
address@hidden @t{@@address@hidden@}} @tab @v{o} @tab hacek
or check accent
address@hidden multitable
+
+This table lists the Texinfo commands for inserting other characters
+commonly used in languages other than English.
+
address@hidden questiondown
address@hidden @questiondown{}
address@hidden exclamdown
address@hidden @exclamdown{}
address@hidden aa
address@hidden @aa{}
address@hidden AA
address@hidden @AA{}
address@hidden ae
address@hidden @ae{}
address@hidden AE
address@hidden @AE{}
address@hidden dotless
address@hidden @dotless{i}
address@hidden @dotless{j}
address@hidden Dotless i, j
address@hidden l
address@hidden @l{}
address@hidden L
address@hidden @L{}
address@hidden o
address@hidden @o{}
address@hidden O
address@hidden @O{}
address@hidden oe
address@hidden @oe{}
address@hidden OE
address@hidden @OE{}
address@hidden ss
address@hidden @ss{}
address@hidden Es-zet
address@hidden Sharp S
address@hidden German S
address@hidden {x@@address@hidden@}} {oe,OE} {es-zet or sharp S}
address@hidden @t{@@address@hidden@}} @tab @exclamdown{} @tab upside-down !
address@hidden @t{@@address@hidden@}} @tab @questiondown{} @tab upside-down ?
address@hidden @t{@@address@hidden@},@@address@hidden@}} @tab @aa{},@AA{}
@tab a,A with circle
address@hidden @t{@@address@hidden@},@@address@hidden@}} @tab @ae{},@AE{}
@tab ae,AE ligatures
address@hidden @t{@@address@hidden@}} @tab @dotless{i} @tab dotless i
address@hidden @t{@@address@hidden@}} @tab @dotless{j} @tab dotless j
address@hidden @t{@@address@hidden@},@@address@hidden@}} @tab @l{},@L{}
@tab suppressed-L,l
address@hidden @t{@@address@hidden@},@@address@hidden@}} @tab @o{},@O{}
@tab O,o with slash
address@hidden @t{@@address@hidden@},@@address@hidden@}} @tab @oe{},@OE{}
@tab oe,OE ligatures
address@hidden @t{@@address@hidden@}} @tab @ss{} @tab
es-zet or sharp S
address@hidden multitable
+
+
address@hidden Dots Bullets
address@hidden Inserting Ellipsis and Bullets
address@hidden Dots, inserting
address@hidden Bullets, inserting
address@hidden Ellipsis, inserting
address@hidden Inserting ellipsis
address@hidden Inserting dots
address@hidden Special typesetting commands
address@hidden Typesetting commands for dots, etc.
+
+An @dfn{ellipsis} (a line of dots) is not typeset as a string of
+periods, so a special command is used for ellipsis in Texinfo. The
address@hidden@@bullet} command is special, too. Each of these commands is
+followed by a pair of braces, @address@hidden@}}, without any whitespace
+between the name of the command and the braces. (You need to use braces
+with these commands because you can use them next to other text; without
+the braces, the formatters would be confused. @xref{Command Syntax, ,
+@@-Command Syntax}, for further information.)@refill
+
address@hidden
+* dots:: How to insert dots @dots{}
+* bullet:: How to insert a bullet.
address@hidden menu
+
+
address@hidden dots
address@hidden @code{@@address@hidden@} (@dots{}) and @code{@@address@hidden@}
(@enddots{})
address@hidden dots
address@hidden enddots
address@hidden Inserting dots
address@hidden Dots, inserting
+
+Use the @code{@@address@hidden@}} command to generate an ellipsis, which is
+three dots in a row, appropriately spaced, like this: address@hidden'. Do
+not simply write three periods in the input file; that would work for
+the Info file output, but would produce the wrong amount of space
+between the periods in the printed manual.
+
+Similarly, the @code{@@address@hidden@}} command generates an
+end-of-sentence ellipsis (four dots) @enddots{}
+
+
+
address@hidden bullet
address@hidden @code{@@address@hidden@} (@bullet{})
address@hidden bullet
+
+Use the @code{@@address@hidden@}} command to generate a large round dot, or
+the closest possible thing to one. In Info, an asterisk is address@hidden
+
+Here is a bullet: @bullet{}
+
+When you use @code{@@bullet} in @code{@@itemize}, you do not need to
+type the braces, because @code{@@itemize} supplies them.
+(@xref{itemize, , @code{@@itemize}}.)@refill
+
+
address@hidden TeX and copyright, pounds, Dots Bullets, Insertions
address@hidden Inserting @TeX{} and the Copyright Symbol
+
+The logo address@hidden' is typeset in a special fashion and it needs an
+@@-command. The copyright symbol, address@hidden', is also special.
+Each of these commands is followed by a pair of braces, @address@hidden@}},
+without any whitespace between the name of the command and the
address@hidden
+
address@hidden
+* tex:: How to insert the @TeX{} logo.
+* copyright symbol:: How to use @code{@@address@hidden@}.
address@hidden menu
+
+
address@hidden tex
address@hidden @code{@@address@hidden@} (@TeX{})
address@hidden tex (command)
+
+Use the @code{@@address@hidden@}} command to generate address@hidden'. In a
printed
+manual, this is a special logo that is different from three ordinary
+letters. In Info, it just looks like @samp{TeX}. The
address@hidden@@address@hidden@}} command is unique among Texinfo commands in
that the
address@hidden and the @samp{X} are in upper address@hidden
+
+
address@hidden copyright symbol
address@hidden @code{@@address@hidden@} (@copyright{})
address@hidden copyright
+
+Use the @code{@@address@hidden@}} command to generate address@hidden'. In
+a printed manual, this is a @samp{c} inside a circle, and in Info,
+this is @samp{(C)address@hidden
+
+
address@hidden pounds, minus, TeX and copyright, Insertions
address@hidden @code{@@address@hidden@} (@pounds{}): Pounds Sterling
address@hidden pounds
+
+Use the @code{@@address@hidden@}} command to generate address@hidden'. In a
+printed manual, this is the symbol for the currency pounds sterling.
+In Info, it is a @samp{#}. Other currency symbols are unfortunately not
+available.
+
+
address@hidden minus, math, pounds, Insertions
address@hidden @code{@@address@hidden@} (@minus{}): Inserting a Minus Sign
address@hidden minus
+
address@hidden em-dash
address@hidden hyphen
+Use the @code{@@address@hidden@}} command to generate a minus sign. In a
+fixed-width font, this is a single hyphen, but in a proportional font,
+the symbol is the customary length for a minus sign---a little longer
+than a hyphen, shorter than an em-dash:
+
address@hidden
address@hidden@minus{}} is a minus sign generated with
@samp{@@address@hidden@}},
+
+`-' is a hyphen generated with the character @samp{-},
+
+`---' is an em-dash for text.
address@hidden display
+
address@hidden
+In the fixed-width font used by Info, @code{@@address@hidden@}} is the same
+as a hyphen.
+
+You should not use @code{@@address@hidden@}} inside @code{@@code} or
address@hidden@@example} because the width distinction is not made in the
+fixed-width font they use.
+
+When you use @code{@@minus} to specify the mark beginning each entry in
+an itemized list, you do not need to type the braces
+(@pxref{itemize, , @code{@@itemize}}.)
+
+
address@hidden math
address@hidden @code{@@math}: Inserting Mathematical Expressions
address@hidden math
address@hidden Mathematical expressions
address@hidden Formulas, mathematical
+
+You can write a short mathematical expression with the @code{@@math}
+command. Write the mathematical expression between braces, like this:
+
address@hidden
+@@address@hidden(a + b)(a + b) = a^2 + 2ab + address@hidden
address@hidden example
+
address@hidden This produces the following in Info:
+
address@hidden
+(a + b)(a + b) = a^2 + 2ab + b^2
address@hidden example
+
+Thus, the @code{@@math} command has no effect on the Info output.
+
address@hidden@@math} implies @code{@@tex}. This not only makes it possible to
+write superscripts and subscripts (as in the above example), but also
+allows you to use any of the plain @TeX{} math control sequences. It's
+conventional to use @samp{\} instead of @samp{@@} for these commands.
+As in:
address@hidden
+@@address@hidden 2\pi \equiv \cos address@hidden
address@hidden example
+
address@hidden which looks like the input in Info and HTML:
address@hidden
+\sin 2\pi \equiv \cos 3\pi
address@hidden example
+
address@hidden \ @r{(literal \ in @code{@@math})}
+Since @samp{\} is an escape character inside @code{@@math}, you can use
address@hidden@@\} to get a literal backslash (@code{\\} will work in @TeX{},
+but you'll get the literal @samp{\\} in Info). @code{@@\} is not
+defined outside of @code{@@math}, since a @samp{\} ordinarily produces a
+literal @samp{\}.
+
+
address@hidden Displayed equations
address@hidden Equations, displayed
+For displayed equations, you must at present use @TeX{} directly
+(@pxref{Raw Formatter Commands}).
+
+
address@hidden Glyphs
address@hidden Glyphs for Examples
address@hidden Glyphs
address@hidden Examples, glyphs for
+
+In Texinfo, code is often illustrated in examples that are delimited
+by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and
address@hidden@@end lisp}. In such examples, you can indicate the results of
+evaluation or an expansion using @address@hidden or
address@hidden@expansion{}}. Likewise, there are commands to insert glyphs
+to indicate
+printed output, error messages, equivalence of expressions, and the
+location of address@hidden
+
+The glyph-insertion commands do not need to be used within an example, but
+most often they are. Every glyph-insertion command is followed by a pair of
+left- and right-hand address@hidden
+
address@hidden
+* Glyphs Summary::
+* result:: How to show the result of expression.
+* expansion:: How to indicate an expansion.
+* Print Glyph:: How to indicate printed output.
+* Error Glyph:: How to indicate an error message.
+* Equivalence:: How to indicate equivalence.
+* Point Glyph:: How to indicate the location of point.
address@hidden menu
+
+
address@hidden Glyphs Summary
address@hidden Glyphs Summary
+
+Here are the different glyph commands:@refill
+
address@hidden @asis
address@hidden @result{}
address@hidden@@address@hidden@}} points to the result of an address@hidden
+
address@hidden @expansion{}
address@hidden@@address@hidden@}} shows the results of a macro address@hidden
+
address@hidden @print{}
address@hidden@@address@hidden@}} indicates printed address@hidden
+
address@hidden @error{}
address@hidden@@address@hidden@}} indicates that the following text is an error
address@hidden
+
address@hidden @equiv{}
address@hidden@@address@hidden@}} indicates the exact equivalence of two
address@hidden
+
address@hidden @point{}
address@hidden@@address@hidden@}} shows the location of address@hidden
address@hidden table
+
address@hidden
+* result::
+* expansion::
+* Print Glyph::
+* Error Glyph::
+* Equivalence::
+* Point Glyph::
address@hidden menu
+
+
address@hidden result
address@hidden @code{@@address@hidden@}} (@result{}): Indicating Evaluation
address@hidden Result of an expression
address@hidden Indicating evaluation
address@hidden Evaluation glyph
address@hidden Value of an expression, indicating
address@hidden result
+
+Use the @code{@@address@hidden@}} command to indicate the result of
+evaluating an address@hidden
+
+The @code{@@address@hidden@}} command is displayed as @address@hidden in Info
+and as a double stemmed arrow in the printed address@hidden
+
+Thus, the following,
+
address@hidden
+(cdr '(1 2 3))
+ @result{} (2 3)
address@hidden lisp
+
address@hidden
+may be read as address@hidden(cdr '(1 2 3))} evaluates to @code{(2 3)}''.
+
+
address@hidden expansion, Print Glyph, result, Glyphs
address@hidden @code{@@address@hidden@}} (@expansion{}): Indicating an Expansion
address@hidden Expansion, indicating it
address@hidden expansion
+
+When an expression is a macro call, it expands into a new expression.
+You can indicate the result of the expansion with the
address@hidden@@address@hidden@}} address@hidden
+
+The @code{@@address@hidden@}} command is displayed as @address@hidden
+in Info and as a long arrow with a flat base in the printed address@hidden
+
address@hidden 700
+For example, the following
+
address@hidden
address@hidden
+@@lisp
+(third '(a b c))
+ @@address@hidden@} (car (cdr (cdr '(a b c))))
+ @@address@hidden@} c
+@@end lisp
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+(third '(a b c))
+ @expansion{} (car (cdr (cdr '(a b c))))
+ @result{} c
address@hidden group
address@hidden lisp
+
address@hidden
+which may be read as:
+
address@hidden
address@hidden(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))};
+the result of evaluating the expression is @code{c}.
address@hidden quotation
+
address@hidden
+Often, as in this case, an example looks better if the
address@hidden@@address@hidden@}} and @code{@@address@hidden@}} commands are
indented
+five address@hidden
+
+
address@hidden Print Glyph, Error Glyph, expansion, Glyphs
address@hidden @code{@@address@hidden@}} (@print{}): Indicating Printed Output
address@hidden Printed output, indicating it
address@hidden print
+
+Sometimes an expression will print output during its execution. You
+can indicate the printed output with the @code{@@address@hidden@}}
address@hidden
+
+The @code{@@address@hidden@}} command is displayed as @address@hidden in Info
+and similarly, as a horizontal dash butting against a vertical bar, in
+the printed address@hidden
+
+In the following example, the printed text is indicated with
address@hidden@print{}}, and the value of the expression follows on the
+last address@hidden
+
address@hidden
address@hidden
+(progn (print 'foo) (print 'bar))
+ @print{} foo
+ @print{} bar
+ @result{} bar
address@hidden group
address@hidden lisp
+
address@hidden
+In a Texinfo source file, this example is written as follows:
+
address@hidden
address@hidden
+@@lisp
+(progn (print 'foo) (print 'bar))
+ @@address@hidden@} foo
+ @@address@hidden@} bar
+ @@address@hidden@} bar
+@@end lisp
address@hidden group
address@hidden lisp
+
+
address@hidden Error Glyph, Equivalence, Print Glyph, Glyphs
address@hidden @code{@@address@hidden@}} (@error{}): Indicating an Error Message
address@hidden Error message, indicating it
address@hidden error
+
+A piece of code may cause an error when you evaluate it. You can
+designate the error message with the @code{@@address@hidden@}} address@hidden
+
+The @code{@@address@hidden@}} command is displayed as @address@hidden in Info
+and as the word `error' in a box in the printed address@hidden
+
address@hidden 700
+Thus,
+
address@hidden
+@@lisp
+(+ 23 'x)
+@@address@hidden@} Wrong type argument: integer-or-marker-p, x
+@@end lisp
address@hidden example
+
address@hidden
+produces
+
address@hidden
+(+ 23 'x)
address@hidden Wrong type argument: integer-or-marker-p, x
address@hidden lisp
+
address@hidden
+This indicates that the following error message is printed
+when you evaluate the expression:
+
address@hidden
+Wrong type argument: integer-or-marker-p, x
address@hidden lisp
+
address@hidden@error{}} itself is not part of the error message.
+
+
address@hidden Equivalence, Point Glyph, Error Glyph, Glyphs
address@hidden @code{@@address@hidden@}} (@equiv{}): Indicating Equivalence
address@hidden Equivalence, indicating it
address@hidden equiv
+
+Sometimes two expressions produce identical results. You can indicate the
+exact equivalence of two forms with the @code{@@address@hidden@}}
address@hidden
+
+The @code{@@address@hidden@}} command is displayed as @address@hidden in Info
+and as a three parallel horizontal lines in the printed address@hidden
+
+Thus,
+
address@hidden
+@@lisp
+(make-sparse-keymap) @@address@hidden@} (list 'keymap)
+@@end lisp
address@hidden example
+
address@hidden
+produces
+
address@hidden
+(make-sparse-keymap) @equiv{} (list 'keymap)
address@hidden lisp
+
address@hidden
+This indicates that evaluating @code{(make-sparse-keymap)} produces
+identical results to evaluating @code{(list 'keymap)}.
+
+
address@hidden Point Glyph
address@hidden @code{@@address@hidden@}} (@point{}): Indicating Point in a
Buffer
address@hidden Point, indicating in a buffer
address@hidden point
+
+Sometimes you need to show an example of text in an Emacs buffer. In
+such examples, the convention is to include the entire contents of the
+buffer in question between two lines of dashes containing the buffer
address@hidden
+
+You can use the @samp{@@address@hidden@}} command to show the location of point
+in the text in the buffer. (The symbol for point, of course, is not
+part of the text in the buffer; it indicates the place @emph{between}
+two characters where point is located.)@refill
+
+The @code{@@address@hidden@}} command is displayed as @address@hidden in Info
+and as a small five pointed star in the printed address@hidden
+
+The following example shows the contents of buffer @file{foo} before
+and after evaluating a Lisp command to insert the word @address@hidden
+
address@hidden
address@hidden
+---------- Buffer: foo ----------
+This is the @point{}contents of foo.
+---------- Buffer: foo ----------
+
address@hidden group
address@hidden example
+
address@hidden
address@hidden
+(insert "changed ")
+ @result{} nil
+---------- Buffer: foo ----------
+This is the changed @point{}contents of foo.
+---------- Buffer: foo ----------
+
address@hidden group
address@hidden example
+
+In a Texinfo source file, the example is written like this:@refill
+
address@hidden
+@@example
+---------- Buffer: foo ----------
+This is the @@address@hidden@}contents of foo.
+---------- Buffer: foo ----------
+
+(insert "changed ")
+ @@address@hidden@} nil
+---------- Buffer: foo ----------
+This is the changed @@address@hidden@}contents of foo.
+---------- Buffer: foo ----------
+@@end example
address@hidden example
+
+
address@hidden Footnotes
address@hidden Footnotes
address@hidden Footnotes
address@hidden footnote
+
+A @dfn{footnote} is for a reference that documents or elucidates the
+primary address@hidden footnote should complement or expand upon
+the primary text, but a reader should not need to read a footnote to
+understand the primary text. For a thorough discussion of footnotes,
+see @cite{The Chicago Manual of Style}, which is published by the
+University of Chicago Press.}
+
address@hidden
+* Footnote Commands:: How to write a footnote in Texinfo.
+* Footnote Styles:: Controlling how footnotes appear in Info.
address@hidden menu
+
+
address@hidden Footnote Commands
address@hidden Footnote Commands
+
+In Texinfo, footnotes are created with the @code{@@footnote} command.
+This command is followed immediately by a left brace, then by the text
+of the footnote, and then by a terminating right brace. Footnotes may
+be of any length (they will be broken across pages if necessary), but
+are usually short. The template is:
+
address@hidden
+ordinary text@@address@hidden@var{text of address@hidden
address@hidden example
+
+As shown here, the @code{@@footnote} command should come right after the
+text being footnoted, with no intervening space; otherwise, the footnote
+marker might end up starting a line.
+
+For example, this clause is followed by a sample address@hidden
+is the sample footnote.}; in the Texinfo source, it looks like
+this:
+
address@hidden
address@hidden sample footnote@@address@hidden is the sample
address@hidden; in the Texinfo address@hidden
address@hidden example
+
+As you can see, the source includes two punctuation marks next to each
+other; in this case, @address@hidden;} is the sequence. This is normal (the
+first ends the footnote and the second belongs to the sentence being
+footnoted), so don't worry that it looks odd.
+
+In a printed manual or book, the reference mark for a footnote is a
+small, superscripted number; the text of the footnote appears at the
+bottom of the page, below a horizontal line.
+
+In Info, the reference mark for a footnote is a pair of parentheses
+with the footnote number between them, like this: @samp{(1)}. The
+reference mark is followed by a cross-reference link to the footnote's
+text.
+
+In the HTML output, footnote references are marked with a small,
+superscripted number which is rendered as a hypertext link to the
+footnote text.
+
+By the way, footnotes in the argument of an @code{@@item} command for a
address@hidden@@table} must be on the same line as the @code{@@item}
+(as usual). @xref{Two-column Tables}.
+
+
address@hidden Footnote Styles
address@hidden Footnote Styles
+
+Info has two footnote styles, which determine where the text of the
+footnote is located:@refill
+
address@hidden @bullet
address@hidden @address@hidden node footnote style
address@hidden
+In the `End' node style, all the footnotes for a single node
+are placed at the end of that node. The footnotes are separated from
+the rest of the node by a line of dashes with the word
address@hidden within it. Each footnote begins with an
address@hidden(@var{n})} reference address@hidden
+
address@hidden 700
address@hidden
+Here is an example of a single footnote in the end of node style:@refill
+
address@hidden
address@hidden
+ --------- Footnotes ---------
+
+(1) Here is a sample footnote.
address@hidden group
address@hidden example
+
address@hidden @address@hidden footnote style
address@hidden
+In the `Separate' node style, all the footnotes for a single
+node are placed in an automatically constructed node of
+their own. In this style, a ``footnote reference'' follows
+each @samp{(@var{n})} reference mark in the body of the
+node. The footnote reference is actually a cross reference
+which you use to reach the footnote address@hidden
+
+The name of the node with the footnotes is constructed
+by appending @address@hidden to the name of the node
+that contains the footnotes. (Consequently, the footnotes'
+node for the @file{Footnotes} node is
address@hidden@file{Footnotes-Footnotes}}!) The footnotes' node has an
+`Up' node pointer that leads back to its parent address@hidden
+
address@hidden
+Here is how the first footnote in this manual looks after being
+formatted for Info in the separate node style:@refill
+
address@hidden
address@hidden
+File: texinfo.info Node: Overview-Footnotes, Up: Overview
+
+(1) The first syllable of "Texinfo" is pronounced like "speck", not
+"hex". @dots{}
address@hidden group
address@hidden smallexample
address@hidden itemize
+
+A Texinfo file may be formatted into an Info file with either footnote
address@hidden
+
address@hidden footnotestyle
+Use the @code{@@footnotestyle} command to specify an Info file's
+footnote style. Write this command at the beginning of a line followed
+by an argument, either @samp{end} for the end node style or
address@hidden for the separate node style.
+
address@hidden 700
+For example,
+
address@hidden
+@@footnotestyle end
address@hidden example
address@hidden
+or
address@hidden
+@@footnotestyle separate
address@hidden example
+
+Write an @code{@@footnotestyle} command before or shortly after the
+end-of-header line at the beginning of a Texinfo file. (If you
+include the @code{@@footnotestyle} command between the start-of-header
+and end-of-header lines, the region formatting commands will format
+footnotes as specified.)@refill
+
+If you do not specify a footnote style, the formatting commands use
+their default style. Currently, @code{texinfo-format-buffer} and
address@hidden use the `separate' style and
address@hidden uses the `end' address@hidden
+
address@hidden !!! note: makeinfo's --footnote-style option overrides
footnotestyle
+This chapter contains two address@hidden
+
+
address@hidden this should be described with figures when we have them
address@hidden perhaps in the quotation/example chapter.
address@hidden Images
address@hidden Inserting Images
+
address@hidden Images, inserting
address@hidden Pictures, inserting
address@hidden image
+
+You can insert an image given in an external file with the
address@hidden@@image} command:
+
address@hidden
+@@address@hidden@var{filename}, @address@hidden@r{]}, @address@hidden@r{]},
@address@hidden@r{]}, @address@hidden@address@hidden
address@hidden example
+
address@hidden Formats for images
address@hidden Image formats
+The @var{filename} argument is mandatory, and must not have an
+extension, because the different processors support different formats:
address@hidden @bullet
address@hidden
address@hidden reads the file @address@hidden (Encapsulated PostScript
+format).
address@hidden
address@hidden address@hidden, and images}
address@hidden reads @address@hidden (Adobe's Portable Document Format).
address@hidden
address@hidden uses @address@hidden verbatim for
+Info output (more or less as if it was an @code{@@example}).
address@hidden
address@hidden
+uses the optional fifth argument to @code{@@image} for the extension if
+you supply it. For example:
+
address@hidden XPM image format
address@hidden
+@@address@hidden,,,,address@hidden
address@hidden example
+
address@hidden
+will cause @samp{makeinfo --html} to try @file{foo.xpm}.
+
address@hidden GIF, unsupported due to patents
address@hidden PNG image format
address@hidden JPG image format
+If you do not supply the optional fifth argument, @samp{makeinfo
+---html} first tries @address@hidden; if that does not exist,
+it tries @address@hidden If that does not exist either, it
+complains. (We cannot support GIF format directly due to software
+patents.)
address@hidden itemize
+
address@hidden Width of images
address@hidden Height of images
address@hidden Aspect ratio of images
address@hidden Distorting images
+The optional @var{width} and @var{height} arguments specify the size to
+scale the image to (they are ignored for Info output). If neither is
+specified, the image is presented in its natural size (given in the
+file); if only one is specified, the other is scaled proportionately;
+and if both are specified, both are respected, thus possibly distorting
+the original image by changing its aspect ratio.
+
address@hidden Dimensions and image sizes
+The @var{width} and @var{height} may be specified using any valid @TeX{}
+dimension, namely:
+
address@hidden @asis
address@hidden pt
address@hidden Points (dimension)
+point (72.27pt = 1in)
address@hidden pc
address@hidden Picas
+pica (1pc = 12pt)
address@hidden bp
address@hidden Big points
+big point (72bp = 1in)
address@hidden in
address@hidden Inches
+inch
address@hidden cm
address@hidden Centimeters
+centimeter (2.54cm = 1in)
address@hidden mm
address@hidden Millimeters
+millimeter (10mm = 1cm)
address@hidden dd
address@hidden address@hidden points
address@hidden point (1157dd = 1238pt)
address@hidden cc
address@hidden Ciceros
+cicero (1cc = 12dd)
address@hidden sp
address@hidden Scaled points
+scaled point (65536sp = 1pt)
address@hidden table
+
address@hidden ridt.eps
+For example, the following will scale a file @file{ridt.eps} to one
+inch vertically, with the width scaled proportionately:
+
address@hidden
+@@address@hidden,,address@hidden
address@hidden example
+
address@hidden epsf.tex
+For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be
+installed somewhere that @TeX{} can find it. (The standard location is
address@hidden@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a
+root of your @TeX{} directory tree.) This file is included in the
+Texinfo distribution and is also available from
address@hidden://tug.org/tex/epsf.tex}, among other places.
+
address@hidden@@image} can be used within a line as well as for displayed
+figures. Therefore, if you intend it to be displayed, be sure to leave
+a blank line before the command, or the output will run into the
+preceding text.
+
address@hidden alt attribute for images
address@hidden alternate text for images
+When producing html, @code{makeinfo} sets the @dfn{alt attribute} for
+inline images to the optional fourth argument to @code{@@image}, if
+supplied. If not supplied, @code{makeinfo} uses the full file name of
+the image being displayed.
+
+
address@hidden Breaks
address@hidden Making and Preventing Breaks
address@hidden Making line and page breaks
address@hidden Preventing line and page breaks
+
address@hidden Line breaks
+Usually, a Texinfo file is processed both by @TeX{} and by one of the
+Info formatting commands. Line, paragraph, or page breaks sometimes
+occur in the `wrong' place in one or other form of output. You must
+ensure that text looks right both in the printed manual and in the
+Info file.
+
address@hidden White space, excessive
address@hidden Page breaks
+For example, in a printed manual, page breaks may occur awkwardly in
+the middle of an example; to prevent this, you can hold text together
+using a grouping command that keeps the text from being split across
+two pages. Conversely, you may want to force a page break where none
+would occur normally. Fortunately, problems like these do not often
+arise. When they do, use the break, break prevention, or pagination
+commands.
+
address@hidden
+* Break Commands:: Cause and prevent splits.
+* Line Breaks:: How to force a single line to use two lines.
+* - and hyphenation:: How to tell @TeX{} about hyphenation points.
+* w:: How to prevent unwanted line breaks.
+* sp:: How to insert blank lines.
+* page:: How to force the start of a new page.
+* group:: How to prevent unwanted page breaks.
+* need:: Another way to prevent unwanted page breaks.
address@hidden menu
+
+
address@hidden Break Commands, Line Breaks, Breaks, Breaks
address@hidden Break Commands
+
+The break commands create or allow line and paragraph breaks:@refill
+
address@hidden @code
address@hidden @@*
+Force a line break.
+
address@hidden @@sp @var{n}
+Skip @var{n} blank address@hidden
+
address@hidden @@-
+Insert a discretionary hyphen.
+
address@hidden @@address@hidden@var{hy-phen-a-ted address@hidden
+Define hyphen points in @var{hy-phen-a-ted words}.
address@hidden table
+
+The line-break-prevention command holds text together all on one
+line:@refill
+
address@hidden @code
address@hidden @@address@hidden@address@hidden
+Prevent @var{text} from being split and hyphenated across two address@hidden
address@hidden table
+
+The pagination commands apply only to printed output, since Info
+files do not have address@hidden
+
address@hidden @code
address@hidden @@page
+Start a new page in the printed address@hidden
+
address@hidden @@group
+Hold text together that must appear on one printed address@hidden
+
address@hidden @@need @var{mils}
+Start a new printed page if not enough space on this address@hidden
address@hidden table
+
address@hidden Line Breaks
address@hidden @code{@@*}: Generate Line Breaks
address@hidden * @r{(force line break)}
address@hidden Line breaks
address@hidden Breaks in a line
+
+The @code{@@*} command forces a line break in both the printed manual and
+in address@hidden
+
address@hidden 700
+For example,
+
address@hidden
+This line @@* is broken @@*in two places.
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden
+This line
+ is broken
+in two places.
address@hidden group
address@hidden example
+
address@hidden
+(Note that the space after the first @code{@@*} command is faithfully
+carried down to the next line.)@refill
+
address@hidden 800
+The @code{@@*} command is often used in a file's copyright page:@refill
+
address@hidden
address@hidden
+This is edition 2.0 of the Texinfo documentation,@@*
+and is for @dots{}
address@hidden group
address@hidden example
+
address@hidden
+In this case, the @code{@@*} command keeps @TeX{} from stretching the
+line across the whole page in an ugly address@hidden
+
address@hidden
address@hidden note:} Do not write braces after an @code{@@*} command;
+they are not address@hidden
+
+Do not write an @code{@@refill} command at the end of a paragraph
+containing an @code{@@*} command; it will cause the paragraph to be
+refilled after the line break occurs, negating the effect of the line
address@hidden
address@hidden quotation
+
+
address@hidden - and hyphenation
address@hidden @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate
+
address@hidden - @r{(discretionary hyphen)}
address@hidden hyphenation
address@hidden Hyphenation, helping @TeX{} do
address@hidden Fine-tuning, and hyphenation
+
+Although @TeX{}'s hyphenation algorithm is generally pretty good, it
+does miss useful hyphenation points from time to time. (Or, far more
+rarely, insert an incorrect hyphenation.) So, for documents with an
+unusual vocabulary or when fine-tuning for a printed edition, you may
+wish to help @TeX{} out. Texinfo supports two commands for this:
+
address@hidden @code
address@hidden @@-
+Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does
+not have to) hyphenate. This is especially useful when you notice an
+overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull
+hboxes}). @TeX{} will not insert any hyphenation points itself into a
+word containing @code{@@-}.
+
address@hidden @@address@hidden@var{hy-phen-a-ted address@hidden
+Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you
+put a @samp{-} at each hyphenation point. For example:
address@hidden
+@@address@hidden address@hidden
address@hidden example
address@hidden @TeX{} only uses the specified hyphenation points when the
+words match exactly, so give all necessary variants.
address@hidden table
+
+Info output is not hyphenated, so these commands have no effect there.
+
address@hidden w
address@hidden @code{@@address@hidden@address@hidden: Prevent Line Breaks
address@hidden w @r{(prevent line break)}
address@hidden Line breaks, preventing
address@hidden Hyphenation, preventing
+
address@hidden@@address@hidden@address@hidden outputs @var{text} and prohibits
line breaks
+within @address@hidden
+
+You can use the @code{@@w} command to prevent @TeX{} from automatically
+hyphenating a long name or phrase that happens to fall near the end of a
+line. For example:
+
address@hidden
+You can copy GNU software from @@address@hidden@@address@hidden@address@hidden
address@hidden example
+
address@hidden
+produces
+
address@hidden
+You can copy GNU software from @address@hidden
address@hidden quotation
+
address@hidden Non-breakable space
address@hidden Unbreakable space
address@hidden Tied space
+You can also use @code{@@w} to produce a non-breakable space:
+
address@hidden
+None of the formatters will break at this@@address@hidden @}space.
address@hidden example
+
+
address@hidden sp
address@hidden @code{@@sp} @var{n}: Insert Blank Lines
address@hidden sp @r{(line spacing)}
address@hidden Space, inserting vertical
address@hidden Blank lines
address@hidden Line spacing
+
+A line beginning with and containing only @code{@@sp @var{n}}
+generates @var{n} blank lines of space in both the printed manual and
+the Info file. @code{@@sp} also forces a paragraph break. For
+example,
+
address@hidden
+@@sp 2
address@hidden example
+
address@hidden
+generates two blank lines.
+
+The @code{@@sp} command is most often used in the title address@hidden
+
+
+
address@hidden page
address@hidden @code{@@page}: Start a New Page
address@hidden Page breaks
address@hidden page
+
+A line containing only @code{@@page} starts a new page in a printed
+manual. The command has no effect on Info files since they are not
+paginated. An @code{@@page} command is often used in the @code{@@titlepage}
+section of a Texinfo file to start the copyright page.
+
+
address@hidden group, need, page, Breaks
address@hidden node-name, next, previous, up
address@hidden @code{@@group}: Prevent Page Breaks
address@hidden Group (hold text together vertically)
address@hidden Holding text together vertically
address@hidden Vertically holding text together
address@hidden group
+
+The @code{@@group} command (on a line by itself) is used inside an
address@hidden@@example} or similar construct to begin an unsplittable vertical
+group, which will appear entirely on one page in the printed output.
+The group is terminated by a line containing only @code{@@end group}.
+These two lines produce no output of their own, and in the Info file
+output they have no effect at address@hidden
+
address@hidden Once said that these environments
address@hidden turn off vertical spacing between ``paragraphs''.
address@hidden Also, quotation used to work, but doesn't in texinfo-2.72
+Although @code{@@group} would make sense conceptually in a wide
+variety of contexts, its current implementation works reliably only
+within @code{@@example} and variants, and within @code{@@display},
address@hidden@@format}, @code{@@flushleft} and @code{@@flushright}.
address@hidden and Examples}. (What all these commands have in
+common is that each line of input produces a line of output.) In
+other contexts, @code{@@group} can cause anomalous vertical
address@hidden
+
address@hidden 750
+This formatting requirement means that you should write:
+
address@hidden
address@hidden
+@@example
+@@group
address@hidden
+@@end group
+@@end example
address@hidden group
address@hidden example
+
address@hidden
+with the @code{@@group} and @code{@@end group} commands inside the
address@hidden@@example} and @code{@@end example} commands.
+
+The @code{@@group} command is most often used to hold an example
+together on one page. In this Texinfo manual, more than 100 examples
+contain text that is enclosed between @code{@@group} and @code{@@end
+group}.
+
+If you forget to end a group, you may get strange and unfathomable
+error messages when you run @TeX{}. This is because @TeX{} keeps
+trying to put the rest of the Texinfo file onto the one page and does
+not start to generate error messages until it has processed
+considerable text. It is a good rule of thumb to look for a missing
address@hidden@@end group} if you get incomprehensible error messages in
address@hidden@refill
+
address@hidden need, , group, Breaks
address@hidden node-name, next, previous, up
address@hidden @code{@@need @var{mils}}: Prevent Page Breaks
address@hidden Need space at page bottom
address@hidden need
+
+A line containing only @code{@@need @var{n}} starts
+a new page in a printed manual if fewer than @var{n} mils (thousandths
+of an inch) remain on the current page. Do not use
+braces around the argument @var{n}. The @code{@@need} command has no
+effect on Info files since they are not address@hidden
+
address@hidden 800
+This paragraph is preceded by an @code{@@need} command that tells
address@hidden to start a new page if fewer than 800 mils (eight-tenths
+inch) remain on the page. It looks like this:@refill
+
address@hidden
address@hidden
+@@need 800
+This paragraph is preceded by @dots{}
address@hidden group
address@hidden example
+
+The @code{@@need} command is useful for preventing orphans (single
+lines at the bottoms of printed pages)address@hidden
+
+
address@hidden Definition Commands
address@hidden Definition Commands
address@hidden Definition commands
+
+The @code{@@deffn} command and the other @dfn{definition commands}
+enable you to describe functions, variables, macros, commands, user
+options, special forms and other such artifacts in a uniform
address@hidden
+
+In the Info file, a definition causes the entity
+category---`Function', `Variable', or whatever---to appear at the
+beginning of the first line of the definition, followed by the
+entity's name and arguments. In the printed manual, the command
+causes @TeX{} to print the entity's name and its arguments on the left
+margin and print the category next to the right margin. In both
+output formats, the body of the definition is indented. Also, the
+name of the entity is entered into the appropriate index:
address@hidden@@deffn} enters the name into the index of functions,
address@hidden@@defvr} enters it into the index of variables, and so
address@hidden
+
+A manual need not and should not contain more than one definition for
+a given name. An appendix containing a summary should use
address@hidden@@table} rather than the definition address@hidden
+
address@hidden
+* Def Cmd Template:: How to structure a description using a
+ definition command.
+* Optional Arguments:: How to handle optional and repeated arguments.
+* deffnx:: How to group two or more `first' lines.
+* Def Cmds in Detail:: All the definition commands.
+* Def Cmd Conventions:: Conventions for writing definitions.
+* Sample Function Definition::
address@hidden menu
+
address@hidden Def Cmd Template, Optional Arguments, Definition Commands,
Definition Commands
address@hidden The Template for a Definition
address@hidden Definition template
address@hidden Template for a definition
+
+The @code{@@deffn} command is used for definitions of entities that
+resemble functions. To write a definition using the @code{@@deffn}
+command, write the @code{@@deffn} command at the beginning of a line
+and follow it on the same line by the category of the entity, the name
+of the entity itself, and its arguments (if any). Then write the body
+of the definition on succeeding lines. (You may embed examples in the
+body.) Finally, end the definition with an @code{@@end deffn} command
+written on a line of its own. (The other definition commands follow
+the same format.)@refill
+
+The template for a definition looks like this:
+
address@hidden
address@hidden
+@@deffn @var{category} @var{name} @address@hidden
address@hidden
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden 700
address@hidden
+For example,
+
address@hidden
address@hidden
+@@deffn Command forward-word count
+This command moves point forward @@address@hidden@} words
+(or backward if @@address@hidden@} is negative). @dots{}
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden Command forward-word count
+This function moves point forward @var{count} words
+(or backward if @var{count} is negative). @dots{}
address@hidden deffn
address@hidden quotation
+
+Capitalize the category name like a title. If the name of the
+category contains spaces, as in the phrase `Interactive Command',
+write braces around it. For example:@refill
+
address@hidden
address@hidden
+@@deffn @{Interactive address@hidden isearch-forward
address@hidden
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden
+Otherwise, the second word will be mistaken for the name of the
address@hidden
+
+Some of the definition commands are more general than others. The
address@hidden@@deffn} command, for example, is the general definition command
+for functions and the like---for entities that may take arguments. When
+you use this command, you specify the category to which the entity
+belongs. The @code{@@deffn} command possesses three predefined,
+specialized variations, @code{@@defun}, @code{@@defmac}, and
address@hidden@@defspec}, that specify the category for you: ``Function'',
+``Macro'', and ``Special Form'' respectively. (In Lisp, a special form
+is an entity much like a function.) The @code{@@defvr} command also is
+accompanied by several predefined, specialized variations for describing
+particular kinds of address@hidden
+
+The template for a specialized definition, such as @code{@@defun}, is
+similar to the template for a generalized definition, except that you
+do not need to specify the category:@refill
+
address@hidden
address@hidden
+@@defun @var{name} @address@hidden
address@hidden
+@@end defun
address@hidden group
address@hidden example
+
address@hidden
+Thus,
+
address@hidden
address@hidden
+@@defun buffer-end flag
+This function returns @@address@hidden(point-min)@} if @@address@hidden@}
+is less than 1, @@address@hidden(point-max)@} otherwise.
address@hidden
+@@end defun
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden
address@hidden buffer-end flag
+This function returns @code{(point-min)} if @var{flag} is less than 1,
address@hidden(point-max)} otherwise. @dots{}
address@hidden defun
address@hidden quotation
+
address@hidden
address@hidden Function Definition, Sample Function Definition, A Sample
+Function Definition}, for a more detailed example of a function
+definition, including the use of @code{@@example} inside the
address@hidden
+
+The other specialized commands work like @code{@@address@hidden
+
address@hidden Macros in definition commands
+Note that, due to implementation difficulties, macros are not expanded
+in @code{@@deffn} and all the other definition commands.
+
address@hidden Optional Arguments, deffnx, Def Cmd Template, Definition Commands
address@hidden Optional and Repeated Arguments
address@hidden Optional and repeated arguments
address@hidden Repeated and optional arguments
address@hidden Arguments, repeated and optional
address@hidden Syntax, optional & repeated arguments
address@hidden Meta-syntactic chars for arguments
+
+Some entities take optional or repeated arguments, which may be
+specified by a distinctive glyph that uses square brackets and
+ellipses. For @w{example}, a special form often breaks its argument list
+into separate arguments in more complicated ways than a
+straightforward address@hidden
+
address@hidden The following looks better in Info (no `r', `samp' and `code'):
+An argument enclosed within square brackets is optional.
+Thus, address@hidden means that @var{optional-arg} is optional.
+An argument followed by an ellipsis is optional
+and may be repeated more than once.
address@hidden This is consistent with Emacs Lisp Reference manual
+Thus, @address@hidden stands for zero or more arguments.
+Parentheses are used when several arguments are grouped
+into additional levels of list structure in Lisp.
+
+Here is the @code{@@defspec} line of an example of an imaginary
+special form:@refill
+
address@hidden
address@hidden foobar (@var{var} address@hidden @var{to} address@hidden)
@address@hidden
address@hidden defspec
address@hidden
+\vskip \parskip
address@hidden tex
address@hidden quotation
+
address@hidden
+In this example, the arguments @var{from} and @var{to} are optional,
+but must both be present or both absent. If they are present,
address@hidden may optionally be specified as well. These arguments are
+grouped with the argument @var{var} into a list, to distinguish them
+from @var{body}, which includes all remaining elements of the
address@hidden
+
+In a Texinfo source file, this @code{@@defspec} line is written like
+this (except it would not be split over two lines, as it is in this
+example)address@hidden
+
address@hidden
address@hidden
+@@defspec foobar (@@address@hidden@} [@@address@hidden@} @@address@hidden@}
+ [@@address@hidden@}]]) @@address@hidden@}@@address@hidden@}
address@hidden group
address@hidden example
+
address@hidden
+The function is listed in the Command and Variable Index under
address@hidden@refill
+
address@hidden deffnx, Def Cmds in Detail, Optional Arguments, Definition
Commands
address@hidden Two or More `First' Lines
address@hidden Two `First' Lines for @code{@@deffn}
address@hidden Grouping two definitions together
address@hidden Definitions grouped together
address@hidden deffnx
+
+To create two or more `first' or header lines for a definition, follow
+the first @code{@@deffn} line by a line beginning with @code{@@deffnx}.
+The @code{@@deffnx} command works exactly like @code{@@deffn}
+except that it does not generate extra vertical white space between it
+and the preceding address@hidden
+
address@hidden 1000
+For example,
+
address@hidden
address@hidden
+@@deffn @{Interactive address@hidden isearch-forward
+@@deffnx @{Interactive address@hidden isearch-backward
+These two search commands are similar except @dots{}
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden
+produces
+
address@hidden {Interactive Command} isearch-forward
address@hidden {Interactive Command} isearch-backward
+These two search commands are similar except @dots{}
address@hidden deffn
+
+Each definition command has an `x' form: @code{@@defunx},
address@hidden@@defvrx}, @code{@@deftypefunx}, etc.
+
+The `x' forms work just like @code{@@itemx}; see @ref{itemx, , @code{@@itemx}}.
+
address@hidden Def Cmds in Detail, Def Cmd Conventions, deffnx, Definition
Commands
address@hidden The Definition Commands
+
+Texinfo provides more than a dozen definition commands, all of which
+are described in this address@hidden
+
+The definition commands automatically enter the name of the entity in
+the appropriate index: for example, @code{@@deffn}, @code{@@defun},
+and @code{@@defmac} enter function names in the index of functions;
address@hidden@@defvr} and @code{@@defvar} enter variable names in the index
+of address@hidden
+
+Although the examples that follow mostly illustrate Lisp, the commands
+can be used for other programming address@hidden
+
address@hidden
+* 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.
+* Abstract Objects:: Commands for object-oriented programming.
+* Data Types:: The definition command for data types.
address@hidden menu
+
address@hidden Functions Commands, Variables Commands, Def Cmds in Detail, Def
Cmds in Detail
address@hidden Functions and Similar Entities
+
+This section describes the commands for describing functions and similar
+entities:@refill
+
address@hidden @code
address@hidden deffn
address@hidden @@deffn @var{category} @var{name} @address@hidden
+The @code{@@deffn} command is the general definition command for
+functions, interactive commands, and similar entities that may take
+arguments. You must choose a term to describe the category of entity
+being defined; for example, ``Function'' could be used if the entity is
+a function. The @code{@@deffn} command is written at the beginning of a
+line and is followed on the same line by the category of entity being
+described, the name of this particular entity, and its arguments, if
+any. Terminate the definition with @code{@@end deffn} on a line of its
address@hidden
+
address@hidden 750
+For example, here is a definition:
+
address@hidden
address@hidden
+@@deffn Command forward-char nchars
+Move point forward @@address@hidden@} characters.
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden
+This shows a rather terse definition for a ``command'' named
address@hidden with one argument, @var{nchars}.
+
address@hidden@@deffn} prints argument names such as @var{nchars} in italics or
+upper case, as if @code{@@var} had been used, because we think of these
+names as metasyntactic variables---they stand for the actual argument
+values. Within the text of the description, write an argument name
+explicitly with @code{@@var} to refer to the value of the argument. In
+the example above, we used @samp{@@address@hidden@}} in this way.
+
+The template for @code{@@deffn} is:
+
address@hidden
address@hidden
+@@deffn @var{category} @var{name} @address@hidden
address@hidden
+@@end deffn
address@hidden group
address@hidden example
+
address@hidden defun
address@hidden @@defun @var{name} @address@hidden
+The @code{@@defun} command is the definition command for functions.
address@hidden@@defun} is equivalent to @samp{@@deffn Function
address@hidden@refill
+
address@hidden 800
address@hidden
+For example,
+
address@hidden
address@hidden
+@@defun set symbol new-value
+Change the value of the symbol @@address@hidden@}
+to @@address@hidden@}.
+@@end defun
address@hidden group
address@hidden example
+
address@hidden
+shows a rather terse definition for a function @code{set} whose
+arguments are @var{symbol} and @var{new-value}. The argument names on
+the @code{@@defun} line automatically appear in italics or upper case as
+if they were enclosed in @code{@@var}. Terminate the definition with
address@hidden@@end defun} on a line of its address@hidden
+
+The template is:
+
address@hidden
address@hidden
+@@defun @var{function-name} @address@hidden
address@hidden
+@@end defun
address@hidden group
address@hidden example
+
address@hidden@@defun} creates an entry in the index of functions.
+
address@hidden defmac
address@hidden @@defmac @var{name} @address@hidden
+The @code{@@defmac} command is the definition command for macros.
address@hidden@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and
+works like @code{@@address@hidden
+
address@hidden defspec
address@hidden @@defspec @var{name} @address@hidden
+The @code{@@defspec} command is the definition command for special
+forms. (In Lisp, a special form is an entity much like a function,
address@hidden Forms,,, elisp, GNU Emacs Lisp Reference Manual}.)
address@hidden@@defspec} is equivalent to @samp{@@deffn @{Special address@hidden
address@hidden and works like @code{@@address@hidden
address@hidden table
+
address@hidden Variables Commands, Typed Functions, Functions Commands, Def
Cmds in Detail
address@hidden Variables and Similar Entities
+
+Here are the commands for defining variables and similar
+entities:@refill
+
address@hidden @code
address@hidden defvr
address@hidden @@defvr @var{category} @var{name}
+The @code{@@defvr} command is a general definition command for
+something like a variable---an entity that records a value. You must
+choose a term to describe the category of entity being defined; for
+example, ``Variable'' could be used if the entity is a variable.
+Write the @code{@@defvr} command at the beginning of a line and
+follow it on the same line by the category of the entity and the
+name of the entity.
+
+Capitalize the category name like a title. If the name of the category
+contains spaces, as in the name ``User Option'', enclose it in braces.
+Otherwise, the second word will be mistaken for the name of the entity.
+For example,
+
address@hidden
address@hidden
+@@defvr @{User address@hidden fill-column
+This buffer-local variable specifies
+the maximum width of filled lines.
address@hidden
+@@end defvr
address@hidden group
address@hidden example
+
+Terminate the definition with @code{@@end defvr} on a line of its
address@hidden
+
+The template is:
+
address@hidden
address@hidden
+@@defvr @var{category} @var{name}
address@hidden
+@@end defvr
address@hidden group
address@hidden example
+
address@hidden@@defvr} creates an entry in the index of variables for
@var{name}.
+
address@hidden defvar
address@hidden @@defvar @var{name}
+The @code{@@defvar} command is the definition command for variables.
address@hidden@@defvar} is equivalent to @samp{@@defvr Variable
address@hidden@refill
+
address@hidden 750
+For example:
+
address@hidden
address@hidden
+@@defvar kill-ring
address@hidden
+@@end defvar
address@hidden group
address@hidden example
+
+The template is:
+
address@hidden
address@hidden
+@@defvar @var{name}
address@hidden
+@@end defvar
address@hidden group
address@hidden example
+
address@hidden@@defvar} creates an entry in the index of variables for
address@hidden@refill
+
address@hidden defopt
address@hidden @@defopt @var{name}
address@hidden User options, marking
+The @code{@@defopt} command is the definition command for @dfn{user
+options}, i.e., variables intended for users to change according to
+taste; Emacs has many such (@pxref{Variables,,, emacs, The GNU Emacs
+Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User
address@hidden @dots{}} and works like @code{@@address@hidden
address@hidden table
+
+
address@hidden Typed Functions, Typed Variables, Variables Commands, Def Cmds
in Detail
address@hidden Functions in Typed Languages
+
+The @code{@@deftypefn} command and its variations are for describing
+functions in languages in which you must declare types of variables and
+functions, such as C and C++.
+
address@hidden @code
address@hidden deftypefn
address@hidden @@deftypefn @var{category} @var{data-type} @var{name}
@address@hidden
+The @code{@@deftypefn} command is the general definition command for
+functions and similar entities that may take arguments and that are
+typed. The @code{@@deftypefn} command is written at the beginning of
+a line and is followed on the same line by the category of entity
+being described, the type of the returned value, the name of this
+particular entity, and its arguments, if address@hidden
+
address@hidden 800
address@hidden
+For example,
+
address@hidden
address@hidden
+@@deftypefn @{Library address@hidden int foobar
+ (int @@address@hidden@}, float @@address@hidden@})
address@hidden
+@@end deftypefn
address@hidden group
address@hidden example
+
address@hidden 1000
address@hidden
+(where the text before the address@hidden'', shown above as two lines, would
+actually be a single line in a real Texinfo file) produces the following
+in Info:
+
address@hidden
address@hidden
+-- Library Function: int foobar (int FOO, float BAR)
address@hidden
address@hidden group
address@hidden smallexample
+
+This means that @code{foobar} is a ``library function'' that returns an
address@hidden, and its arguments are @var{foo} (an @code{int}) and
address@hidden (a @code{float})address@hidden
+
+The argument names that you write in @code{@@deftypefn} are not subject
+to an implicit @code{@@var}---since the actual names of the arguments in
address@hidden@@deftypefn} are typically scattered among data type names and
+keywords, Texinfo cannot find them without help. Instead, you must write
address@hidden@@var} explicitly around the argument names. In the example
+above, the argument names are @samp{foo} and @address@hidden
+
+The template for @code{@@deftypefn} is:@refill
+
address@hidden
address@hidden
+@@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{}
address@hidden
+@@end deftypefn
address@hidden group
address@hidden example
+
address@hidden
+Note that if the @var{category} or @var{data type} is more than one
+word then it must be enclosed in braces to make it a single address@hidden
+
+If you are describing a procedure in a language that has packages,
+such as Ada, you might consider using @code{@@deftypefn} in a manner
+somewhat contrary to the convention described in the preceding
address@hidden
+
address@hidden 800
address@hidden
+For example:
+
address@hidden
address@hidden
+@@deftypefn stacks private push
+ (@@address@hidden@}:in out stack;
+ @@address@hidden@}:in integer)
address@hidden
+@@end deftypefn
address@hidden group
address@hidden example
+
address@hidden
+(The @code{@@deftypefn} arguments are shown split into three lines, but
+would be a single line in a real Texinfo file.)
+
+In this instance, the procedure is classified as belonging to the
+package @code{stacks} rather than classified as a `procedure' and its
+data type is described as @code{private}. (The name of the procedure
+is @code{push}, and its arguments are @var{s} and @var{n}.)@refill
+
address@hidden@@deftypefn} creates an entry in the index of functions for
address@hidden@refill
+
address@hidden @@deftypefun @var{data-type} @var{name} @address@hidden
address@hidden deftypefun
+The @code{@@deftypefun} command is the specialized definition command
+for functions in typed languages. The command is equivalent to
address@hidden@@deftypefn Function @address@hidden
+
address@hidden 800
address@hidden
+Thus,
+
address@hidden
address@hidden
+@@deftypefun int foobar (int @@address@hidden@}, float @@address@hidden@})
address@hidden
+@@end deftypefun
address@hidden group
address@hidden smallexample
+
address@hidden
+produces the following in Info:
+
address@hidden
address@hidden
+-- Function: int foobar (int FOO, float BAR)
address@hidden
address@hidden group
address@hidden example
+
address@hidden 800
+The template is:
+
address@hidden
address@hidden
+@@deftypefun @var{type} @var{name} @address@hidden
address@hidden
+@@end deftypefun
address@hidden group
address@hidden example
+
address@hidden@@deftypefun} creates an entry in the index of functions for
address@hidden@refill
+
address@hidden table
+
+
address@hidden Typed Variables, Abstract Objects, Typed Functions, Def Cmds in
Detail
address@hidden Variables in Typed Languages
+
+Variables in typed languages are handled in a manner similar to
+functions in typed languages. @xref{Typed Functions}. The general
+definition command @code{@@deftypevr} corresponds to
address@hidden@@deftypefn} and the specialized definition command
address@hidden@@deftypevar} corresponds to @code{@@address@hidden
+
address@hidden @code
address@hidden deftypevr
address@hidden @@deftypevr @var{category} @var{data-type} @var{name}
+The @code{@@deftypevr} command is the general definition command for
+something like a variable in a typed language---an entity that records
+a value. You must choose a term to describe the category of the
+entity being defined; for example, ``Variable'' could be used if the
+entity is a address@hidden
+
+The @code{@@deftypevr} command is written at the beginning of a line
+and is followed on the same line by the category of the entity
+being described, the data type, and the name of this particular
address@hidden
+
address@hidden 800
address@hidden
+For example:
+
address@hidden
address@hidden
+@@deftypevr @{Global address@hidden int enable
address@hidden
+@@end deftypevr
address@hidden group
address@hidden example
+
address@hidden
+produces the following in Info:
+
address@hidden
address@hidden
+-- Global Flag: int enable
address@hidden
address@hidden group
address@hidden example
+
address@hidden 800
+The template is:
+
address@hidden
+@@deftypevr @var{category} @var{data-type} @var{name}
address@hidden
+@@end deftypevr
address@hidden example
+
address@hidden@@deftypevr} creates an entry in the index of variables for
address@hidden@refill
+
address@hidden deftypevar
address@hidden @@deftypevar @var{data-type} @var{name}
+The @code{@@deftypevar} command is the specialized definition command
+for variables in typed languages. @code{@@deftypevar} is equivalent
+to @samp{@@deftypevr Variable @address@hidden
+
address@hidden 800
address@hidden
+For example:
+
address@hidden
address@hidden
+@@deftypevar int fubar
address@hidden
+@@end deftypevar
address@hidden group
address@hidden example
+
address@hidden
+produces the following in Info:
+
address@hidden
address@hidden
+-- Variable: int fubar
address@hidden
address@hidden group
address@hidden example
+
address@hidden 800
address@hidden
+The template is:
+
address@hidden
address@hidden
+@@deftypevar @var{data-type} @var{name}
address@hidden
+@@end deftypevar
address@hidden group
address@hidden example
+
address@hidden@@deftypevar} creates an entry in the index of variables for
address@hidden@refill
address@hidden table
+
address@hidden Abstract Objects
address@hidden Object-Oriented Programming
+
+Here are the commands for formatting descriptions about abstract
+objects, such as are used in object-oriented programming. A class is
+a defined type of abstract object. An instance of a class is a
+particular object that has the type of the class. An instance
+variable is a variable that belongs to the class but for which each
+instance has its own address@hidden
+
+In a definition, if the name of a class is truly a name defined in the
+programming system for a class, then you should write an @code{@@code}
+around it. Otherwise, it is printed in the usual text address@hidden
+
address@hidden @code
address@hidden defcv
address@hidden @@defcv @var{category} @var{class} @var{name}
+The @code{@@defcv} command is the general definition command for
+variables associated with classes in object-oriented programming. The
address@hidden@@defcv} command is followed by three arguments: the category of
+thing being defined, the class to which it belongs, and its
+name. Thus,@refill
+
address@hidden
address@hidden
+@@defcv @{Class address@hidden Window border-pattern
address@hidden
+@@end defcv
address@hidden group
address@hidden example
+
address@hidden
+illustrates how you would write the first line of a definition of the
address@hidden class option of the class @address@hidden
+
+The template is:
address@hidden
address@hidden
+@@defcv @var{category} @var{class} @var{name}
address@hidden
+@@end defcv
address@hidden group
address@hidden example
+
address@hidden@@defcv} creates an entry in the index of variables.
+
address@hidden defivar
address@hidden @@defivar @var{class} @var{name}
+The @code{@@defivar} command is the definition command for instance
+variables in object-oriented programming. @code{@@defivar} is
+equivalent to @samp{@@defcv @{Instance address@hidden @address@hidden
+
+The template is:
address@hidden
address@hidden
+@@defivar @var{class} @var{instance-variable-name}
address@hidden
+@@end defivar
address@hidden group
address@hidden example
+
address@hidden@@defivar} creates an entry in the index of variables.
+
address@hidden deftypeivar
address@hidden @@deftypeivar @var{class} @var{data-type} @var{name}
+The @code{@@deftypeivar} command is the definition command for typed
+instance variables in object-oriented programming. It is similar to
address@hidden@@defivar} with the addition of the @var{data-type} parameter to
+specify the type of the instance variable. @code{@@deftypeivar} creates an
+entry in the index of variables.
+
address@hidden defop
address@hidden @@defop @var{category} @var{class} @var{name} @address@hidden
+The @code{@@defop} command is the general definition command for
+entities that may resemble methods in object-oriented programming.
+These entities take arguments, as functions do, but are associated with
+particular classes of address@hidden
+
+For example, some systems have constructs called @dfn{wrappers} that
+are associated with classes as methods are, but that act more like
+macros than like functions. You could use @code{@@defop Wrapper} to
+describe one of address@hidden
+
+Sometimes it is useful to distinguish methods and @dfn{operations}.
+You can think of an operation as the specification for a method.
+Thus, a window system might specify that all window classes have a
+method named @code{expose}; we would say that this window system
+defines an @code{expose} operation on windows in general. Typically,
+the operation has a name and also specifies the pattern of arguments;
+all methods that implement the operation must accept the same
+arguments, since applications that use the operation do so without
+knowing which method will implement address@hidden
+
+Often it makes more sense to document operations than methods. For
+example, window application developers need to know about the
address@hidden operation, but need not be concerned with whether a
+given class of windows has its own method to implement this operation.
+To describe this operation, you would write:@refill
+
address@hidden
+@@defop Operation windows expose
address@hidden example
+
+The @code{@@defop} command is written at the beginning of a line and
+is followed on the same line by the overall name of the category of
+operation, the name of the class of the operation, the name of the
+operation, and its arguments, if address@hidden
+
+The template is:
address@hidden
address@hidden
+@@defop @var{category} @var{class} @var{name} @address@hidden
address@hidden
+@@end defop
address@hidden group
address@hidden example
+
address@hidden@@defop} creates an entry, such as address@hidden on
address@hidden', in the index of address@hidden
+
address@hidden deftypeop
address@hidden @@deftypeop @var{category} @var{class} @var{data-type}
@var{name} @address@hidden
+The @code{@@deftypeop} command is the definition command for typed
+operations in object-oriented programming. It is similar to
address@hidden@@defop} with the addition of the @var{data-type} parameter to
+specify the return type of the method. @code{@@deftypeop} creates an
+entry in the index of functions.
+
address@hidden @@defmethod @var{class} @var{name} @address@hidden
address@hidden defmethod
+The @code{@@defmethod} command is the definition command for methods
+in object-oriented programming. A method is a kind of function that
+implements an operation for a particular class of objects and its
+subclasses.
+
address@hidden@@defmethod} is equivalent to @samp{@@defop Method @dots{}}.
+The command is written at the beginning of a line and is followed by
+the name of the class of the method, the name of the method, and its
+arguments, if address@hidden
+
address@hidden
+For example:
address@hidden
address@hidden
+@@defmethod @code{bar-class} bar-method argument
address@hidden
+@@end defmethod
address@hidden group
address@hidden example
+
address@hidden
+illustrates the definition for a method called @code{bar-method} of
+the class @code{bar-class}. The method takes an address@hidden
+
+The template is:
+
address@hidden
address@hidden
+@@defmethod @var{class} @var{method-name} @address@hidden
address@hidden
+@@end defmethod
address@hidden group
address@hidden example
+
address@hidden@@defmethod} creates an entry, such as address@hidden on
address@hidden', in the index of address@hidden
+
+
address@hidden @@deftypemethod @var{class} @var{data-type} @var{name}
@address@hidden
address@hidden defmethod
+The @code{@@deftypemethod} command is the definition command for methods
+in object-oriented typed languages, such as C++ and Java. It is similar
+to the @code{@@defmethod} command with the addition of the
address@hidden parameter to specify the return type of the method.
+
address@hidden table
+
+
address@hidden Data Types
address@hidden Data Types
+
+Here is the command for data types:@refill
+
address@hidden @code
address@hidden deftp
address@hidden @@deftp @var{category} @var{name} @address@hidden
+The @code{@@deftp} command is the generic definition command for data
+types. The command is written at the beginning of a line and is
+followed on the same line by the category, by the name of the type
+(which is a word like @code{int} or @code{float}), and then by names of
+attributes of objects of that type. Thus, you could use this command
+for describing @code{int} or @code{float}, in which case you could use
address@hidden type} as the category. (A data type is a category of
+certain objects for purposes of deciding which operations can be
+performed on them.)@refill
+
+In Lisp, for example, @dfn{pair} names a particular data
+type, and an object of that type has two slots called the
address@hidden and the @sc{cdr}. Here is how you would write the first line
+of a definition of @address@hidden
+
address@hidden
address@hidden
+@@deftp @{Data address@hidden pair car cdr
address@hidden
+@@end deftp
address@hidden group
address@hidden example
+
address@hidden 950
+The template is:
+
address@hidden
address@hidden
+@@deftp @var{category} @var{name-of-type} @address@hidden
address@hidden
+@@end deftp
address@hidden group
address@hidden example
+
address@hidden@@deftp} creates an entry in the index of data types.
address@hidden table
+
address@hidden Def Cmd Conventions, Sample Function Definition, Def Cmds in
Detail, Definition Commands
address@hidden Conventions for Writing Definitions
address@hidden Definition conventions
address@hidden Conventions for writing definitions
+
+When you write a definition using @code{@@deffn}, @code{@@defun}, or
+one of the other definition commands, please take care to use
+arguments that indicate the meaning, as with the @var{count} argument
+to the @code{forward-word} function. Also, if the name of an argument
+contains the name of a type, such as @var{integer}, take care that the
+argument actually is of that address@hidden
+
address@hidden Sample Function Definition, , Def Cmd Conventions, Definition
Commands
address@hidden A Sample Function Definition
address@hidden Function definitions
address@hidden Command definitions
address@hidden Macro definitions
address@hidden Sample function definition
+
+A function definition uses the @code{@@defun} and @code{@@end defun}
+commands. The name of the function follows immediately after the
address@hidden@@defun} command and it is followed, on the same line, by the
+parameter address@hidden
+
+Here is a definition from @ref{Calling Functions,,, elisp, The GNU Emacs
+Lisp Reference Manual}.
+
address@hidden
address@hidden apply function &rest arguments
address@hidden calls @var{function} with @var{arguments}, just
+like @code{funcall} but with one difference: the last of
address@hidden is a list of arguments to give to
address@hidden, rather than a single argument. We also say
+that this list is @dfn{appended} to the other arguments.
+
address@hidden returns the result of calling @var{function}.
+As with @code{funcall}, @var{function} must either be a Lisp
+function or a primitive function; special forms and macros
+do not make sense in @code{apply}.
+
address@hidden
+(setq f 'list)
+ @result{} list
+(apply f 'x 'y 'z)
address@hidden Wrong type argument: listp, z
+(apply '+ 1 2 '(3 4))
+ @result{} 10
+(apply '+ '(1 2 3 4))
+ @result{} 10
+
+(apply 'append '((a b c) nil (x y z) nil))
+ @result{} (a b c x y z)
address@hidden example
+
+An interesting example of using @code{apply} is found in the description
+of @address@hidden
address@hidden defun
address@hidden quotation
+
address@hidden 1200
+In the Texinfo source file, this example looks like this:
+
address@hidden
address@hidden
+@@defun apply function &rest arguments
+@@address@hidden@} calls @@address@hidden@} with
+@@address@hidden@}, just like @@address@hidden@} but with one
+difference: the last of @@address@hidden@} is a list of
+arguments to give to @@address@hidden@}, rather than a single
+argument. We also say that this list is @@address@hidden@}
+to the other arguments.
address@hidden group
+
address@hidden
+@@address@hidden@} returns the result of calling
+@@address@hidden@}. As with @@address@hidden@},
+@@address@hidden@} must either be a Lisp function or a
+primitive function; special forms and macros do not make
+sense in @@address@hidden@}.
address@hidden group
+
address@hidden
+@@example
+(setq f 'list)
+ @@address@hidden@} list
+(apply f 'x 'y 'z)
+@@address@hidden@} Wrong type argument: listp, z
+(apply '+ 1 2 '(3 4))
+ @@address@hidden@} 10
+(apply '+ '(1 2 3 4))
+ @@address@hidden@} 10
+
+(apply 'append '((a b c) nil (x y z) nil))
+ @@address@hidden@} (a b c x y z)
+@@end example
address@hidden group
+
address@hidden
+An interesting example of using @@address@hidden@} is found
+in the description of @@address@hidden@}.
+@@end defun
address@hidden group
address@hidden example
+
address@hidden
+In this manual, this function is listed in the Command and Variable
+Index under @address@hidden
+
+Ordinary variables and user options are described using a format like
+that for functions except that variables do not take arguments.
+
+
address@hidden Conditionals
address@hidden Conditionally Visible Text
address@hidden Conditionally visible text
address@hidden Text, conditionally visible
address@hidden Visibility of conditional text
address@hidden If text conditionally visible
+
+Sometimes it is good to use different text for different output formats.
+For example, you can use the @dfn{conditional commands} to specify
+different text for the printed manual and the Info output.
+
+Conditional commands may not be nested.
+
+The conditional commands comprise the following categories.
+
address@hidden @bullet
address@hidden Commands for HTML, Info, or @TeX{}.
address@hidden Commands for not HTML, Info, or @TeX{}.
address@hidden Raw @TeX{} or HTML commands.
address@hidden
+Substituting text for all formats, and testing if a flag is set or clear.
address@hidden itemize
+
address@hidden
+* Conditional Commands:: Specifying text for HTML, Info, or @TeX{}.
+* Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}.
+* Raw Formatter Commands:: Using raw @TeX{} or HTML commands.
+* set clear value:: Designating which text to format (for
+ all output formats); and how to set a
+ flag to a string that you can insert.
address@hidden menu
+
+
address@hidden Conditional Commands
address@hidden Conditional Commands
+
+Texinfo has a pair of commands for each output format, to allow
+conditional inclusion of text for a particular output format.
+
address@hidden ifinfo
address@hidden@@ifinfo} begins segments of text that should be ignored by @TeX{}
+when it typesets the printed manual. The segment of text appears only
+in the Info file and (for historical compatibility) the plain text
+output. The @code{@@ifinfo} command should appear on a line by itself;
+end the Info-only text with a line containing @code{@@end ifinfo} by
+itself.
+
address@hidden iftex
address@hidden ifhtml
address@hidden ifplaintext
+The @code{@@iftex} and @code{@@end iftex} commands are analogous to the
address@hidden@@ifinfo} and @code{@@end ifinfo} commands; they specify text that
+will appear in the printed manual but not in the Info file. Likewise
+for @code{@@ifhtml} and @code{@@end ifhtml}, which specify text to
+appear only in HTML output. And for @code{@@ifplaintext} and
address@hidden@@end ifplaintext}, which specify text to appear only in plain
+text output.
+
+For example,
+
address@hidden
+@@iftex
+This text will appear only in the printed manual.
+@@end iftex
+@@ifinfo
+However, this text will appear only in Info (or plain text).
+@@end ifinfo
+@@ifhtml
+And this text will only appear in HTML.
+@@end ifhtml
+@@ifplaintext
+Whereas this text will only appear in plain text.
+@@end ifplaintext
address@hidden example
+
address@hidden
+The preceding example produces the following line:
+However, this text will appear only in Info (or plain text).
+
address@hidden
+Notice that you only see one of the input lines, depending on which
+version of the manual you are reading.
+
+
address@hidden Conditional Not Commands
address@hidden Conditional Not Commands
address@hidden ifnothtml
address@hidden ifnotinfo
address@hidden ifnotplaintext
address@hidden ifnottex
+
+You can specify text to be included in any output format @emph{other}
+than some given one with the @code{@@address@hidden commands:
address@hidden
+@@ifnothtml @dots{} @@end ifnothtml
+@@ifnotinfo @dots{} @@end ifnotinfo
+@@ifnotplaintext @dots{} @@end ifnotplaintext
+@@ifnottex @dots{} @@end ifnottex
address@hidden example
address@hidden
+(The @code{@@address@hidden command and the @code{@@end} command must
+appear on lines by themselves in your actual source file.)
+
+If the output file is @emph{not} being made for the given format, the
+region is included. Otherwise, it is ignored.
+
+With one exception (for historical compatibility): @code{@@ifnotinfo}
+text is omitted for both Info and plain text output, not just Info. To
+specify text which appears only in Info and not in plain text, use
address@hidden@@ifnotplaintext}, like this:
address@hidden
+This will be in Info, but not plain text.
address@hidden example
+
+The regions delimited by these commands are ordinary Texinfo source as
+with @code{@@iftex}, not raw formatter source as with @code{@@tex}
+(@pxref{Raw Formatter Commands}).
+
+
address@hidden Raw Formatter Commands
address@hidden Raw Formatter Commands
address@hidden @TeX{} commands, using ordinary
address@hidden HTML commands, using ordinary
address@hidden Raw formatter commands
address@hidden Ordinary @TeX{} commands, using
address@hidden Ordinary HTML commands, using
address@hidden Commands using raw @TeX{}
address@hidden Commands using raw HTML
address@hidden plain @TeX{}
+
+Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, you
+can embed some raw @TeX{} commands. Info will ignore these commands
+since they are only in that part of the file which is seen by @TeX{}.
+You can write the @TeX{} commands as you would write them in a normal
address@hidden file, except that you must replace the @samp{\} used by @TeX{}
+with an @samp{@@}. For example, in the @code{@@titlepage} section of a
+Texinfo file, you can use the @TeX{} command @code{@@vskip} to format
+the copyright page. (The @code{@@titlepage} command causes Info to
+ignore the region automatically, as it does with the @code{@@iftex}
+command.)
+
+However, many features of plain @TeX{} will not work, as they are
+overridden by Texinfo features.
+
address@hidden tex
+You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{}
+commands, by delineating a region with the @code{@@tex} and @code{@@end
+tex} commands. (The @code{@@tex} command also causes Info to ignore the
+region, like the @code{@@iftex} command.) The sole exception is that the
address@hidden@@} character still introduces a command, so that @code{@@end tex}
+can be recognized properly.
+
address@hidden Mathematical expressions
+For example, here is a mathematical expression written in
+plain @TeX{}:
+
address@hidden
+@@tex
+$$ \chi^2 = address@hidden@}^N
+ \left (y_i - (a + b x_i)
+ \over \sigma_i\right)^2 $$
+@@end tex
address@hidden example
+
address@hidden
+The output of this example will appear only in a printed manual. If
+you are reading this in Info, you will not see the equation that appears
+in the printed manual.
+
address@hidden
+$$ \chi^2 = \sum_{i=1}^N
+ \left(y_i - (a + b x_i)
+ \over \sigma_i\right)^2 $$
address@hidden tex
+
address@hidden ifhtml
address@hidden html
+Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to delimit
+a region to be included in HTML output only, and @code{@@html @dots{}
+@@end html} for a region of raw HTML (again, except that @code{@@} is
+still the escape character, so the @code{@@end} command can be
+recognized.)
+
+
address@hidden set clear value
address@hidden @code{@@set}, @code{@@clear}, and @code{@@value}
+
+You can direct the Texinfo formatting commands to format or ignore parts
+of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset},
+and @code{@@ifclear} address@hidden
+
+Brief descriptions:
+
address@hidden @code
address@hidden @@set @var{flag} address@hidden
+Set the variable @var{flag}, to the optional @var{value} if specifed.
+
address@hidden @@clear @var{flag}
+Undefine the variable @var{flag}, whether or not it was previously defined.
+
address@hidden @@ifset @var{flag}
+If @var{flag} is set, text through the next @code{@@end ifset} command
+is formatted. If @var{flag} is clear, text through the following
address@hidden@@end ifset} command is ignored.
+
address@hidden @@ifclear @var{flag}
+If @var{flag} is set, text through the next @code{@@end ifclear} command
+is ignored. If @var{flag} is clear, text through the following
address@hidden@@end ifclear} command is formatted.
address@hidden table
+
address@hidden
+* set value:: Expand a flag variable to a string.
+* ifset ifclear:: Format a region if a flag is set.
+* value Example:: An easy way to update edition information.
address@hidden menu
+
+
address@hidden set value
address@hidden @code{@@set} and @code{@@value}
address@hidden value
+
+You use the @code{@@set} command to specify a value for a flag, which is
+later expanded by the @code{@@value} command.
+
+A @dfn{flag} is an identifier. In general, it is best to use only
+letters and numerals in a flag name, not @samp{-} or @samp{_}---they
+will work in some contexts, but not all, due to limitations in @TeX{}.
+
+The value is the remainder of the input line, and can contain anything.
+
+Write the @code{@@set} command like this:
+
address@hidden
+@@set foo This is a string.
address@hidden example
+
address@hidden
+This sets the value of the flag @code{foo} to ``This is a string.''.
+
+The Texinfo formatters then replace an @code{@@address@hidden@address@hidden
+command with the string to which @var{flag} is set. Thus, when
address@hidden is set as shown above, the Texinfo formatters convert this:
+
address@hidden
address@hidden
+@@address@hidden@}
address@hidden @r{to this:}
+This is a string.
address@hidden group
address@hidden example
+
+You can write an @code{@@value} command within a paragraph; but you
+must write an @code{@@set} command on a line of its own.
+
+If you write the @code{@@set} command like this:
+
address@hidden
+@@set foo
address@hidden example
+
address@hidden
+without specifying a string, the value of @code{foo} is the empty string.
+
+If you clear a previously set flag with @code{@@clear @var{flag}}, a
+subsequent @code{@@address@hidden@}} command will report an error.
+
+For example, if you set @code{foo} as follows:@refill
+
address@hidden
+@@set how-much very, very, very
address@hidden example
+
address@hidden
+then the formatters transform
+
address@hidden
address@hidden
+It is a @@address@hidden@} wet day.
address@hidden @r{into}
+It is a very, very, very wet day.
address@hidden group
address@hidden example
+
+If you write
+
address@hidden
+@@clear how-much
address@hidden example
+
address@hidden
+then the formatters transform
+
address@hidden
address@hidden
+It is a @@address@hidden@} wet day.
address@hidden @r{into}
+It is a @{No value for "how-much"@} wet day.
address@hidden group
address@hidden example
+
+
address@hidden ifset ifclear
address@hidden @code{@@ifset} and @code{@@ifclear}
+
address@hidden ifset
+When a @var{flag} is set, the Texinfo formatting commands format text
+between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end
+ifset} commands. When the @var{flag} is cleared, the Texinfo formatting
+commands do @emph{not} format the text. @code{@@ifclear} operates
+analogously.
+
+Write the conditionally formatted text between @code{@@ifset @var{flag}}
+and @code{@@end ifset} commands, like this:
+
address@hidden
address@hidden
+@@ifset @var{flag}
address@hidden
+@@end ifset
address@hidden group
address@hidden example
+
+For example, you can create one document that has two variants, such as
+a manual for a `large' and `small' model:
+
address@hidden shrubbery
address@hidden
+You can use this machine to dig up shrubs
+without hurting them.
+
+@@set large
+
+@@ifset large
+It can also dig up fully grown trees.
+@@end ifset
+
+Remember to replant promptly @dots{}
address@hidden example
+
address@hidden
+In the example, the formatting commands will format the text between
address@hidden@@ifset large} and @code{@@end ifset} because the @code{large}
+flag is set.
+
+When @var{flag} is cleared, the Texinfo formatting commands do
address@hidden format the text between @code{@@ifset @var{flag}} and
address@hidden@@end ifset}; that text is ignored and does not appear in either
+printed or Info output.
+
+For example, if you clear the flag of the preceding example by writing
+an @code{@@clear large} command after the @code{@@set large} command
+(but before the conditional text), then the Texinfo formatting commands
+ignore the text between the @code{@@ifset large} and @code{@@end ifset}
+commands. In the formatted output, that text does not appear; in both
+printed and Info output, you see only the lines that say, ``You can use
+this machine to dig up shrubs without hurting them. Remember to replant
+promptly @dots{}''.
+
address@hidden ifclear
+If a flag is cleared with an @code{@@clear @var{flag}} command, then
+the formatting commands format text between subsequent pairs of
address@hidden@@ifclear} and @code{@@end ifclear} commands. But if the flag
+is set with @code{@@set @var{flag}}, then the formatting commands do
address@hidden format text between an @code{@@ifclear} and an @code{@@end
+ifclear} command; rather, they ignore that text. An @code{@@ifclear}
+command looks like this:
+
address@hidden
+@@ifclear @var{flag}
address@hidden example
+
+
address@hidden value Example
address@hidden @code{@@value} Example
+
+You can use the @code{@@value} command to minimize the number of places
+you need to change when you record an update to a manual. @xref{GNU
+Sample Texts}, for an example of this same principle can work with
+Automake distributions, and full texts.
+
+Here is an example adapted from @ref{Top,, Overview, make, The GNU Make
+Manual}):
+
address@hidden
address@hidden
+Set the flags:
+
address@hidden
address@hidden
+@@set EDITION 0.35 Beta
+@@set VERSION 3.63 Beta
+@@set UPDATED 14 August 1992
+@@set UPDATE-MONTH August 1992
address@hidden group
address@hidden example
+
address@hidden
+Write text for the @code{@@copying} section (@pxref{copying}):
+
address@hidden
address@hidden
+@@copying
+This is Edition @@address@hidden@},
+last updated @@address@hidden@},
+of @@address@hidden GNU Make address@hidden,
+for @@address@hidden@}, version @@address@hidden@}.
+
+Copyright @dots{}
+
+Permission is granted @dots{}
+@@end copying
address@hidden group
address@hidden example
+
address@hidden
+Write text for the title page, for people reading the printed manual:
+
address@hidden
address@hidden
+@@titlepage
+@@title GNU Make
+@@subtitle A Program for Directing Recompilation
+@@subtitle Edition @@address@hidden@}, @dots{}
+@@subtitle @@address@hidden@}
+@@page
+@@insertcopying
address@hidden
+@@end titlepage
address@hidden group
address@hidden example
+
address@hidden
+(On a printed cover, a date listing the month and the year looks less
+fussy than a date listing the day as well as the month and year.)
+
address@hidden
+Write text for the Top node, for people reading the Info file:
+
address@hidden
address@hidden
+@@ifnottex
+@@node Top
+@@top Make
+
+@@insertcopying
address@hidden
+@@end ifnottex
address@hidden group
address@hidden example
+
+After you format the manual, the @code{@@value} constructs have been
+expanded, so the output contains text like this:
+
address@hidden
address@hidden
+This is Edition 0.35 Beta, last updated 14 August 1992,
+of `The GNU Make Manual', for `make', Version 3.63 Beta.
address@hidden group
address@hidden example
address@hidden enumerate
+
+When you update the manual, you change only the values of the flags; you
+do not need to edit the three sections.
+
+
address@hidden Internationalization
address@hidden Internationalization
+
address@hidden Internationalization
+Texinfo has some support for writing in languages other than English,
+although this area still needs considerable work.
+
+For a list of the various accented and special characters Texinfo
+supports, see @ref{Inserting Accents}.
+
address@hidden
+* documentlanguage:: Declaring the current language.
+* documentencoding:: Declaring the input encoding.
address@hidden menu
+
+
address@hidden documentlanguage
address@hidden @code{@@documentlanguage @var{cc}}: Set the Document Language
+
address@hidden documentlanguage
address@hidden Language, declaring
address@hidden Document language, declaring
+
+The @code{@@documentlanguage} command declares the current document
+language. Write it on a line by itself, with a two-letter ISO-639
+language code following (list is included below). If you have a
+multilingual document, the intent is to be able to use this command
+multiple times, to declare each language change. If the command is not
+used at all, the default is @code{en} for English.
+
address@hidden @address@hidden
+At present, this command is ignored in Info and HTML output. For
address@hidden, it causes the file @address@hidden to be read (if it
+exists). Such a file appropriately redefines the various English words
+used in @TeX{} output, such as `Chapter', `See', and so on.
+
address@hidden Hyphenation patterns, language-dependent
+It would be good if this command also changed @TeX{}'s ideas of the
+current hyphenation patterns (via the @TeX{} primitive
address@hidden), but this is unfortunately not currently implemented.
+
address@hidden ISO 639 codes
address@hidden Language codes
+Hereare the valid language codes, from ISO-639.
+
address@hidden @columnfractions .07 .26 .07 .26 .07 .26
address@hidden
address@hidden @tab Afar @tab
address@hidden @tab Abkhazian @tab
address@hidden @tab Afrikaans
address@hidden
address@hidden @tab Amharic @tab
address@hidden @tab Arabic @tab
address@hidden @tab Assamese
address@hidden
address@hidden @tab Aymara @tab
address@hidden @tab Azerbaijani @tab
address@hidden @tab Bashkir
address@hidden
address@hidden @tab Byelorussian @tab
address@hidden @tab Bulgarian @tab
address@hidden @tab Bihari
address@hidden
address@hidden @tab Bislama @tab
address@hidden @tab Bengali; Bangla @tab
address@hidden @tab Tibetan
address@hidden
address@hidden @tab Breton @tab
address@hidden @tab Catalan @tab
address@hidden @tab Corsican
address@hidden
address@hidden @tab Czech @tab
address@hidden @tab Welsh @tab
address@hidden @tab Danish
address@hidden
address@hidden @tab German @tab
address@hidden @tab Bhutani @tab
address@hidden @tab Greek
address@hidden
address@hidden @tab English @tab
address@hidden @tab Esperanto @tab
address@hidden @tab Spanish
address@hidden
address@hidden @tab Estonian @tab
address@hidden @tab Basque @tab
address@hidden @tab Persian
address@hidden
address@hidden @tab Finnish @tab
address@hidden @tab Fiji @tab
address@hidden @tab Faroese
address@hidden
address@hidden @tab French @tab
address@hidden @tab Frisian @tab
address@hidden @tab Irish
address@hidden
address@hidden @tab Scots Gaelic @tab
address@hidden @tab Galician @tab
address@hidden @tab Guarani
address@hidden
address@hidden @tab Gujarati @tab
address@hidden @tab Hausa @tab
address@hidden @tab Hebrew
address@hidden
address@hidden @tab Hindi @tab
address@hidden @tab Croatian @tab
address@hidden @tab Hungarian
address@hidden
address@hidden @tab Armenian @tab
address@hidden @tab Interlingua @tab
address@hidden @tab Indonesian
address@hidden
address@hidden @tab Interlingue @tab
address@hidden @tab Inupiak @tab
address@hidden @tab Icelandic
address@hidden
address@hidden @tab Italian @tab
address@hidden @tab Inuktitut @tab
address@hidden @tab Japanese
address@hidden
address@hidden @tab Javanese @tab
address@hidden @tab Georgian @tab
address@hidden @tab Kazakh
address@hidden
address@hidden @tab Greenlandic @tab
address@hidden @tab Cambodian @tab
address@hidden @tab Kannada
address@hidden
address@hidden @tab Kashmiri @tab
address@hidden @tab Korean @tab
address@hidden @tab Kurdish
address@hidden
address@hidden @tab Kirghiz @tab
address@hidden @tab Latin @tab
address@hidden @tab Lingala
address@hidden
address@hidden @tab Lithuanian @tab
address@hidden @tab Laothian @tab
address@hidden @tab Latvian, Lettish
address@hidden
address@hidden @tab Malagasy @tab
address@hidden @tab Maori @tab
address@hidden @tab Macedonian
address@hidden
address@hidden @tab Malayalam @tab
address@hidden @tab Mongolian @tab
address@hidden @tab Moldavian
address@hidden
address@hidden @tab Marathi @tab
address@hidden @tab Malay @tab
address@hidden @tab Maltese
address@hidden
address@hidden @tab Burmese @tab
address@hidden @tab Nauru @tab
address@hidden @tab Nepali
address@hidden
address@hidden @tab Dutch @tab
address@hidden @tab Norwegian @tab
address@hidden @tab Occitan
address@hidden
address@hidden @tab (Afan) Oromo @tab
address@hidden @tab Oriya @tab
address@hidden @tab Punjabi
address@hidden
address@hidden @tab Polish @tab
address@hidden @tab Pashto, Pushto @tab
address@hidden @tab Portuguese
address@hidden
address@hidden @tab Quechua @tab
address@hidden @tab Rhaeto-Romance @tab
address@hidden @tab Kirundi
address@hidden
address@hidden @tab Romanian @tab
address@hidden @tab Russian @tab
address@hidden @tab Kinyarwanda
address@hidden
address@hidden @tab Sanskrit @tab
address@hidden @tab Sindhi @tab
address@hidden @tab Sangro
address@hidden
address@hidden @tab Serbo-Croatian @tab
address@hidden @tab Sinhalese @tab
address@hidden @tab Slovak
address@hidden
address@hidden @tab Slovenian @tab
address@hidden @tab Samoan @tab
address@hidden @tab Shona
address@hidden
address@hidden @tab Somali @tab
address@hidden @tab Albanian @tab
address@hidden @tab Serbian
address@hidden
address@hidden @tab Siswati @tab
address@hidden @tab Sesotho @tab
address@hidden @tab Sundanese
address@hidden
address@hidden @tab Swedish @tab
address@hidden @tab Swahili @tab
address@hidden @tab Tamil
address@hidden
address@hidden @tab Telugu @tab
address@hidden @tab Tajik @tab
address@hidden @tab Thai
address@hidden
address@hidden @tab Tigrinya @tab
address@hidden @tab Turkmen @tab
address@hidden @tab Tagalog
address@hidden
address@hidden @tab Setswana @tab
address@hidden @tab Tonga @tab
address@hidden @tab Turkish
address@hidden
address@hidden @tab Tsonga @tab
address@hidden @tab Tatar @tab
address@hidden @tab Twi
address@hidden
address@hidden @tab Uighur @tab
address@hidden @tab Ukrainian @tab
address@hidden @tab Urdu
address@hidden
address@hidden @tab Uzbek @tab
address@hidden @tab Vietnamese @tab
address@hidden @tab Volapuk
address@hidden
address@hidden @tab Wolof @tab
address@hidden @tab Xhosa @tab
address@hidden @tab Yiddish
address@hidden
address@hidden @tab Yoruba @tab
address@hidden @tab Zhuang @tab
address@hidden @tab Chinese
address@hidden
address@hidden @tab Zulu
address@hidden multitable
+
+
address@hidden documentencoding
address@hidden @code{@@documentencoding @var{enc}}: Set Input Encoding
+
address@hidden documentencoding
address@hidden Encoding, declaring
address@hidden Input encoding, declaring
address@hidden Document input encoding
+
+The @code{@@documentencoding} command declares the input document
+encoding. Write it on a line by itself, with a valid encoding
+specification following, such as @samp{ISO-8859-1}.
+
address@hidden http-equiv, and charset
address@hidden meta HTML tag, and charset
+At present, this is used only in HTML output from @code{makeinfo}. If a
+document encoding @var{enc} is specified, it is used in a
address@hidden<meta>} tag included in the @samp{<head>} of the output:
+
address@hidden
+<meta http-equiv="Content-Type" content="text/html;
+ address@hidden">
address@hidden example
+
+
address@hidden Defining New Texinfo Commands
address@hidden Defining New Texinfo Commands
address@hidden Macros
address@hidden Defining new Texinfo commands
address@hidden New Texinfo commands, defining
address@hidden Texinfo commands, defining new
address@hidden User-defined Texinfo commands
+
+Texinfo provides several ways to define new commands:
+
address@hidden @bullet
address@hidden
+A Texinfo @dfn{macro} allows you to define a new Texinfo command as any
+sequence of text and/or existing commands (including other macros). The
+macro can have any number of @dfn{parameters}---text you supply each
+time you use the macro.
+
+Incidentally, these macros have nothing to do with the @code{@@defmac}
+command, which is for documenting macros in the subject of the manual
+(@pxref{Def Cmd Template}).
+
address@hidden
address@hidden@@alias} is a convenient way to define a new name for an existing
+command.
+
address@hidden
address@hidden@@definfoenclose} allows you to define new commands with
+customized output in the Info file.
+
address@hidden itemize
+
address@hidden
+* Defining Macros:: Defining and undefining new commands.
+* Invoking Macros:: Using a macro, once you've defined it.
+* Macro Details:: Beyond basic macro usage.
+* alias:: Command aliases.
+* definfoenclose:: Customized highlighting.
address@hidden menu
+
+
address@hidden Defining Macros
address@hidden Defining Macros
address@hidden Defining macros
address@hidden Macro definitions
+
address@hidden macro
+You use the Texinfo @code{@@macro} command to define a macro, like this:
+
address@hidden
+@@macro @address@hidden@var{param1}, @var{param2}, @address@hidden
address@hidden @dots{} address@hidden @dots{}
+@@end macro
address@hidden example
+
+The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to
+arguments supplied when the macro is subsequently used in the document
+(described in the next section).
+
+For a macro to work with @TeX{}, @var{macroname} must consist entirely
+of letters: no digits, hyphens, underscores, or other special characters.
+
+If a macro needs no parameters, you can define it either with an empty
+list (@samp{@@macro foo @address@hidden) or with no braces at all
(@samp{@@macro
+foo}).
+
address@hidden Body of a macro
address@hidden Mutually recursive macros
address@hidden Recursion, mutual
+The definition or @dfn{body} of the macro can contain most Texinfo
+commands, including previously-defined macros. Not-yet-defined macro
+invocations are not allowed; thus, it is not possible to have mutually
+recursive Texinfo macros. Also, a macro definition that defines another
+macro does not work in @TeX{} due to limitations in the design of
address@hidden@@macro}.
+
address@hidden Parameters to macros
+In the macro body, instances of a parameter name surrounded by
+backslashes, as in @address@hidden in the example above, are
+replaced by the corresponding argument from the macro invocation. You
+can use parameter names any number of times in the body, including zero.
+
address@hidden Backslash in macros
+To get a single @samp{\} in the macro expansion, use @samp{\\}. Any
+other use of @samp{\} in the body yields a warning.
+
address@hidden Spaces in macros
address@hidden Whitespace in macros
+The newlines after the @code{@@macro} line and before the @code{@@end
+macro} line are ignored, that is, not included in the macro body. All
+other whitespace is treated according to the usual Texinfo rules.
+
address@hidden Recursive macro invocations
address@hidden rmacro
+To allow a macro to be used recursively, that is, in an argument to a
+call to itself, you must define it with @samp{@@rmacro}, like this:
+
address@hidden
+@@rmacro rmac @address@hidden
+a\arg\b
+@@end rmacro
address@hidden
+@@address@hidden@@address@hidden@address@hidden
address@hidden example
+
+This produces the output `a1atextb2b'. With @samp{@@macro} instead of
address@hidden@@rmacro}, an error message is given.
+
address@hidden unmacro
address@hidden Macros, undefining
address@hidden Undefining macros
+You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}.
+It is not an error to undefine a macro that is already undefined.
+For example:
+
address@hidden
+@@unmacro foo
address@hidden example
+
+
address@hidden Invoking Macros
address@hidden Invoking Macros
address@hidden Invoking macros
address@hidden Expanding macros
address@hidden Running macros
address@hidden Macro invocation
+
+After a macro is defined (see the previous section), you can use
+(@dfn{invoke}) it in your document like this:
+
address@hidden
+@@@var{macroname} @address@hidden, @var{arg2}, @address@hidden
address@hidden example
+
address@hidden and the result will be just as if you typed the body of
address@hidden at that spot. For example:
+
address@hidden
+@@macro foo @{p, address@hidden
+Together: \p\ & \q\.
+@@end macro
+@@address@hidden, address@hidden
address@hidden example
+
address@hidden produces:
+
address@hidden
+Together: a & b.
address@hidden display
+
address@hidden Backslash, and macros
+Thus, the arguments and parameters are separated by commas and delimited
+by braces; any whitespace after (but not before) a comma is ignored.
+The braces are required in the invocation (but not the definition), even
+when the macro takes no arguments, consistent with all other Texinfo
+commands. For example:
+
address@hidden
+@@macro argless @address@hidden
+No arguments here.
+@@end macro
+@@address@hidden@}
address@hidden example
+
address@hidden produces:
+
address@hidden
+No arguments here.
address@hidden display
+
address@hidden Comma, in macro arguments
address@hidden Braces, in macro arguments
+To insert a comma, brace, or backslash in an argument, prepend a
+backslash, as in
+
address@hidden
+@@@var{macname} @address@hidden@}\,@}
address@hidden example
+
address@hidden
+which will pass the (almost certainly error-producing) argument
address@hidden@address@hidden,} to @var{macname}. However, commas in
parameters, even
+if escaped by a backslash, might cause trouble in @TeX{}.
+
+If the macro is defined to take a single argument, and is invoked
+without any braces, the entire rest of the line after the macro name is
+supplied as the argument. For example:
+
address@hidden
+@@macro bar @address@hidden
+Twice: \p\ & \p\.
+@@end macro
+@@bar aah
address@hidden example
+
address@hidden produces:
+
address@hidden Sorry for cheating, but let's not require macros to process the
manual.
address@hidden
+Twice: aah & aah.
address@hidden display
+
+If the macro is defined to take a single argument, and is invoked with
+braces, the braced text is passed as the argument, regardless of
+commas. For example:
+
address@hidden
+@@macro bar @address@hidden
+Twice: \p\ & \p\.
+@@end macro
+@@address@hidden,address@hidden
address@hidden example
+
address@hidden produces:
+
address@hidden
+Twice: a,b & a,b.
address@hidden display
+
+
address@hidden Macro Details
address@hidden Macro Details
address@hidden Macro details
address@hidden Details of macro usage
+
+Due to unavoidable disparities in the @TeX{} and @command{makeinfo}
+implementations, Texinfo macros have the following limitations.
+
address@hidden @bullet
address@hidden
+All macros are expanded inside at least one @TeX{} group. This means
+that @code{@@set} and other such commands will have no effect inside a
+macro.
+
address@hidden
+Macros containing a command which must be on a line by itself, such as a
+conditional, cannot be invoked in the middle of a line.
+
address@hidden
+Commas in macro arguments, even if escaped by a backslash, don't
+always work.
+
address@hidden
+The @TeX{} implementation cannot construct macros that define macros in
+the natural way. To do this, you must use conditionals and raw @TeX{}.
+For example:
+
address@hidden
+@@ifnottex
+@@macro ctor @{name, address@hidden
+@@macro \name\
+something involving \arg\ somehow
+@@end macro
+@@end macro
+@@end ifnottex
+@@tex
address@hidden,@}
+\gdef\ctorx#1,#2,@address@hidden involving #2 address@hidden@}
+@@end tex
address@hidden example
+
address@hidden
+It is best to avoid comments inside macro definitions.
+
address@hidden itemize
+
+If some macro feature causes errors when producing the printed version
+of a manual, try expanding the macros with @command{makeinfo} by
+invoking @command{texi2dvi} with the @samp{-e} option; see @ref{Format
+with texi2dvi}.
+
address@hidden alias
address@hidden @samp{@@alias @address@hidden
address@hidden Aliases, command
address@hidden Command aliases
address@hidden alias
+
+The @samp{@@alias} command defines a new command to be just like an
+existing one. This is useful for defining additional markup names, thus
+preserving semantic information in the input even though the output
+result may be the same.
+
+Write the @samp{@@alias} command on a line by itself, followed by the
+new command name, an equals sign, and the existing command name.
+Whitespace around the equals sign is ignored. Thus:
address@hidden
+@@alias @var{new} = @var{existing}
address@hidden example
+
+For example, if your document contains citations for both books and
+some other media (movies, for example), you might like to define a
+macro @code{@@address@hidden@}} that does the same thing as an ordinary
address@hidden@@address@hidden@}} but conveys the extra semantic information as
well.
+You'd do this as follows:
+
address@hidden
+@@alias moviecite = cite
address@hidden example
+
+Macros do not always have the same effect due to vagaries of argument
+parsing. Also, aliases are much simpler to define than macros. So the
+command is not redundant. (It was also heavily used in the Jargon File!)
+
+Aliases must not be recursive, directly or indirectly.
+
address@hidden definfoenclose
address@hidden @samp{definfoenclose}: Customized Highlighting
address@hidden Highlighting, customized
address@hidden Customized highlighting
address@hidden definfoenclose
+
+A @code{@@definfoenclose} command may be used to define a highlighting
+command for Info, but not for @TeX{}. A command defined using
address@hidden@@definfoenclose} marks text by enclosing it in strings that
+precede and follow the text. You can use this to get closer control of
+your Info output.
+
+Presumably, if you define a command with @code{@@definfoenclose} for Info,
+you will create a corresponding command for @TeX{}, either in
address@hidden, @file{texinfo.cnf}, or within an @samp{@@iftex} in
+your document.
+
+Write a @code{@@definfoenclose} command on a line and follow it with
+three arguments separated by commas. The first argument to
address@hidden@@definfoenclose} is the @@-command name (without the @code{@@});
+the second argument is the Info start delimiter string; and the third
+argument is the Info end delimiter string. The latter two arguments
+enclose the highlighted text in the Info file. A delimiter string may
+contain spaces. Neither the start nor end delimiter is required. If
+you do not want a start delimiter but do want an end delimiter, you must
+follow the command name with two commas in a row; otherwise, the Info
+formatting commands will naturally misinterpret the end delimiter string
+you intended as the start delimiter string.
+
+If you do a @code{@@definfoenclose} on the name of a pre-defined macro
+(such as @code{@@emph}, @code{@@strong}, @code{@@t}, or @code{@@i}), the
+enclosure definition will override the built-in definition.
+
+An enclosure command defined this way takes one argument in braces; this
+is intended for new markup commands (@pxref{Marking Text}).
+
address@hidden phoo
+For example, you can write:
+
address@hidden
+@@definfoenclose phoo,//,\\
address@hidden example
+
address@hidden
+near the beginning of a Texinfo file to define @code{@@phoo} as an Info
+formatting command that inserts `//' before and `\\' after the argument
+to @code{@@phoo}. You can then write @code{@@address@hidden@}} wherever you
+want `//bar\\' highlighted in Info.
+
+Also, for @TeX{} formatting, you could write
+
address@hidden
+@@iftex
+@@global@@let@@phoo=@@i
+@@end iftex
address@hidden example
+
address@hidden
+to define @code{@@phoo} as a command that causes @TeX{} to typeset the
+argument to @code{@@phoo} in italics.
+
+Each definition applies to its own formatter: one for @TeX{}, the other
+for @code{texinfo-format-buffer} or @code{texinfo-format-region}. The
address@hidden@@definfoenclose} command need not be within @samp{@@ifinfo}, but
+the raw @TeX{} commands do need to be in @samp{@@iftex}.
+
address@hidden headword
+Here is another example: write
+
address@hidden
+@@definfoenclose headword, , :
address@hidden example
+
address@hidden
+near the beginning of the file, to define @code{@@headword} as an Info
+formatting command that inserts nothing before and a colon after the
+argument to @code{@@headword}.
+
address@hidden@@definfoenclose} definitions must not be recursive, directly or
+indirectly.
+
+
address@hidden Hardcopy
address@hidden Formatting and Printing Hardcopy
address@hidden Format and print hardcopy
address@hidden Printing hardcopy
address@hidden Hardcopy, printing it
address@hidden Making a printed manual
address@hidden Sorting indices
address@hidden Indices, sorting
address@hidden @TeX{} index sorting
address@hidden texindex
+
+There are three major shell commands for making a printed manual from a
+Texinfo file: one for converting the Texinfo file into a file that will be
+printed, a second for sorting indices, and a third for printing the
+formatted document. When you use the shell commands, you can either
+work directly in the operating system shell or work within a shell
+inside GNU Emacs.
+
+If you are using GNU Emacs, you can use commands provided by Texinfo
+mode instead of shell commands. In addition to the three commands to
+format a file, sort the indices, and print the result, Texinfo mode
+offers key bindings for commands to recenter the output buffer, show the
+print queue, and delete a job from the print queue.
+
address@hidden
+* Use TeX:: Use @TeX{} to format for hardcopy.
+* Format with tex/texindex:: How to format with explicit shell commands.
+* Format with texi2dvi:: A simpler way to format.
+* Print with 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.
+* smallbook:: How to print small format books and manuals.
+* A4 Paper:: How to print on A4 or A5 paper.
+* 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.
address@hidden menu
+
address@hidden Use TeX
address@hidden Use @TeX{}
+
+The typesetting program called @TeX{} is used for formatting a Texinfo
+file. @TeX{} is a very powerful typesetting program and, if used correctly,
+does an exceptionally good job. (@xref{Obtaining TeX, , How to Obtain
address@hidden, for information on how to obtain @TeX{}.)
+
+The standalone @code{makeinfo} program and Emacs functions
address@hidden and @code{texinfo-format-buffer} commands
+read the very same @@-commands in the Texinfo file as does @TeX{}, but
+process them differently to make an Info file (@pxref{Creating an Info
+File}).
+
+
address@hidden Format with tex/texindex
address@hidden Format with @code{tex} and @code{texindex}
address@hidden Shell formatting with @code{tex} and @code{texindex}
address@hidden Formatting with @code{tex} and @code{texindex}
address@hidden DVI file
+
+Format the Texinfo file with the shell command @code{tex} followed by
+the name of the Texinfo file. For example:
+
address@hidden
+tex foo.texi
address@hidden example
+
address@hidden @TeX{} will produce a @dfn{DVI file} as well as several auxiliary
+files containing information for indices, cross references, etc. The
+DVI file (for @dfn{DeVice Independent} file) can be printed on virtually
+any device (see the following sections).
+
address@hidden texindex
+The @code{tex} formatting command itself does not sort the indices; it
+writes an output file of unsorted index data. (The @code{texi2dvi}
+command automatically generates indices; @pxref{Format with texi2dvi,,
+Format with @code{texi2dvi}}.) To generate a printed index after
+running the @code{tex} command, you first need a sorted index to work
+from. The @code{texindex} command sorts indices. (The source file
address@hidden comes as part of the standard Texinfo distribution,
+among other places.)@refill
+
address@hidden Names of index files
address@hidden Index file names
+The @code{tex} formatting command outputs unsorted index files under
+names that obey a standard convention: the name of your main input file
+with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c,
+Web2c}) extension removed, followed by the two letter names of indices.
+For example, the raw index output files for the input file
address@hidden would be @file{foo.cp}, @file{foo.vr}, @file{foo.fn},
address@hidden, @file{foo.pg} and @file{foo.ky}. Those are exactly the
+arguments to give to @code{texindex}.
+
address@hidden 1000
address@hidden Wildcards
address@hidden Globbing
+Instead of specifying all the unsorted index file names explicitly, you
+can use @samp{??} as shell wildcards and give the command in this
+form:
+
address@hidden
+texindex foo.??
address@hidden example
+
address@hidden
+This command will run @code{texindex} on all the unsorted index files,
+including any that you have defined yourself using @code{@@defindex}
+or @code{@@defcodeindex}. (You may execute @samp{texindex foo.??}
+even if there are similarly named files with two letter extensions
+that are not index files, such as @samp{foo.el}. The @code{texindex}
+command reports but otherwise ignores such files.)
+
+For each file specified, @code{texindex} generates a sorted index file
+whose name is made by appending @samp{s} to the input file name. The
address@hidden@@printindex} command looks for a file with that name
+(@pxref{Printing Indices & Menus}). @code{texindex} does not alter the
+raw index output file.
+
+After you have sorted the indices, you need to rerun the @code{tex}
+formatting command on the Texinfo file. This regenerates the DVI file,
+this time with up-to-date index entries.
+
+Finally, you may need to run @code{tex} one more time, to get the page
+numbers in the cross-references correct.
+
+To summarize, this is a five step process:
+
address@hidden
address@hidden
+Run @code{tex} on your Texinfo file. This generates a DVI file (with
+undefined cross-references and no indices), and the raw index files
+(with two letter extensions).
+
address@hidden
+Run @code{texindex} on the raw index files. This creates the
+corresponding sorted index files (with three letter extensions).
+
address@hidden
+Run @code{tex} again on your Texinfo file. This regenerates the DVI
+file, this time with indices and defined cross-references, but with page
+numbers for the cross-references from last time, generally incorrect.
+
address@hidden
+Sort the indices again, with @code{texindex}.
+
address@hidden
+Run @code{tex} one last time. This time the correct page numbers are
+written for the cross-references.
address@hidden enumerate
+
address@hidden texi2dvi
+Alternatively, it's a one-step process: run @code{texi2dvi}
+(@pxref{Format with texi2dvi}).
+
+You need not run @code{texindex} each time after you run @code{tex}. If
+you do not, on the next run, the @code{tex} formatting command will use
+whatever sorted index files happen to exist from the previous use of
address@hidden This is usually ok while you are debugging.
+
address@hidden Auxiliary files, avoiding
address@hidden novalidate
address@hidden Pointer validation, suppressing
address@hidden Chapters, formatting one at a time
+Sometimes you may wish to print a document while you know it is
+incomplete, or to print just one chapter of a document. In that case,
+the usual auxiliary files that @TeX{} creates and warnings @TeX{} gives
+when cross-references are not satisfied are just nuisances. You can
+avoid them with the @code{@@novalidate} command, which you must give
address@hidden the @code{@@setfilename} command
+(@pxref{setfilename,,@code{@@setfilename}}). Thus, the beginning of
+your file would look approximately like this:
+
address@hidden
+\input texinfo
+@@novalidate
+@@setfilename myfile.info
address@hidden
address@hidden example
+
address@hidden @code{@@novalidate} also turns off validation in
address@hidden, just like its @code{--no-validate} option
+(@pxref{Pointer Validation}).
+
+
address@hidden Format with texi2dvi
address@hidden Format with @code{texi2dvi}
address@hidden texi2dvi @r{(shell script)}
+
+The @code{texi2dvi} command automatically runs both @code{tex} and
address@hidden as many times as necessary to produce a DVI file with
+sorted indices and all cross-references resolved. It simplifies the
address@hidden@address@hidden@code{tex} sequence
+described in the previous section.
+
+To run @code{texi2dvi} on an input file @file{foo.texi}, do this (where
address@hidden } is your shell prompt):
+
address@hidden
+prompt$ @kbd{texi2dvi foo.texi}
address@hidden example
+
+As shown in this example, the input filenames to @code{texi2dvi} must
+include any extension (@samp{.texi}, @samp{.texinfo}, etc.). Under
+MS-DOS and perhaps in other circumstances, you may need to run @samp{sh
+texi2dvi foo.texi} instead of relying on the operating system to invoke
+the shell on the @samp{texi2dvi} script.
+
+Perhaps the most useful option to @code{texi2dvi} is
address@hidden@var{cmd}}. This inserts @var{cmd} on a line by itself
+after the @code{@@setfilename} in a temporary copy of the input file
+before running @TeX{}. With this, you can specify different printing
+formats, such as @code{@@smallbook} (@pxref{smallbook}),
address@hidden@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes}
+(@pxref{pagesizes}), without actually changing the document source.
+(You can also do this on a site-wide basis with @file{texinfo.cnf};
address@hidden for TeX,,Preparing for @TeX{}}).
+
+For a list of other options, run @samp{texi2dvi --help}.
+
+
address@hidden Print with lpr
address@hidden Shell Print Using @code{lpr -d}
address@hidden lpr @r{(DVI print command)}
+
+The precise command to print a DVI file depends on your system
+installation. Two common ones are @samp{dvips foo.dvi -o} and @samp{lpr
+-d foo.dvi}.
+
+For example, the following commands will (perhaps) suffice to sort the
+indices, format, and print the @cite{Bison Manual}:
+
address@hidden
address@hidden
+tex bison.texinfo
+texindex bison.??
+tex bison.texinfo
+lpr -d bison.dvi
address@hidden group
address@hidden example
+
address@hidden
+(Remember that the shell commands may be different at your site; but
+these are commonly used versions.)
+
+Using the @code{texi2dvi} shell script (see the previous section):
+
address@hidden
address@hidden
+texi2dvi bison.texinfo
+lpr -d bison.dvi
+# or perhaps dvips bison.dvi -o
address@hidden group
address@hidden example
+
address@hidden Shell printing, on MS-DOS/MS-Windows
address@hidden Printing DVI files, on MS-DOS/MS-Windows
address@hidden address@hidden, replacements on MS-DOS/MS-Windows}
address@hidden is a standard program on Unix systems, but it is usually
+absent on MS-DOS/MS-Windows. Some network packages come with a
+program named @code{lpr}, but these are usually limited to sending files
+to a print server over the network, and generally don't support the
address@hidden option. If you are unfortunate enough to work on one of these
+systems, you have several alternative ways of printing DVI files:
+
address@hidden @bullet{}
address@hidden Find and install a Unix-like @code{lpr} program, or its clone.
+If you can do that, you will be able to print DVI files just like
+described above.
+
address@hidden Send the DVI files to a network printer queue for DVI files.
+Some network printers have special queues for printing DVI files. You
+should be able to set up your network software to send files to that
+queue. In some cases, the version of @code{lpr} which comes with your
+network software will have a special option to send a file to specific
+queues, like this:
+
address@hidden
+lpr -Qdvi -hprint.server.domain bison.dvi
address@hidden example
+
address@hidden Convert the DVI file to a Postscript or PCL file and send it to
your
+local printer. @xref{dvips invocation,,, dvips, Dvips}, and the man
+pages for @code{dvilj}, for detailed description of these tools. Once
+the DVI file is converted to the format your local printer understands
+directly, just send it to the appropriate port, usually @samp{PRN}.
address@hidden itemize
+
+
address@hidden Within Emacs
address@hidden From an Emacs Shell
address@hidden Print, format from Emacs shell
address@hidden Format, print from Emacs shell
address@hidden Shell, format, print from
address@hidden Emacs shell, format, print from
address@hidden GNU Emacs shell, format, print from
+
+You can give formatting and printing commands from a shell within GNU
+Emacs. To create a shell within Emacs, type @kbd{M-x shell}. In this
+shell, you can format and print the document. @xref{Hardcopy, , Format
+and Print Hardcopy}, for details.
+
+You can switch to and from the shell buffer while @code{tex} is
+running and do other editing. If you are formatting a long document
+on a slow machine, this can be very address@hidden
+
+You can also use @code{texi2dvi} from an Emacs shell. For example,
+here is how to use @code{texi2dvi} to format and print @cite{Using and
+Porting GNU CC} from a shell within Emacs:
+
address@hidden
address@hidden
+texi2dvi gcc.texinfo
+lpr -d gcc.dvi
address@hidden group
address@hidden example
+
address@hidden Mode Printing}, for more information about formatting
+and printing in Texinfo address@hidden
+
+
address@hidden Texinfo Mode Printing, Compile-Command, Within Emacs, Hardcopy
address@hidden Formatting and Printing in Texinfo Mode
address@hidden Region printing in Texinfo mode
address@hidden Format and print in Texinfo mode
address@hidden Print and format in Texinfo mode
+
+Texinfo mode provides several predefined key commands for @TeX{}
+formatting and printing. These include commands for sorting indices,
+looking at the printer queue, killing the formatting job, and
+recentering the display of the buffer in which the operations
address@hidden
+
address@hidden @kbd
address@hidden C-c C-t C-b
address@hidden M-x texinfo-tex-buffer
+Run @code{texi2dvi} on the current address@hidden
+
address@hidden C-c C-t C-r
address@hidden M-x texinfo-tex-region
+Run @TeX{} on the current address@hidden
+
address@hidden C-c C-t C-i
address@hidden M-x texinfo-texindex
+Sort the indices of a Texinfo file formatted with
address@hidden@refill
+
address@hidden C-c C-t C-p
address@hidden M-x texinfo-tex-print
+Print a DVI file that was made with @code{texinfo-tex-region} or
address@hidden@refill
+
address@hidden C-c C-t C-q
address@hidden M-x tex-show-print-queue
+Show the print address@hidden
+
address@hidden C-c C-t C-d
address@hidden M-x texinfo-delete-from-print-queue
+Delete a job from the print queue; you will be prompted for the job
+number shown by a preceding @kbd{C-c C-t C-q} command
+(@code{texinfo-show-tex-print-queue})address@hidden
+
address@hidden C-c C-t C-k
address@hidden M-x tex-kill-job
+Kill the currently running @TeX{} job started by either
address@hidden or @code{texinfo-tex-buffer}, or any other
+process running in the Texinfo shell address@hidden
+
address@hidden C-c C-t C-x
address@hidden M-x texinfo-quit-job
+Quit a @TeX{} formatting job that has stopped because of an error by
+sending an @key{x} to it. When you do this, @TeX{} preserves a record
+of what it did in a @file{.log} address@hidden
+
address@hidden C-c C-t C-l
address@hidden M-x tex-recenter-output-buffer
+Redisplay the shell buffer in which the @TeX{} printing and formatting
+commands are run to show its most recent address@hidden
address@hidden table
+
address@hidden 1000
+Thus, the usual sequence of commands for formatting a buffer is as
+follows (with comments to the right):@refill
+
address@hidden
address@hidden
+C-c C-t C-b @r{Run @code{texi2dvi} on the buffer.}
+C-c C-t C-p @r{Print the DVI file.}
+C-c C-t C-q @r{Display the printer queue.}
address@hidden group
address@hidden example
+
+The Texinfo mode @TeX{} formatting commands start a subshell in Emacs
+called the @file{*tex-shell*}. The @code{texinfo-tex-command},
address@hidden, and @code{tex-dvi-print-command}
+commands are all run in this shell.
+
+You can watch the commands operate in the @samp{*tex-shell*} buffer,
+and you can switch to and from and use the @samp{*tex-shell*} buffer
+as you would any other shell address@hidden
+
address@hidden 1500
+The formatting and print commands depend on the values of several variables.
+The default values are:@refill
+
address@hidden
address@hidden
+ @r{Variable} @r{Default value}
+
+texinfo-texi2dvi-command "texi2dvi"
+texinfo-tex-command "tex"
+texinfo-texindex-command "texindex"
+texinfo-delete-from-print-queue-command "lprm"
+texinfo-tex-trailer "@@bye"
+tex-start-of-header "%**start"
+tex-end-of-header "%**end"
+tex-dvi-print-command "lpr -d"
+tex-show-queue-command "lpq"
address@hidden group
address@hidden example
+
+You can change the values of these variables with the @kbd{M-x
+edit-options} command (@pxref{Edit Options, , Editing Variable Values,
+emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command
+(@pxref{Examining, , Examining and Setting Variables, emacs, The GNU
+Emacs Manual}), or with your @file{.emacs} initialization file
+(@pxref{Init File, , , emacs, The GNU Emacs Manual})address@hidden
+
address@hidden Customize Emacs package (@t{Development/Docs/Texinfo})
+Beginning with version 20, GNU Emacs offers a user-friendly interface,
+called @dfn{Customize}, for changing values of user-definable variables.
address@hidden Customization, , Easy Customization Interface, emacs, The GNU
+Emacs Manual}, for more details about this. The Texinfo variables can
+be found in the @samp{Development/Docs/Texinfo} group, once you invoke
+the @kbd{M-x customize} command.
+
+
address@hidden Compile-Command
address@hidden Using the Local Variables List
address@hidden Local variables
address@hidden Compile command for formatting
address@hidden Format with the compile command
+
+Yet another way to apply the @TeX{} formatting command to a Texinfo file
+is to put that command in a @dfn{local variables list} at the end of the
+Texinfo file. You can then specify the @code{tex} or @code{texi2dvi}
+commands as a @code{compile-command} and have Emacs run it by typing
address@hidden compile}. This creates a special shell called the
address@hidden buffer in which Emacs runs the compile command.
+For example, at the end of the @file{gdb.texinfo} file, after the
address@hidden@@bye}, you could put the following:@refill
+
address@hidden
address@hidden
+Local Variables:
+compile-command: "texi2dvi gdb.texinfo"
+End:
address@hidden group
address@hidden example
+
address@hidden
+This technique is most often used by programmers who also compile programs
+this way; see @ref{Compilation, , , emacs, The GNU Emacs address@hidden
+
+
address@hidden Requirements Summary
address@hidden @TeX{} Formatting Requirements Summary
address@hidden Requirements for formatting
address@hidden Minimal requirements for formatting
address@hidden Formatting requirements
+
+Every Texinfo file that is to be input to @TeX{} must begin with a
address@hidden command and must contain an @code{@@setfilename} command:
+
address@hidden
+\input texinfo
+@@setfilename @address@hidden
address@hidden example
+
address@hidden
+The first command instructs @TeX{} to load the macros it needs to
+process a Texinfo file and the second command opens auxiliary files.
+
+Every Texinfo file must end with a line that terminates @TeX{}'s
+processing and forces out unfinished pages:
+
address@hidden
+@@bye
address@hidden example
+
+Strictly speaking, these lines are all a Texinfo file needs to be
+processed successfully by @TeX{}.
+
+Usually, however, the beginning includes an @code{@@settitle} command to
+define the title of the printed manual, an @code{@@setchapternewpage}
+command, a title page, a copyright page, and permissions. Besides an
address@hidden@@bye}, the end of a file usually includes indices and a table of
+contents. (And of course most manuals contain a body of text as well.)
+
+For more information, see:
address@hidden @bullet
address@hidden @ref{settitle, , @code{@@settitle}}
address@hidden @ref{setchapternewpage, , @code{@@setchapternewpage}}
address@hidden @ref{Headings, ,Page Headings}
address@hidden @ref{Titlepage & Copyright Page}
address@hidden @ref{Printing Indices & Menus}
address@hidden @ref{Contents}
address@hidden itemize
+
+
address@hidden Preparing for TeX
address@hidden Preparing for @TeX{}
address@hidden Preparing for @TeX{}
address@hidden @TeX{} input initialization
address@hidden @code{TEXINPUTS} environment variable
address@hidden TEXINPUTS
address@hidden @b{.profile} initialization file
address@hidden @b{.cshrc} initialization file
address@hidden Initialization file for @TeX{} input
+
address@hidden needs to know where to find the @file{texinfo.tex} file that the
address@hidden texinfo} command on the first line reads. The
address@hidden file tells @TeX{} how to handle @@-commands; it is
+included in all standard GNU distributions.
+
address@hidden address@hidden, installing}
+
+Usually, the installer has put the @file{texinfo.tex} file in the
+default directory that contains @TeX{} macros when GNU Texinfo, Emacs or
+other GNU software is installed. In this case, @TeX{} will find the
+file and you do not need to do anything special. If this has not been
+done, you can put @file{texinfo.tex} in the current directory when you
+run @TeX{}, and @TeX{} will find it there.
+
address@hidden address@hidden, installing}
+Also, you should install @file{epsf.tex}, if it is not already installed
+from another distribution. More details are at the end of the description
+of the @code{@@image} command (@pxref{Images}).
+
address@hidden address@hidden, installing}
+Likewise for @file{pdfcolor.tex}, if it is not already installed and you
+use pdftex.
+
address@hidden texinfo.cnf @r{installation}
address@hidden Customizing of @TeX{} for Texinfo
address@hidden Site-wide Texinfo configuration file
+Optionally, you may create an additional @file{texinfo.cnf}, and install
+it as well. This file is read by @TeX{} when the @code{@@setfilename}
+command is executed (@pxref{setfilename,, @code{@@setfilename}}). You can put
any
+commands you like there, according to local site-wide conventions. They
+will be read by @TeX{} when processing any Texinfo document. For
+example, if @file{texinfo.cnf} contains the line @samp{@@afourpaper}
+(@pxref{A4 Paper}), then all Texinfo documents will be processed with
+that page size in effect. If you have nothing to put in
address@hidden, you do not need to create it.
+
address@hidden TEXINPUTS
+If neither of the above locations for these system files suffice for
+you, you can specify the directories explicitly. For
address@hidden, you can do this by writing the complete path for the
+file after the @code{\input} command. Another way, that works for both
address@hidden and @file{texinfo.cnf} (and any other file @TeX{}
+might read), is to set the @code{TEXINPUTS} environment variable in your
address@hidden or @file{.profile} file.
+
+Which you use of @file{.cshrc} or @file{.profile} depends on
+whether you use a Bourne shell-compatible (@code{sh}, @code{bash},
address@hidden, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh})
+command interpreter. The latter read the @file{.cshrc} file for
+initialization information, and the former read @file{.profile}.
+
+In a @file{.cshrc} file, you could use the following @code{csh} command
+sequence:
+
address@hidden
+setenv TEXINPUTS .:/home/me/mylib:/usr/lib/tex/macros
address@hidden example
+
address@hidden 1000
+In a @file{.profile} file, you could use the following @code{sh} command
+sequence:
+
address@hidden
address@hidden
+TEXINPUTS=.:/home/me/mylib:/usr/lib/tex/macros
+export TEXINPUTS
address@hidden group
address@hidden example
+
+On MS-DOS/MS-Windows, you would say it like address@hidden the use
+of the @samp{;} character, instead of @samp{:}, as directory separator
+on these systems.}:
+
address@hidden
address@hidden
+set TEXINPUTS=.;d:/home/me/mylib;c:/usr/lib/tex/macros
address@hidden group
address@hidden example
+
address@hidden
+It is customary for DOS/Windows users to put such commands in the
address@hidden file, or in the Windows address@hidden
+
address@hidden
+These settings would cause @TeX{} to look for @file{\input} file first
+in the current directory, indicated by the @samp{.}, then in a
+hypothetical user's @file{me/mylib} directory, and finally in a system
+directory @file{/usr/lib/tex/macros}.
+
address@hidden Dumping a .fmt file
address@hidden Format file, dumping
+Finally, you may wish to dump a @file{.fmt} file (@pxref{Memory dumps,,,
+web2c, Web2c}) so that @TeX{} can load Texinfo faster. (The
+disadvantage is that then updating @file{texinfo.tex} requires
+redumping.) You can do this by running this command, assuming
address@hidden is findable by @TeX{}:
+
address@hidden
+initex texinfo @@dump
address@hidden example
+
+(@code{dump} is a @TeX{} primitive.) Then, move @file{texinfo.fmt} to
+wherever your @code{.fmt} files are found; typically, this will be in the
+subdirectory @file{web2c} of your @TeX{} installation.
+
+
address@hidden Overfull hboxes
address@hidden Overfull ``hboxes''
address@hidden Overfull @samp{hboxes}
address@hidden @samp{hboxes}, overfull
address@hidden Final output
+
address@hidden is sometimes unable to typeset a line without extending it into
+the right margin. This can occur when @TeX{} comes upon what it
+interprets as a long word that it cannot hyphenate, such as an
+electronic mail network address or a very long title. When this
+happens, @TeX{} prints an error message like this:
+
address@hidden
+Overfull @@hbox (20.76302pt too wide)
address@hidden example
+
address@hidden hbox
address@hidden
+(In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''.
address@hidden@@hbox} is a @TeX{} primitive not needed in the Texinfo language.)
+
address@hidden also provides the line number in the Texinfo source file and
+the text of the offending line, which is marked at all the places that
address@hidden considered hyphenation.
address@hidden with TeX, , Catching Errors with @TeX{} Formatting},
+for more information about typesetting errors.
+
+If the Texinfo file has an overfull hbox, you can rewrite the sentence
+so the overfull hbox does not occur, or you can decide to leave it. A
+small excursion into the right margin often does not matter and may not
+even be noticeable.
+
+If you have many overfull boxes and/or an antipathy to rewriting, you
+can coerce @TeX{} into greatly increasing the allowable interword
+spacing, thus (if you're lucky) avoiding many of the bad line breaks,
+like this:
+
address@hidden \emergencystretch
address@hidden
+@@tex
+\global\emergencystretch = .9\hsize
+@@end tex
address@hidden example
+
address@hidden
+(You should adjust the fraction as needed.) This huge value for
address@hidden cannot be the default, since then the typeset
+output would generally be of noticeably lower quality; the default
+is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension
+containing the current line width.
+
address@hidden Black rectangle in hardcopy
address@hidden Rectangle, black in hardcopy
address@hidden Box, ugly black in hardcopy
address@hidden Ugly black rectangles in hardcopy
+For what overfull boxes you have, however, @TeX{} will print a large,
+ugly, black rectangle beside the line that contains the overfull hbox
+unless told otherwise. This is so you will notice the location of the
+problem if you are correcting a draft.
+
address@hidden finalout
+To prevent such a monstrosity from marring your final printout, write
+the following in the beginning of the Texinfo file on a line of its own,
+before the @code{@@titlepage} command:
+
address@hidden
+@@finalout
address@hidden example
+
+
address@hidden smallbook
address@hidden Printing ``Small'' Books
address@hidden smallbook
address@hidden Small book size
address@hidden Book, printing small
address@hidden Page sizes for books
address@hidden Size of printed book
+
+By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch
+format. However, you can direct @TeX{} to typeset a document in a 7 by
+9.25 inch format that is suitable for bound books by inserting the
+following command on a line by itself at the beginning of the Texinfo
+file, before the title page:@refill
+
address@hidden
+@@smallbook
address@hidden example
+
address@hidden
+(Since many books are about 7 by 9.25 inches, this command might better
+have been called the @code{@@regularbooksize} command, but it came to be
+called the @code{@@smallbook} command by comparison to the 8.5 by 11 inch
format.)
+
+If you write the @code{@@smallbook} command between the
+start-of-header and end-of-header lines, the Texinfo mode @TeX{}
+region formatting command, @code{texinfo-tex-region}, will format the
+region in ``small'' book size (@pxref{Start of Header})address@hidden
+
address@hidden, for information about
+commands that make it easier to produce examples for a smaller manual.
+
address@hidden with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
address@hidden, for other ways to format with @code{@@smallbook} that do not
+require changing the source file.
+
+
address@hidden A4 Paper
address@hidden Printing on A4 Paper
address@hidden A4 paper, printing on
address@hidden A5 paper, printing on
address@hidden Paper size, A4
address@hidden European A4 paper
address@hidden afourpaper
+
+You can tell @TeX{} to format a document for printing on European size
+A4 paper (or A5) with the @code{@@afourpaper} (or @code{@@afivepaper})
+command. Write the command on a line by itself near the beginning of
+the Texinfo file, before the title page. For example, this is how you
+would write the header for this manual:
+
address@hidden
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename texinfo
+@@settitle Texinfo
+@@afourpaper
+@@c %**end of header
address@hidden group
address@hidden example
+
address@hidden with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
address@hidden, for other ways to format for different paper sizes that do not
+require changing the source file.
+
address@hidden afourlatex
address@hidden afourwide
+You may or may not prefer the formatting that results from the command
address@hidden@@afourlatex}. There's also @code{@@afourwide} for A4 paper in
+wide format.
+
address@hidden pagesizes
address@hidden @code{@@pagesizes} address@hidden, @var{height}]: Custom page
sizes
address@hidden pagesizes
address@hidden Custom page sizes
address@hidden Page sizes, customized
address@hidden Text width and height
address@hidden Width of text area
address@hidden Height of text area
address@hidden Depth of text area
+
+You can explicitly specify the height and (optionally) width of the main
+text area on the page with the @code{@@pagesizes} command. Write this
+on a line by itself near the beginning of the Texinfo file, before the
+title page. The height comes first, then the width if desired,
+separated by a comma. Examples:
+
address@hidden
+@@pagesizes 200mm,150mm @c for b5 paper
address@hidden example
address@hidden and
address@hidden
+@@pagesizes 11.5in @c for legal paper
address@hidden example
+
address@hidden B5 paper, printing on
address@hidden Legal paper, printing on
+This would be reasonable for printing on B5-size paper. To emphasize,
+this command specifies the size of the @emph{text area}, not the size of
+the paper (which is address@hidden by address@hidden for B5, address@hidden by
address@hidden for legal).
+
address@hidden Margins on page, not controllable
+To make more elaborate changes, such as changing any of the page
+margins, you must define a new command in @file{texinfo.tex} (or
address@hidden, @pxref{Preparing for TeX,,Preparing for @TeX{}}).
+
address@hidden with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
address@hidden, for other ways to specify @code{@@pagesizes} that do not
+require changing the source file.
+
address@hidden@@pagesizes} is ignored by @code{makeinfo}.
+
+
address@hidden Cropmarks and Magnification
address@hidden Cropmarks and Magnification
address@hidden cropmarks
address@hidden Cropmarks for printing
address@hidden Printing cropmarks
+You can (attempt to) direct @TeX{} to print cropmarks at the corners of
+pages with the @code{@@cropmarks} command. Write the @code{@@cropmarks}
+command on a line by itself between @code{@@iftex} and @code{@@end
+iftex} lines near the beginning of the Texinfo file, before the title
+page, like this:@refill
+
address@hidden
address@hidden
+@@iftex
+@@cropmarks
+@@end iftex
address@hidden group
address@hidden example
+
+This command is mainly for printers that typeset several pages on one
+sheet of film; but you can attempt to use it to mark the corners of a
+book set to 7 by 9.25 inches with the @code{@@smallbook} command.
+(Printers will not produce cropmarks for regular sized output that is
+printed on regular sized paper.) Since different printing machines work
+in different ways, you should explore the use of this command with a
+spirit of adventure. You may have to redefine the command in
address@hidden
+
address@hidden \mag @r{(raw @TeX{} magnification)}
address@hidden Magnified printing
address@hidden Larger or smaller pages
+You can attempt to direct @TeX{} to typeset pages larger or smaller than
+usual with the @code{\mag} @TeX{} command. Everything that is typeset
+is scaled proportionally larger or smaller. (@code{\mag} stands for
+``magnification''.) This is @emph{not} a Texinfo @@-command, but is a
+plain @TeX{} command that is prefixed with a backslash. You have to
+write this command between @code{@@tex} and @code{@@end tex}
+(@pxref{Raw Formatter Commands}).
+
+Follow the @code{\mag} command with an @samp{=} and then a number that
+is 1000 times the magnification you desire. For example, to print pages
+at 1.2 normal size, write the following near the beginning of the
+Texinfo file, before the title page:
+
address@hidden
address@hidden
+@@tex
+\mag=1200
+@@end tex
address@hidden group
address@hidden example
+
+With some printing technologies, you can print normal-sized copies that
+look better than usual by giving a larger-than-normal master to your
+print shop. They do the reduction, thus effectively increasing the
+resolution.
+
+Depending on your system, DVI files prepared with a
address@hidden may not print or may print only with certain
+magnifications. Be prepared to experiment.
+
+
address@hidden PDF Output
address@hidden PDF Output
address@hidden PDF output
+
address@hidden pdftex
+You can generate a PDF output file from Texinfo source by using the
address@hidden program to process your file instead of plain
address@hidden Just run @samp{pdftex foo.texi} instead of @samp{tex
+foo.texi}, or give the @samp{--pdf} option to @command{texi2dvi}.
+
address@hidden stands for `Portable Document Format'. It was invented by
+Adobe Systems some years ago for document interchange, based on their
+PostScript language. A @uref{http://www.foolabs.com/xpdf/, PDF reader}
+for the X window system is freely available, as is the
address@hidden://partners.adobe.com/asn/developer/technotes/, definition of
+the file format}. Since PDF is a binary format, there are no
address@hidden@@ifpdf} or @samp{@@pdf} commands as with the other output
+formats.
+
+Despite the `portable' in the name, PDF files are nowhere near as
+portable in practice as the plain ASCII formats (Info, HTML) that
+Texinfo supports (DVI portability is arguable). They also tend to be
+much larger and do not support the bitmap fonts used by @TeX{} (by
+default) very well. Nevertheless, a PDF file does preserve an actual
+printed document on a screen as faithfully as possible, so it has its place.
+
+PDF support in Texinfo is fairly rudimentary.
+
+
address@hidden Creating and Installing Info Files
address@hidden Creating and Installing Info Files
+
+This chapter describes how to create and install Info files. @xref{Info
+Files}, for general information about the file format itself.
+
address@hidden
+* Creating an Info File::
+* Installing an Info File::
address@hidden menu
+
+
address@hidden Creating an Info File
address@hidden Creating an Info File
address@hidden Creating an Info file
address@hidden Info, creating an online file
address@hidden Formatting a file for Info
+
address@hidden is a program that converts a Texinfo file into an Info
+file, HTML file, or plain text. @code{texinfo-format-region} and
address@hidden are GNU Emacs functions that convert
+Texinfo to Info.
+
+For information on installing the Info file in the Info system,
address@hidden an Info File}.
+
address@hidden
+* makeinfo advantages:: @code{makeinfo} provides better error checking.
+* Invoking makeinfo:: How to run @code{makeinfo} from a shell.
+* makeinfo options:: Specify fill-column and other options.
+* Pointer Validation:: How to check that pointers point somewhere.
+* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs.
+* 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.
+* makeinfo html:: Generating HTML output.
address@hidden menu
+
+
address@hidden makeinfo advantages
address@hidden @code{makeinfo} Preferred
+
+The @code{makeinfo} utility creates an Info file from a Texinfo source
+file more quickly than either of the Emacs formatting commands and
+provides better error messages. We recommend it. @code{makeinfo} is a
+C program that is independent of Emacs. You do not need to run Emacs to
+use @code{makeinfo}, which means you can use @code{makeinfo} on machines
+that are too small to run Emacs. You can run @code{makeinfo} in any one
+of three ways: from an operating system shell, from a shell inside
+Emacs, or by typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b}
+command in Texinfo mode in Emacs.
address@hidden
+
+The @code{texinfo-format-region} and the @code{texinfo-format-buffer}
+commands are useful if you cannot run @code{makeinfo}. Also, in some
+circumstances, they format short regions or buffers more quickly than
address@hidden@refill
+
address@hidden Invoking makeinfo
address@hidden Running @code{makeinfo} from a Shell
+
+To create an Info file from a Texinfo file, type @code{makeinfo}
+followed by the name of the Texinfo file. Thus, to create the Info
+file for Bison, type the following to the shell:
+
address@hidden
+makeinfo bison.texinfo
address@hidden example
+
+(You can run a shell inside Emacs by typing @kbd{M-x shell}.)@refill
+
+Sometimes you will want to specify options. For example, if you wish
+to discover which version of @code{makeinfo} you are using,
+type:@refill
+
address@hidden
+makeinfo --version
address@hidden example
+
address@hidden options}, for more information.
+
+
address@hidden makeinfo options
address@hidden Options for @code{makeinfo}
address@hidden @code{makeinfo} options
address@hidden Options for @code{makeinfo}
+
+The @code{makeinfo} command takes a number of options. Most often,
+options are used to set the value of the fill column and specify the
+footnote style. Each command line option is a word preceded by
address@hidden or a letter preceded by @samp{-}. You can use abbreviations
+for the long option names as long as they are address@hidden
+
+For example, you could use the following shell command to create an Info
+file for @file{bison.texinfo} in which each line is filled to only 68
+columns:@refill
+
address@hidden
+makeinfo --fill-column=68 bison.texinfo
address@hidden example
+
+You can write two or more options in sequence, like this:@refill
+
address@hidden
+makeinfo --no-split --fill-column=70 @dots{}
address@hidden example
+
address@hidden
+This would keep the Info file together as one possibly very long
+file and would also set the fill column to address@hidden
+
+The options are:
+
address@hidden @code
+
address@hidden -D @var{var}
address@hidden -D @var{var}
+Cause the variable @var{var} to be defined. This is equivalent to
address@hidden@@set @var{var}} in the Texinfo file (@pxref{set clear value}).
+
address@hidden --commands-in-node-names
address@hidden --commands-in-node-names
+Allow @code{@@}-commands in node names. This is not recommended, as it
+can probably never be implemented in @TeX{}. It also makes
address@hidden much slower. Also, this option is ignored when
address@hidden is used. @xref{Pointer Validation}, for more
+details.
+
address@hidden --docbook
address@hidden --docbook
+Generate DocBook output rather than Info.
+
address@hidden address@hidden
address@hidden -e @var{limit}
address@hidden address@hidden
address@hidden -e @var{limit}
+Set the maximum number of errors that @code{makeinfo} will report
+before exiting (on the assumption that continuing would be useless);
+default 100.
+
address@hidden address@hidden
address@hidden -f @var{width}
address@hidden address@hidden
address@hidden -f @var{width}
+Specify the maximum number of columns in a line; this is the right-hand
+edge of a line. Paragraphs that are filled will be filled to this
+width. (Filling is the process of breaking up and connecting lines so
+that lines are the same length as or shorter than the number specified
+as the fill column. Lines are broken between words.) The default value
+is 72. Ignored with @samp{--html}.
+
address@hidden address@hidden
address@hidden -s @var{style}
address@hidden address@hidden
address@hidden -s @var{style}
+Set the footnote style to @var{style}, either @samp{end} for the end
+node style (the default) or @samp{separate} for the separate node style.
+The value set by this option overrides the value set in a Texinfo file
+by an @code{@@footnotestyle} command (@pxref{Footnotes}). When the
+footnote style is @samp{separate}, @code{makeinfo} makes a new node
+containing the footnotes found in the current node. When the footnote
+style is @samp{end}, @code{makeinfo} places the footnote references at
+the end of the current node. Ignored with @samp{--html}.
+
address@hidden --force
address@hidden -F
address@hidden --force
address@hidden -F
+Ordinarily, if the input file has errors, the output files are not
+created. With this option, they are preserved.
+
address@hidden --help
address@hidden -h
address@hidden --help
address@hidden -h
+Print a usage message listing all available options, then exit successfully.
+
address@hidden --html
address@hidden --html
+Generate HTML output rather than Info. @xref{makeinfo html}. By
+default, the HTML output is split into one output file per source node,
+and the split output is written into a subdirectory with the name of the
+top-level info file.
+
address@hidden -I @var{dir}
address@hidden -I @var{dir}
+Append @var{dir} to the directory search list for finding files that
+are included using the @code{@@include} command. By default,
address@hidden searches only the current directory. If @var{dir} is
+not given, the current directory @file{.} is appended. Note that
address@hidden can actually be a list of several directories separated by the
+usual path separator character (@samp{:} on Unix, @samp{;} on
+MS-DOS/MS-Windows).
+
address@hidden address@hidden
address@hidden -E @var{file}
+Output the Texinfo source with all the macros expanded to the named
+file. Normally, the results of macro expansion are used internally by
address@hidden and then discarded. This option is used by
address@hidden if you are using an old version of @file{texinfo.tex}
+that does not support @code{@@macro}.
+
address@hidden --no-headers
address@hidden --no-headers
address@hidden Plain text output
address@hidden ASCII text output
address@hidden Generating plain text files
address@hidden @file{INSTALL} file, generating
address@hidden Node separators, omitting
address@hidden Menus, omitting
+For Info output, do not include menus or node separator lines in the
+output. This results in a simple plain text file that you can (for
+example) send in email without complications, or include in a
+distribution (as in an @file{INSTALL} file).
+
address@hidden Navigation links, omitting
+For HTML output, likewise omit menus. And if @samp{--no-split} is also
+specified, do not include a navigation links at the top of each node
+(these are never included in the default case of split output).
address@hidden html}.
+
+In both cases, write to standard output by default (can still be
+overridden by @option{-o}).
+
address@hidden --no-split
address@hidden --no-split
address@hidden Splitting of output files
address@hidden Output file splitting
+Suppress the splitting stage of @code{makeinfo}. By default, large
+output files (where the size is greater than 70k bytes) are split into
+smaller subfiles. For Info output, each one is approximately 50k bytes.
+For HTML output, each file contains one node (@pxref{makeinfo html}).
+
address@hidden --no-pointer-validate
address@hidden --no-validate
address@hidden --no-pointer-validate
address@hidden --no-validate
address@hidden Pointer validation, suppressing
+Suppress the pointer-validation phase of @code{makeinfo}. This can also
+be done with the @code{@@novalidate} command (@pxref{Use TeX,,Use
address@hidden). Normally, after a Texinfo file is processed, some consistency
+checks are made to ensure that cross references can be resolved, etc.
address@hidden Validation}.
+
address@hidden --no-warn
address@hidden --no-warn
+Suppress warning messages (but @emph{not} error messages). You might
+want this if the file you are creating has examples of Texinfo cross
+references within it, and the nodes that are referenced do not actually
+exist.
+
address@hidden --number-sections
address@hidden --number-sections
+Output chapter, section, and appendix numbers as in printed manuals.
+
address@hidden --no-number-footnotes
address@hidden --no-number-footnotes
+Suppress automatic footnote numbering. By default, @code{makeinfo}
+numbers each footnote sequentially in a single node, resetting the
+current footnote number to 1 at the start of each node.
+
address@hidden address@hidden
address@hidden -o @var{file}
address@hidden address@hidden
address@hidden -o @var{file}
+Specify that the output should be directed to @var{file} and not to the
+file name specified in the @code{@@setfilename} command found in the
+Texinfo source (@pxref{setfilename}). If @var{file} is @samp{-}, output
+goes to standard output and @samp{--no-split} is implied. For split
+HTML output, @var{file} is the name for the directory into which all
+HTML nodes are written (@pxref{makeinfo html}).
+
address@hidden -P @var{dir}
address@hidden -P @var{dir}
+Prepend @var{dir} to the directory search list for @code{@@include}.
+If @var{dir} is not given, the current directory @file{.} is prepended.
+See @samp{-I} for more details.
+
address@hidden address@hidden
address@hidden -p @var{indent}
address@hidden address@hidden
address@hidden -p @var{indent}
+Set the paragraph indentation style to @var{indent}. The value set by
+this option overrides the value set in a Texinfo file by an
address@hidden@@paragraphindent} command (@pxref{paragraphindent}). The value
+of @var{indent} is interpreted as follows:
+
address@hidden @asis
address@hidden @samp{asis}
+Preserve any existing indentation at the starts of paragraphs.
+
address@hidden @samp{0} or @samp{none}
+Delete any existing indentation.
+
address@hidden @var{num}
+Indent each paragraph by @var{num} spaces.
address@hidden table
+
address@hidden address@hidden
address@hidden -r @var{limit}
address@hidden address@hidden
address@hidden -r @var{limit}
+Set the value of the number of references to a node that
address@hidden will make without reporting a warning. If a node has more
+than this number of references in it, @code{makeinfo} will make the
+references but also report a warning. The default is 1000.
+
address@hidden -U @var{var}
+Cause @var{var} to be undefined. This is equivalent to
address@hidden@@clear @var{var}} in the Texinfo file (@pxref{set clear value}).
+
address@hidden --verbose
address@hidden --verbose
+Cause @code{makeinfo} to display messages saying what it is doing.
+Normally, @code{makeinfo} only outputs messages if there are errors or
+warnings.
+
address@hidden --version
address@hidden -V
address@hidden --version
address@hidden -V
+Print the version number, then exit successfully.
+
address@hidden --xml
address@hidden --xml
+Generate XML output rather than Info.
+
address@hidden table
+
+
address@hidden Pointer Validation
address@hidden Pointer Validation
address@hidden Pointer validation with @code{makeinfo}
address@hidden Validation of pointers
+
+If you do not suppress pointer validation with the @samp{--no-validate}
+option or the @code{@@novalidate} command in the source file (@pxref{Use
+TeX,,Use @TeX{}}), @code{makeinfo} will check the validity of the final
+Info file. Mostly, this means ensuring that nodes you have referenced
+really exist. Here is a complete list of what is checked:
+
address@hidden
address@hidden
+If a `Next', `Previous', or `Up' node reference is a reference to a
+node in the current file and is not an external reference such as to
address@hidden(dir)}, then the referenced node must address@hidden
+
address@hidden
+In every node, if the `Previous' node is different from the `Up' node,
+then the node pointed to by the `Previous' field must have a `Next'
+field which points back to this address@hidden
+
address@hidden
+Every node except the `Top' node must have an `Up' address@hidden
+
address@hidden
+The node referenced by an `Up' pointer must itself reference the current
+node through a menu item, unless the node referenced by `Up'
+has the form `(@var{file})'.
+
address@hidden
+If the `Next' reference of a node is not the same as the `Next' reference
+of the `Up' reference, then the node referenced by the `Next' pointer
+must have a `Previous' pointer that points back to the current node.
+This rule allows the last node in a section to point to the first node
+of the next address@hidden
+
address@hidden
+Every node except `Top' should be referenced by at least one other node,
+either via the `Previous' or `Next' links, or via a menu or a
address@hidden
address@hidden enumerate
+
address@hidden @@-commands in @@node, limited support
+Some Texinfo documents might fail during the validation phase because
+they use commands like @code{@@value} and @code{@@definfoenclose} in
+node definitions and cross-references inconsistently. Consider the
+following example:
+
address@hidden
address@hidden
+@@set nodename Node 1
+
+@@node @@address@hidden@}, Node 2, Top, Top
+
+This is node 1.
+
+@@node Node 2, , Node 1, Top
+
+This is node 2.
address@hidden group
address@hidden example
+
address@hidden
+Here, the node ``Node 1'' was referenced both verbatim and through
address@hidden@@value}.
+
+By default, @code{makeinfo} fails such cases, because node names are not
+fully expanded until they are written to the output file. You should
+always try to reference nodes consistently; e.g., in the above example,
+the second @code{@@node} line should have also used @code{@@value}.
+However, if, for some reason, you @emph{must} reference node names
+inconsistently, and @code{makeinfo} fails to validate the file, you can
+use the @samp{--commands-in-node-names} option to force @code{makeinfo}
+to perform the expensive expansion of all node names it finds in the
+document. This might considerably slow down the program, though;
+twofold increase in conversion time was measured for large documents
+such as the Jargon file.
+
address@hidden @@value in @@node lines
+The support for @code{@@}-commands in @code{@@node} directives is not
+general enough to be freely used. For example, if the example above
+redefined @code{nodename} somewhere in the document, @code{makeinfo}
+will fail to convert it, even if invoked with the
address@hidden option.
+
address@hidden has no effect if the @samp{--no-validate}
+option is given.
+
+
address@hidden makeinfo in Emacs
address@hidden Running @code{makeinfo} inside Emacs
address@hidden Running @code{makeinfo} in Emacs
address@hidden @code{makeinfo} inside Emacs
address@hidden Shell, running @code{makeinfo} in
+
+You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the
address@hidden or the @code{makeinfo-buffer} commands. In
+Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c
+C-m C-b} by address@hidden
+
address@hidden @kbd
address@hidden C-c C-m C-r
address@hidden M-x makeinfo-region
+Format the current region for address@hidden
address@hidden makeinfo-region
+
address@hidden C-c C-m C-b
address@hidden M-x makeinfo-buffer
+Format the current buffer for address@hidden
address@hidden makeinfo-buffer
address@hidden table
+
+When you invoke either @code{makeinfo-region} or
address@hidden, Emacs prompts for a file name, offering the
+name of the visited file as the default. You can edit the default
+file name in the minibuffer if you wish, before pressing @key{RET} to
+start the @code{makeinfo} address@hidden
+
+The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands
+run the @code{makeinfo} program in a temporary shell buffer. If
address@hidden finds any errors, Emacs displays the error messages in
+the temporary address@hidden
+
address@hidden Errors, parsing
address@hidden Parsing errors
address@hidden next-error
+You can parse the error messages by typing @kbd{C-x `}
+(@code{next-error}). This causes Emacs to go to and position the
+cursor on the line in the Texinfo source that @code{makeinfo} thinks
+caused the error. @xref{Compilation, , Running @code{make} or
+Compilers Generally, emacs, The GNU Emacs Manual}, for more
+information about using the @code{next-error} address@hidden
+
+In addition, you can kill the shell in which the @code{makeinfo}
+command is running or make the shell buffer display its most recent
address@hidden
+
address@hidden @kbd
address@hidden C-c C-m C-k
address@hidden M-x makeinfo-kill-job
address@hidden makeinfo-kill-job
+Kill the current running @code{makeinfo} job
+(from @code{makeinfo-region} or @code{makeinfo-buffer})address@hidden
+
address@hidden C-c C-m C-l
address@hidden M-x makeinfo-recenter-output-buffer
address@hidden makeinfo-recenter-output-buffer
+Redisplay the @code{makeinfo} shell buffer to display its most recent
address@hidden
address@hidden table
+
address@hidden
+(Note that the parallel commands for killing and recentering a @TeX{}
+job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode
+Printing}.)@refill
+
+You can specify options for @code{makeinfo} by setting the
address@hidden variable with either the @kbd{M-x
+edit-options} or the @kbd{M-x set-variable} command, or by setting the
+variable in your @file{.emacs} initialization address@hidden
+
+For example, you could write the following in your @file{.emacs} file:@refill
+
address@hidden
address@hidden
+(setq makeinfo-options
+ "--paragraph-indent=0 --no-split
+ --fill-column=70 --verbose")
address@hidden group
address@hidden example
+
address@hidden If you write these three cross references using xref, you see
address@hidden three references to the same named manual, which looks strange.
address@hidden
+For more information, address@hidden
address@hidden Options, , Editing Variable Values, emacs, The GNU Emacs
Manual},@*
address@hidden, , Examining and Setting Variables, emacs, The GNU Emacs
Manual},@*
address@hidden File, , , emacs, The GNU Emacs Manual}, address@hidden
address@hidden options, , Options for @code{makeinfo}}.
+
address@hidden texinfo-format commands
address@hidden node-name, next, previous, up
address@hidden The @address@hidden Commands
address@hidden texinfo-format-region
address@hidden texinfo-format-buffer
+
+In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
+file with the @code{texinfo-format-region} command. This formats the
+current region and displays the formatted text in a temporary buffer
+called @samp{*Info address@hidden
+
+Similarly, you can format a buffer with the
address@hidden command. This command creates a new
+buffer and generates the Info file in it. Typing @kbd{C-x C-s} will
+save the Info file under the name specified by the
address@hidden@@setfilename} line which must be near the beginning of the
+Texinfo address@hidden
+
address@hidden @kbd
address@hidden C-c C-e C-r
address@hidden @code{texinfo-format-region}
+Format the current region for Info.
address@hidden texinfo-format-region
+
address@hidden C-c C-e C-b
address@hidden @code{texinfo-format-buffer}
+Format the current buffer for Info.
address@hidden texinfo-format-buffer
address@hidden table
+
+The @code{texinfo-format-region} and @code{texinfo-format-buffer}
+commands provide you with some error checking, and other functions can
+provide you with further help in finding formatting errors. These
+procedures are described in an appendix; see @ref{Catching Mistakes}.
+However, the @code{makeinfo} program is often faster and
+provides better error checking (@pxref{makeinfo in Emacs})address@hidden
+
address@hidden Batch Formatting
address@hidden node-name, next, previous, up
address@hidden Batch Formatting
address@hidden Batch formatting for Info
address@hidden Info batch formatting
+
+You can format Texinfo files for Info using @code{batch-texinfo-format}
+and Emacs Batch mode. You can run Emacs in Batch mode from any shell,
+including a shell inside of Emacs. (@xref{Command Switches, , Command
+Line Switches and Arguments, emacs, The GNU Emacs Manual}.)@refill
+
+Here is a shell command to format all the files that end in
address@hidden in the current directory:
+
address@hidden
+emacs -batch -funcall batch-texinfo-format *.texinfo
address@hidden example
+
address@hidden
+Emacs processes all the files listed on the command line, even if an
+error occurs while attempting to format some of address@hidden
+
+Run @code{batch-texinfo-format} only with Emacs in Batch mode as shown;
+it is not interactive. It kills the Batch mode Emacs on address@hidden
+
address@hidden is convenient if you lack @code{makeinfo}
+and want to format several Texinfo files at once. When you use Batch
+mode, you create a new Emacs process. This frees your current Emacs, so
+you can continue working in it. (When you run
address@hidden or @code{texinfo-format-buffer}, you cannot
+use that Emacs for anything else until the command finishes.)@refill
+
address@hidden Tag and Split Files
address@hidden node-name, next, previous, up
address@hidden Tag Files and Split Files
address@hidden Making a tag table automatically
address@hidden Tag table, making automatically
+
+If a Texinfo file has more than 30,000 bytes,
address@hidden automatically creates a tag table
+for its Info file; @code{makeinfo} always creates a tag table. With
+a @dfn{tag table}, Info can jump to new nodes more quickly than it can
address@hidden
+
address@hidden Indirect subfiles
+In addition, if the Texinfo file contains more than about 70,000
+bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the
+large Info file into shorter @dfn{indirect} subfiles of about 50,000
+bytes each. Big files are split into smaller files so that Emacs does
+not need to make a large buffer to hold the whole of a large Info
+file; instead, Emacs allocates just enough memory for the small, split-off
+file that is needed at the time. This way, Emacs avoids wasting
+memory when you run Info. (Before splitting was implemented, Info
+files were always kept short and @dfn{include files} were designed as
+a way to create a single, large printed manual out of the smaller Info
+files. @xref{Include Files}, for more information. Include files are
+still used for very large documents, such as @cite{The Emacs Lisp
+Reference Manual}, in which each chapter is a separate file.)@refill
+
+When a file is split, Info itself makes use of a shortened version of
+the original file that contains just the tag table and references to
+the files that were split off. The split-off files are called
address@hidden address@hidden
+
+The split-off files have names that are created by appending @address@hidden,
address@hidden@samp{-2}}, @address@hidden and so on to the file name specified
by the
address@hidden@@setfilename} command. The shortened version of the original
file
+continues to have the name specified by @code{@@address@hidden
+
+At one stage in writing this document, for example, the Info file was saved
+as the file @file{test-texinfo} and that file looked like this:@refill
+
address@hidden
address@hidden
+Info file: test-texinfo, -*-Text-*-
+produced by texinfo-format-buffer
+from file: new-texinfo-manual.texinfo
+
+^_
+Indirect:
+test-texinfo-1: 102
+test-texinfo-2: 50422
address@hidden group
address@hidden
+test-texinfo-3: 101300
+^_^L
+Tag table:
+(Indirect)
+Node: overview^?104
+Node: info file^?1271
address@hidden group
address@hidden
+Node: printed manual^?4853
+Node: conventions^?6855
address@hidden
address@hidden group
address@hidden example
+
address@hidden
+(But @file{test-texinfo} had far more nodes than are shown here.) Each of
+the split-off, indirect files, @file{test-texinfo-1},
address@hidden, and @file{test-texinfo-3}, is listed in this file
+after the line that says @samp{Indirect:}. The tag table is listed after
+the line that says @samp{Tag table:}. @refill
+
+In the list of indirect files, the number following the file name
+records the cumulative number of bytes in the preceding indirect files,
+not counting the file list itself, the tag table, or the permissions
+text in each file. In the tag table, the number following the node name
+records the location of the beginning of the node, in bytes from the
+beginning of the (unsplit) output.
+
+If you are using @code{texinfo-format-buffer} to create Info files,
+you may want to run the @code{Info-validate} command. (The
address@hidden command does such a good job on its own, you do not
+need @code{Info-validate}.) However, you cannot run the @kbd{M-x
+Info-validate} node-checking command on indirect files. For
+information on how to prevent files from being split and how to
+validate the structure of the nodes, see @ref{Using
address@hidden
+
+
address@hidden makeinfo html
address@hidden Generating HTML
address@hidden HTML
+
+Besides generating output in the Info format, you can use the
address@hidden option to generate output in HTML format, for installation
+on a web site (for example). By default, the HTML output is split at
+node level.
+
+When splitting, the HTML output files are written into a subdirectory.
+The subdirectory is named according to the name from
address@hidden@@setfilename} with any extension removed; for example, HTML
+output for @code{@@setfilename emacs.info} would be written into a
+subdirectory named @samp{emacs}. If that directory cannot be created
+for any reason, then @samp{.html} is appended to the directory name, as
+in @samp{emacs.html} (this is necessary because sometimes the info file
+is named without an extension, e.g., @samp{texinfo}). If the
address@hidden@var{name}.html} directory can't be created either,
address@hidden gives up. In any case, the top-level output file within
+the directory is always named @samp{index.html}.
+
+Monolithic output (@code{--no-split}) is named according to
address@hidden@@setfilename} or @code{--outfile}. Cross-document node
+references are not supported in monolithic HTML.
+
+Texinfo input marked up with the @code{@@ifhtml} command will produce
+output only with the @samp{--html} option supplied. Input marked up
+with the @code{@@html} is passed literally to the output (suppressing
+the normal escaping of input @samp{<}, @samp{>} and @samp{&} characters
+which have special significance in HTML).
+
+The @samp{--footnote-style} option is currently ignored for HTML output;
+footnotes are linked to the end of the output file.
+
+The HTML generated is mostly standard (i.e., HTML 2.0, RFC-1866). The
+exception is that HTML 3.2 tables are generated from the
address@hidden@@multitable} command, but tagged to degrade as well as possible
+in browsers without table support. The HTML 4 @samp{lang} attribute on
+the @samp{<html>} attribute is also used. Please report output from an
+error-free run of @code{makeinfo} which has browser portability problems
+as a bug.
+
+Navigation bars are inserted at the start of nodes, similarly to Info
+output. The @samp{--no-headers} option will suppress this if used with
address@hidden Header @code{<link>} elements in split output can
+support info-like navigation with browsers like Lynx and @w{Emacs W3}
+which implement this @w{HTML 1.0} feature. @samp{@@xref} commands to
+other documents are generated assuming the other document is available
+in split HTML form, and installed in the same HTML documentation tree,
+at @file{../<info-document>/}.
+
+
address@hidden Installing an Info File
address@hidden Installing an Info File
address@hidden Installing an Info file
address@hidden Info file installation
address@hidden @file{dir} directory for Info installation
+
+Info files are usually kept in the @file{info} directory. You can read
+Info files using the standalone Info program or the Info reader built
+into Emacs. (@inforef{Top, info, info}, for an introduction to Info.)
+
address@hidden
+* 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 install-info:: @code{install-info} options.
address@hidden menu
+
+
address@hidden Directory File
address@hidden The Directory File @file{dir}
+
+For Info to work, the @file{info} directory must contain a file that
+serves as a top level directory for the Info system. By convention,
+this file is called @file{dir}. (You can find the location of this file
+within Emacs by typing @kbd{C-h i} to enter Info and then typing
address@hidden C-f} to see the pathname to the @file{info} directory.)
+
+The @file{dir} file is itself an Info file. It contains the top level
+menu for all the Info files in the system. The menu looks like
+this:@refill
+
address@hidden
address@hidden
+* Menu:
+* Info: (info). Documentation browsing system.
+* Emacs: (emacs). The extensible, self-documenting
+ text editor.
+* Texinfo: (texinfo). With one source file, make
+ either a printed manual using
+ @@address@hidden@} or an Info file.
address@hidden
address@hidden group
address@hidden example
+
+Each of these menu entries points to the `Top' node of the Info file
+that is named in parentheses. (The menu entry does not need to
+specify the `Top' node, since Info goes to the `Top' node if no node
+name is mentioned. @xref{Other Info Files, , Nodes in Other Info
+Files}.)@refill
+
+Thus, the @samp{Info} entry points to the `Top' node of the
address@hidden file and the @samp{Emacs} entry points to the `Top' node
+of the @file{emacs} address@hidden
+
+In each of the Info files, the `Up' pointer of the `Top' node refers
+back to the @code{dir} file. For example, the line for the `Top'
+node of the Emacs manual looks like this in Info:@refill
+
address@hidden
+File: emacs Node: Top, Up: (DIR), Next: Distrib
address@hidden example
+
address@hidden
+In this case, the @file{dir} file name is written in upper case
+letters---it can be written in either upper or lower case. This is not
+true in general, it is a special case for @file{dir}.
+
+
address@hidden New Info File
address@hidden Listing a New Info File
address@hidden Adding a new Info file
address@hidden Listing a new Info file
address@hidden New Info file, listing it in @file{dir} file
address@hidden Info file, listing a new
address@hidden @file{dir} file listing
+
+To add a new Info file to your system, you must write a menu entry to
+add to the menu in the @file{dir} file in the @file{info} directory.
+For example, if you were adding documentation for GDB, you would write
+the following new entry:@refill
+
address@hidden
+* GDB: (gdb). The source-level C debugger.
address@hidden example
+
address@hidden
+The first part of the menu entry is the menu entry name, followed by a
+colon. The second part is the name of the Info file, in parentheses,
+followed by a period. The third part is the description.
+
+The name of an Info file often has a @file{.info} extension. Thus, the
+Info file for GDB might be called either @file{gdb} or @file{gdb.info}.
+The Info reader programs automatically try the file name both with and
+without @address@hidden MS-DOS/MS-Windows systems, Info will
+try the @file{.inf} extension as well.}; so it is better to avoid
+clutter and not to write @samp{.info} explicitly in the menu entry. For
+example, the GDB menu entry should use just @samp{gdb} for the file
+name, not @samp{gdb.info}.
+
+
address@hidden Other Info Directories
address@hidden Info Files in Other Directories
address@hidden Installing Info in another directory
address@hidden Info installed in another directory
address@hidden Another Info directory
address@hidden @file{dir} files and Info directories
+
+If an Info file is not in the @file{info} directory, there are three
+ways to specify its location:@refill
+
address@hidden
address@hidden
+Write the pathname in the @file{dir} file as the second part of the menu.
+
address@hidden
+If you are using Emacs, list the name of the file in a second @file{dir}
+file, in its directory; and then add the name of that directory to the
address@hidden variable in your personal or site
+initialization file.
+
+This variable tells Emacs where to look for @file{dir} files (the files
+must be named @file{dir}). Emacs merges the files named @file{dir} from
+each of the listed directories. (In Emacs version 18, you can set the
address@hidden variable to the name of only one
+directory.)@refill
+
address@hidden
+Specify the Info directory name in the @code{INFOPATH} environment
+variable in your @file{.profile} or @file{.cshrc} initialization file.
+(Only you and others who set this environment variable will be able to
+find Info files whose location is specified this way.)
address@hidden enumerate
+
+For example, to reach a test file in the @file{/home/bob/info}
+directory, you could add an entry like this to the menu in the
+standard @file{dir} file:@refill
+
address@hidden
+* Test: (/home/bob/info/info-test). Bob's own test file.
address@hidden example
+
address@hidden
+In this case, the absolute file name of the @file{info-test} file is
+written as the second part of the menu address@hidden
+
+Alternatively, you could write the following in your @file{.emacs} file:
+
address@hidden Info-directory-list
address@hidden
address@hidden
+(require 'info)
+(setq Info-directory-list
+ (cons (expand-file-name "/home/bob/info")
+ Info-directory-list))
address@hidden group
address@hidden example
+
+This tells Emacs to merge the system @file{dir} file with the @file{dir}
+file in @file{/home/bob/info}. Thus, Info will list the
address@hidden/home/bob/info/info-test} file as a menu entry in the
address@hidden/home/bob/info/dir} file. Emacs does the merging only when
address@hidden info} is first run, so if you want to set
address@hidden in an Emacs session where you've already run
address@hidden, you must @code{(setq Info-dir-contents nil)} to force Emacs
+to recompose the @file{dir} file.
+
address@hidden INFOPATH
+Finally, you can tell Info where to look by setting the @code{INFOPATH}
+environment variable in your shell startup file, such as @file{.cshrc},
address@hidden or @file{autoexec.bat}. If you use a Bourne-compatible
+shell such as @code{sh} or @code{bash} for your shell command
+interpreter, you set the @code{INFOPATH} environment variable in the
address@hidden initialization file; but if you use @code{csh} or
address@hidden, you set the variable in the @file{.cshrc} initialization
+file. On MS-DOS/MS-Windows systems, you must set @code{INFOPATH} in
+your @file{autoexec.bat} file or in the Registry. Each type of shell
+uses a different syntax.
+
address@hidden @bullet
address@hidden
+In a @file{.cshrc} file, you could set the @code{INFOPATH}
+variable as follows:@refill
+
address@hidden
+setenv INFOPATH .:~/info:/usr/local/emacs/info
address@hidden smallexample
+
address@hidden
+In a @file{.profile} file, you would achieve the same effect by
+writing:@refill
+
address@hidden
+INFOPATH=.:$HOME/info:/usr/local/emacs/info
+export INFOPATH
address@hidden smallexample
+
address@hidden
address@hidden autoexec.bat
+In a @file{autoexec.bat} file, you write this address@hidden the
+use of @samp{;} as the directory separator, and a different syntax for
+using values of other environment variables.}:
+
address@hidden
+set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info
address@hidden smallexample
address@hidden itemize
+
address@hidden
+The @samp{.} indicates the current directory as usual. Emacs uses the
address@hidden environment variable to initialize the value of Emacs's
+own @code{Info-directory-list} variable. The stand-alone Info reader
+merges any files named @file{dir} in any directory listed in the
address@hidden variable into a single menu presented to you in the node
+called @samp{(dir)Top}.
+
address@hidden colon, last in @env{INFOPATH}
+However you set @env{INFOPATH}, if its last character is a
address@hidden MS-DOS/MS-Windows systems, use semi-colon instead.}, this
+is replaced by the default (compiled-in) path. This gives you a way to
+augment the default path with new directories without having to list all
+the standard places. For example (using @code{sh} syntax):
+
address@hidden
+INFOPATH=/local/info:
+export INFOPATH
address@hidden example
+
address@hidden
+will search @file{/local/info} first, then the standard directories.
+Leading or doubled colons are not treated specially.
+
address@hidden @file{dir} file, creating your own
+When you create your own @file{dir} file for use with
address@hidden or @env{INFOPATH}, it's easiest to start by
+copying an existing @file{dir} file and replace all the text after the
address@hidden Menu:} with your desired entries. That way, the punctuation and
+special CTRL-_ characters that Info needs will be present.
+
+
address@hidden Installing Dir Entries
address@hidden Installing Info Directory Files
+
+When you install an Info file onto your system, you can use the program
address@hidden to update the Info directory file @file{dir}.
+Normally the makefile for the package runs @code{install-info}, just
+after copying the Info file into its proper installed location.
+
address@hidden dircategory
address@hidden direntry
+In order for the Info file to work with @code{install-info}, you include
+the commands @code{@@dircategory} and
address@hidden@@address@hidden@code{@@end direntry} in the Texinfo source
+file. Use @code{@@direntry} to specify the menu entries to add to the
+Info directory file, and use @code{@@dircategory} to specify which part
+of the Info directory to put it in. Here is how these commands are used
+in this manual:
+
address@hidden
+@@dircategory Texinfo documentation system
+@@direntry
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. @dots{}
address@hidden
+@@end direntry
address@hidden smallexample
+
+Here's what this produces in the Info file:
+
address@hidden
+INFO-DIR-SECTION Texinfo documentation system
+START-INFO-DIR-ENTRY
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. @dots{}
address@hidden
+END-INFO-DIR-ENTRY
address@hidden smallexample
+
address@hidden
+The @code{install-info} program sees these lines in the Info file, and
+that is how it knows what to do.
+
+Always use the @code{@@direntry} and @code{@@dircategory} commands near
+the beginning of the Texinfo input, before the first @code{@@node}
+command. If you use them later on in the input, @code{install-info}
+will not notice them.
+
+If you use @code{@@dircategory} more than once in the Texinfo source,
+each usage specifies the `current' category; any subsequent
address@hidden@@direntry} commands will add to that category.
+
+Here are some recommended @code{@@dircategory} categories:
+
address@hidden
+GNU packages
+GNU programming tools
+GNU programming documentation
+GNU Emacs Lisp
+GNU libraries
+TeX
+Individual utilities
address@hidden display
+
+The idea is to include the `Invoking' node for every program installed
+by a package under `Individual utilities', and an entry for the manual
+as a whole in the appropriate other category.
+
+
address@hidden Invoking install-info
address@hidden Invoking install-info
+
address@hidden install-info
+
address@hidden inserts menu entries from an Info file into the
+top-level @file{dir} file in the Info system (see the previous sections
+for an explanation of how the @file{dir} file works). It's most often
+run as part of software installation, or when constructing a @file{dir} file
+for all manuals on a system. Synopsis:
+
address@hidden
+install-info address@hidden@dots{} address@hidden address@hidden
address@hidden example
+
+If @var{info-file} or @var{dir-file} are not specified, the options
+(described below) that define them must be. There are no compile-time
+defaults, and standard input is never used. @code{install-info} can
+read only one Info file and write only one @file{dir} file per invocation.
+
address@hidden @file{dir}, created by @code{install-info}
+If @var{dir-file} (however specified) does not exist,
address@hidden creates it if possible (with no entries).
+
address@hidden Compressed files, reading
address@hidden Dir files, compressed
+If any input file is compressed with @code{gzip} (@pxref{Invoking
+gzip,,,gzip, Gzip}), @code{install-info} automatically uncompresses it
+for reading. And if @var{dir-file} is compressed, @code{install-info}
+also automatically leaves it compressed after writing any changes.
+If @var{dir-file} itself does not exist, @code{install-info} tries to
+open @address@hidden
+
+Options:
+
address@hidden @code
address@hidden --delete
address@hidden --delete
+Delete the entries in @var{info-file} from @var{dir-file}. The file
+name in the entry in @var{dir-file} must be @var{info-file} (except for
+an optional @samp{.info} in either one). Don't insert any new entries.
+
address@hidden address@hidden
address@hidden -d @var{name}
address@hidden address@hidden
address@hidden -d @var{name}
+Specify file name of the Info directory file. This is equivalent to
+using the @var{dir-file} argument.
+
address@hidden address@hidden
address@hidden -e @var{text}
address@hidden address@hidden
address@hidden -e @var{text}
+Insert @var{text} as an Info directory entry; @var{text} should have the
+form of an Info menu item line plus zero or more extra lines starting
+with whitespace. If you specify more than one entry, they are all
+added. If you don't specify any entries, they are determined from
+information in the Info file itself.
+
address@hidden --help
address@hidden -h
address@hidden --help
address@hidden -h
+Display a usage message listing basic usage and all available options,
+then exit successfully.
+
address@hidden address@hidden
address@hidden -i @var{file}
address@hidden address@hidden
address@hidden -i @var{file}
+Specify Info file to install in the directory.
+Equivalent to using the @var{info-file} argument.
+
address@hidden address@hidden
address@hidden -D @var{dir}
address@hidden address@hidden
address@hidden -D @var{dir}
+Specify the directory where @file{dir} resides.
+Equivalent to @address@hidden/dir}.
+
address@hidden address@hidden
address@hidden address@hidden
+Same as @address@hidden An Info directory entry is actually
+a menu item.
+
address@hidden --quiet
address@hidden --quiet
+Suppress warnings.
+
address@hidden --remove
address@hidden -r
address@hidden --remove
address@hidden -r
+Same as @samp{--delete}.
+
address@hidden address@hidden
address@hidden -s @var{sec}
address@hidden address@hidden
address@hidden -s @var{sec}
+Put this file's entries in section @var{sec} of the directory. If you
+specify more than one section, all the entries are added in each of the
+sections. If you don't specify any sections, they are determined from
+information in the Info file itself.
+
address@hidden --version
address@hidden -V
address@hidden --version
address@hidden -V
address@hidden version number, finding
+Display version information and exit successfully.
+
address@hidden table
+
+
address@hidden Command List
address@hidden @@-Command List
address@hidden Alphabetical @@-command list
address@hidden List of @@-commands
address@hidden @@-command list
address@hidden Reference to @@-commands
+
+Here is an alphabetical list of the @@-commands in Texinfo. Square
+brackets, @address@hidden address@hidden, indicate optional arguments; an
ellipsis,
address@hidden@dots{}}, indicates repeated text.
+
address@hidden 1
address@hidden @code
address@hidden @@@var{whitespace}
+An @code{@@} followed by a space, tab, or newline produces a normal,
+stretchable, interword space. @xref{Multiple Spaces}.
+
address@hidden @@!
+Generate an exclamation point that really does end a sentence (usually
+after an end-of-sentence capital letter). @xref{Ending a Sentence}.
+
address@hidden @@"
address@hidden @@'
+Generate an umlaut or acute accent, respectively, over the next
+character, as in @"o and @'o. @xref{Inserting Accents}.
+
address@hidden @@*
+Force a line break. Do not end a paragraph that uses @code{@@*} with
+an @code{@@refill} command. @xref{Line Breaks}.
+
address@hidden @@,@address@hidden@}
+Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting
+Accents}.
+
address@hidden @@-
+Insert a discretionary hyphenation point. @xref{- and hyphenation}.
+
address@hidden @@.
+Produce a period that really does end a sentence (usually after an
+end-of-sentence capital letter). @xref{Ending a Sentence}.
+
address@hidden @@:
+Indicate to @TeX{} that an immediately preceding period, question
+mark, exclamation mark, or colon does not end a sentence. Prevent
address@hidden from inserting extra whitespace as it does at the end of a
+sentence. The command has no effect on the Info file output.
address@hidden Ending a Sentence}.
+
address@hidden @@=
+Generate a macron (bar) accent over the next character, as in @=o.
address@hidden Accents}.
+
address@hidden @@?
+Generate a question mark that really does end a sentence (usually after
+an end-of-sentence capital letter). @xref{Ending a Sentence}.
+
address@hidden @@@@
+Stands for an at sign, @samp{@@}.
address@hidden Atsigns, , Inserting @@ and braces}.
+
address@hidden @@\
+Stands for a backslash (@samp{\}) inside @code{@@math}.
address@hidden,,@code{math}}.
+
address@hidden @@^
address@hidden @@`
+Generate a circumflex (hat) or grave accent, respectively, over the next
+character, as in @^o and @`e.
address@hidden Accents}.
+
address@hidden @@@{
+Stands for a left brace, @address@hidden
address@hidden Atsigns, , Inserting @@ and braces}.
+
address@hidden @@@}
+Stands for a right-hand brace, @address@hidden@*
address@hidden Atsigns, , Inserting @@ and braces}.
+
address@hidden @@~
+Generate a tilde accent over the next character, as in @~N.
address@hidden Accents}.
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Generate the uppercase and lowercase Scandinavian A-ring letters,
+respectively: @AA{}, @aa{}. @xref{Inserting Accents}.
+
address@hidden @@address@hidden@address@hidden
+Tag @var{abbrev} as an acronym, that is, an abbreviation written in all
+capital letters, such as `NASA'. @xref{acronym,, @code{acronym}}.
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Generate the uppercase and lowercase AE ligatures, respectively:
address@hidden, @ae{}. @xref{Inserting Accents}.
+
address@hidden @@afivepaper
+Change page dimensions for the A5 paper size. @xref{A4 Paper}.
+
address@hidden @@afourlatex
address@hidden @@afourpaper
address@hidden @@afourwide
+Change page dimensions for the A4 paper size. @xref{A4 Paper}.
+
address@hidden @@alias @address@hidden
+Make the command @samp{@@@var{new}} an alias for the existing command
address@hidden@@@var{existing}}. @xref{alias}.
+
address@hidden @@address@hidden@address@hidden
+Define @var{name} as the current location for use as a cross-reference
+target. @xref{anchor,, @code{@@anchor}}.
+
address@hidden @@appendix @var{title}
+Begin an appendix. The title appears in the table
+of contents of a printed manual. In Info, the title is
+underlined with asterisks. @xref{unnumbered & appendix, , The
address@hidden@@unnumbered} and @code{@@appendix} address@hidden
+
address@hidden @@appendixsec @var{title}
address@hidden @@appendixsection @var{title}
+Begin an appendix section within an appendix. The section title appears
+in the table of contents of a printed manual. In Info, the title is
+underlined with equal signs. @code{@@appendixsection} is a longer
+spelling of the @code{@@appendixsec} command. @xref{unnumberedsec
+appendixsec heading, , Section address@hidden
+
address@hidden @@appendixsubsec @var{title}
+Begin an appendix subsection within an appendix. The title appears
+in the table of contents of a printed manual. In Info, the title is
+underlined with hyphens. @xref{unnumberedsubsec appendixsubsec
+subheading, , Subsection address@hidden
+
address@hidden @@appendixsubsubsec @var{title}
+Begin an appendix subsubsection within an appendix subsection. The
+title appears in the table of contents of a printed manual. In Info,
+the title is underlined with periods. @xref{subsubsection,, The
+`subsub' address@hidden
+
address@hidden @@asis
+Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to
+print the table's first column without highlighting (``as is'').
address@hidden Tables, , Making a Two-column address@hidden
+
address@hidden @@author @var{author}
+Typeset @var{author} flushleft and underline it. @xref{title
+subtitle author, , The @code{@@title} and @code{@@author}
address@hidden
+
address@hidden @@address@hidden@address@hidden
+Print @var{text} in @b{bold} font. No effect in Info. @address@hidden
+
+
address@hidden @@address@hidden@}
+Generate a large round dot, or the closest possible
+thing to one. @xref{bullet, , @code{@@address@hidden
+
address@hidden @@bye
+Stop formatting a file. The formatters do not see the contents of a
+file following an @code{@@bye} command. @xref{Ending a address@hidden
+
address@hidden @@c @var{comment}
+Begin a comment in Texinfo. The rest of the line does not appear in
+either the Info file or the printed manual. A synonym for
address@hidden@@comment}. @xref{Comments, , address@hidden
+
address@hidden @@cartouche
+Highlight an example or quotation by drawing a box with rounded
+corners around it. Pair with @code{@@end cartouche}. No effect in
+Info. @xref{cartouche, , Drawing Cartouches Around Examples}.)@refill
+
address@hidden @@center @var{line-of-text}
+Center the line of text following the command.
address@hidden center sp, , @code{@@address@hidden
+
address@hidden @@centerchap @var{line-of-text}
+Like @code{@@chapter}, but centers the chapter title. @xref{chapter,,
address@hidden@@chapter}}.
+
address@hidden @@chapheading @var{title}
+Print a chapter-like heading in the text, but not in the table of
+contents of a printed manual. In Info, the title is underlined with
+asterisks. @xref{majorheading & chapheading, , @code{@@majorheading}
+and @code{@@address@hidden
+
address@hidden @@chapter @var{title}
+Begin a chapter. The chapter title appears in the table of
+contents of a printed manual. In Info, the title is underlined with
+asterisks. @xref{chapter, , @code{@@address@hidden
+
address@hidden @@cindex @var{entry}
+Add @var{entry} to the index of concepts. @xref{Index Entries, ,
+Defining the Entries of an address@hidden
+
address@hidden @@address@hidden@address@hidden
+Highlight the name of a book or other reference that lacks a
+companion Info file. @xref{cite, , @code{@@address@hidden
+
address@hidden @@clear @var{flag}
+Unset @var{flag}, preventing the Texinfo formatting commands from
+formatting text between subsequent pairs of @code{@@ifset @var{flag}}
+and @code{@@end ifset} commands, and preventing
address@hidden@@address@hidden@address@hidden from expanding to the value to
which
address@hidden is set.
address@hidden clear value, , @code{@@set} @code{@@clear} @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Highlight text that is an expression, a syntactically complete token
+of a program, or a program name. @xref{code, , @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate a command name, such as @command{ls}.
address@hidden,, @code{@@command}}.
+
address@hidden @@comment @var{comment}
+Begin a comment in Texinfo. The rest of the line does not appear in
+either the Info file or the printed manual. A synonym for @code{@@c}.
address@hidden
+
address@hidden @@contents
+Print a complete table of contents. Has no effect in Info, which uses
+menus instead. @xref{Contents, , Generating a Table of
address@hidden
+
address@hidden @@address@hidden@}
+Generate a copyright symbol. @xref{copyright symbol, ,
address@hidden@@address@hidden
+
+
address@hidden @@defcodeindex @var{index-name}
+Define a new index and its indexing command. Print entries in an
address@hidden@@code} font. @xref{New Indices, , Defining New
address@hidden
+
address@hidden @@defcv @var{category} @var{class} @var{name}
address@hidden @@defcvx @var{category} @var{class} @var{name}
+Format a description for a variable associated with a class in
+object-oriented programming. Takes three arguments: the category of
+thing being defined, the class to which it belongs, and its name.
address@hidden Commands}, and @ref{deffnx,, Def Cmds in Detail}.
+
address@hidden @@deffn @var{category} @var{name} @address@hidden
address@hidden @@deffnx @var{category} @var{name} @address@hidden
+Format a description for a function, interactive command, or similar
+entity that may take arguments. @code{@@deffn} takes as arguments the
+category of entity being described, the name of this particular
+entity, and its arguments, if any. @xref{Definition address@hidden
+
address@hidden @@defindex @var{index-name}
+Define a new index and its indexing command. Print entries in a roman
+font. @xref{New Indices, , Defining New address@hidden
+
address@hidden @@definfoenclose @var{newcmd}, @var{before}, @var{after},
+Create new @@-command @var{newcmd} for Info that marks text by enclosing
+it in strings that precede and follow the text. @xref{definfoenclose}.
+
address@hidden @@defivar @var{class} @var{instance-variable-name}
address@hidden @@defivarx @var{class} @var{instance-variable-name}
+This command formats a description for an instance variable in
+object-oriented programming. The command is equivalent to @samp{@@defcv
address@hidden address@hidden @dots{}}. @xref{Definition Commands}, and
address@hidden,, Def Cmds in Detail}.
+
address@hidden @@defmac @var{macroname} @address@hidden
address@hidden @@defmacx @var{macroname} @address@hidden
+Format a description for a macro. The command is equivalent to
address@hidden@@deffn Macro @dots{}}. @xref{Definition Commands}, and
address@hidden,, Def Cmds in Detail}.
+
address@hidden @@defmethod @var{class} @var{method-name} @address@hidden
address@hidden @@defmethodx @var{class} @var{method-name} @address@hidden
+Format a description for a method in object-oriented programming. The
+command is equivalent to @samp{@@defop Method @dots{}}. Takes as
+arguments the name of the class of the method, the name of the
+method, and its arguments, if any. @xref{Definition Commands}, and
address@hidden,, Def Cmds in Detail}.
+
address@hidden @@defop @var{category} @var{class} @var{name} @address@hidden
address@hidden @@defopx @var{category} @var{class} @var{name} @address@hidden
+Format a description for an operation in object-oriented programming.
address@hidden@@defop} takes as arguments the overall name of the category of
+operation, the name of the class of the operation, the name of the
+operation, and its arguments, if any. @xref{Definition
+Commands}, and @ref{Abstract Objects}.
+
address@hidden @@defopt @var{option-name}
address@hidden @@defoptx @var{option-name}
+Format a description for a user option. The command is equivalent to
address@hidden@@defvr @{User address@hidden @dots{}}. @xref{Definition
Commands}, and
address@hidden,, Def Cmds in Detail}.
+
address@hidden @@defspec @var{special-form-name} @address@hidden
address@hidden @@defspecx @var{special-form-name} @address@hidden
+Format a description for a special form. The command is equivalent to
address@hidden@@deffn @{Special address@hidden @dots{}}. @xref{Definition
Commands},
+and @ref{deffnx,, Def Cmds in Detail}.
+
address@hidden @@deftp @var{category} @var{name-of-type} @address@hidden
address@hidden @@deftpx @var{category} @var{name-of-type} @address@hidden
+Format a description for a data type. @code{@@deftp} takes as arguments
+the category, the name of the type (which is a word like @samp{int} or
address@hidden), and then the names of attributes of objects of that type.
address@hidden Commands}, and @ref{Data Types}.
+
address@hidden @@deftypefn @var{classification} @var{data-type} @var{name}
@address@hidden
address@hidden @@deftypefnx @var{classification} @var{data-type} @var{name}
@address@hidden
+Format a description for a function or similar entity that may take
+arguments and that is typed. @code{@@deftypefn} takes as arguments the
+classification of entity being described, the type, the name of the
+entity, and its arguments, if any. @xref{Definition Commands}, and
address@hidden,, Def Cmds in Detail}.
+
address@hidden @@deftypefun @var{data-type} @var{function-name} @address@hidden
address@hidden @@deftypefunx @var{data-type} @var{function-name} @address@hidden
+Format a description for a function in a typed language.
+The command is equivalent to @samp{@@deftypefn Function @dots{}}.
address@hidden Commands}, and @ref{deffnx,, Def Cmds in Detail}.
+
address@hidden @@deftypeivar @var{class} @var{data-type} @var{variable-name}
address@hidden @@deftypeivarx @var{class} @var{data-type} @var{variable-name}
+Format a description for a typed instance variable in object-oriented
+programming. @xref{Definition Commands}, and @ref{Abstract Objects}.
+
address@hidden @@deftypemethod @var{class} @var{data-type} @var{method-name}
@address@hidden
address@hidden @@deftypemethodx @var{class} @var{data-type} @var{method-name}
@address@hidden
+Format a description for a typed method in object-oriented programming.
address@hidden Commands}, and @ref{deffnx,, Def Cmds in Detail}.
+
address@hidden @@deftypeop @var{category} @var{class} @var{data-type}
@var{name} @address@hidden
address@hidden @@deftypeopx @var{category} @var{class} @var{data-type}
@var{name} @address@hidden
+Format a description for a typed operation in object-oriented programming.
address@hidden Commands}, and @ref{Abstract Objects}.
+
address@hidden @@deftypevar @var{data-type} @var{variable-name}
address@hidden @@deftypevarx @var{data-type} @var{variable-name}
+Format a description for a variable in a typed language. The command is
+equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition
+Commands}, and @ref{deffnx,, Def Cmds in Detail}.
+
address@hidden @@deftypevr @var{classification} @var{data-type} @var{name}
address@hidden @@deftypevrx @var{classification} @var{data-type} @var{name}
+Format a description for something like a variable in a typed
+language---an entity that records a value. Takes as arguments the
+classification of entity being described, the type, and the name of the
+entity. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in
+Detail}.
+
address@hidden @@defun @var{function-name} @address@hidden
address@hidden @@defunx @var{function-name} @address@hidden
+Format a description for functions. The command is equivalent to
address@hidden@@deffn Function @dots{}}. @xref{Definition Commands}, and
address@hidden,, Def Cmds in Detail}.
+
address@hidden @@defvar @var{variable-name}
address@hidden @@defvarx @var{variable-name}
+Format a description for variables. The command is equivalent to
address@hidden@@defvr Variable @dots{}}. @xref{Definition Commands}, and
address@hidden,, Def Cmds in Detail}.
+
address@hidden @@defvr @var{category} @var{name}
address@hidden @@defvrx @var{category} @var{name}
+Format a description for any kind of variable. @code{@@defvr} takes
+as arguments the category of the entity and the name of the entity.
address@hidden Commands},
+and @ref{deffnx,, Def Cmds in Detail}.
+
address@hidden @@detailmenu
+Avoid @code{makeinfo} confusion stemming from the detailed node listing
+in a master menu. @xref{Master Menu Parts}.
+
address@hidden @@address@hidden@address@hidden
+Highlight the introductory or defining use of a term.
address@hidden, , @code{@@address@hidden
+
address@hidden @@dircategory @var{dirpart}
+Specify a part of the Info directory menu where this file's entry should
+go. @xref{Installing Dir Entries}.
+
address@hidden @@direntry
+Begin the Info directory menu entry for this file. Pair with
address@hidden@@end direntry}. @xref{Installing Dir Entries}.
+
address@hidden @@display
+Begin a kind of example. Like @code{@@example} (indent text, do not
+fill), but do not select a new font. Pair with @code{@@end display}.
address@hidden, , @code{@@display}}.
+
address@hidden @@address@hidden@address@hidden
+Format a unit of measure, as in address@hidden Causes @TeX{} to insert a
+thin space before @var{dimension}. No effect in Info.
address@hidden, , @code{@@dmn}}.
+
address@hidden @@documentdescription
+Set the document description text, included in the HTML output. Pair
+with @code{@@end documentdescription}. @xref{documentdescription,,
address@hidden@@documentdescription}}.
+
address@hidden @@documentencoding @var{enc}
+Declare the input encoding to be @var{enc}.
address@hidden,, @code{@@documentencoding}}.
+
address@hidden @@documentlanguage @var{CC}
+Declare the document language as the two-character ISO-639 abbreviation
address@hidden @xref{documentlanguage,, @code{@@documentlanguage}}.
+
address@hidden @@address@hidden@address@hidden
+Generate a dot accent over the character @var{c}, as in @dotaccent{o}.
address@hidden Accents}.
+
address@hidden @@address@hidden@}
+Insert an ellipsis: @address@hidden
address@hidden, , @code{@@address@hidden
+
address@hidden @@address@hidden@var{address}[, @address@hidden
+Indicate an electronic mail address.
address@hidden, , @code{@@email}}.
+
address@hidden @@address@hidden@address@hidden
+Highlight @var{text}; text is displayed in @emph{italics} in printed
+output, and surrounded by asterisks in Info. @xref{Emphasis, ,
+Emphasizing Text}.
+
address@hidden @@end @var{environment}
+Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting
+Commands,,@@-commands}.
+
address@hidden @@address@hidden@address@hidden
+Indicate an environment variable name, such as @env{PATH}.
address@hidden,, @code{@@env}}.
+
address@hidden @@address@hidden@}
+Generate an end-of-sentence of ellipsis, like this @enddots{}
address@hidden,,@code{@@address@hidden@}}}.
+
address@hidden @@enumerate address@hidden
+Begin a numbered list, using @code{@@item} for each entry.
+Optionally, start list with @var{number-or-letter}. Pair with
address@hidden@@end enumerate}. @xref{enumerate, ,
address@hidden@@address@hidden
+
address@hidden @@address@hidden@}
+Indicate to the reader the exact equivalence of two forms with a
+glyph: @address@hidden @address@hidden
+
address@hidden @@address@hidden@}
+Indicate to the reader with a glyph that the following text is
+an error message: @address@hidden @xref{Error address@hidden
+
address@hidden @@evenfooting address@hidden @@| address@hidden @@|
address@hidden
address@hidden @@evenheading address@hidden @@| address@hidden @@|
address@hidden
+Specify page footings resp.@: headings for even-numbered (left-hand)
+pages. @xref{Custom Headings, ,
+How to Make Your Own address@hidden
+
address@hidden @@everyfooting address@hidden @@| address@hidden @@|
address@hidden
address@hidden @@everyheading address@hidden @@| address@hidden @@|
address@hidden
+Specify page footings resp.@: headings for every page. Not relevant to
+Info. @xref{Custom Headings, , How to Make Your Own address@hidden
+
address@hidden @@example
+Begin an example. Indent text, do not fill, and select fixed-width font.
+Pair with @code{@@end example}. @xref{example, ,
address@hidden@@address@hidden
+
address@hidden @@exampleindent @var{indent}
+Indent example-like environments by @var{indent} number of spaces
+(perhaps 0). @xref{exampleindent,, Paragraph Indenting}.
+
address@hidden @@address@hidden@}
+Produce an upside-down exclamation point. @xref{Inserting Accents}.
+
address@hidden @@exdent @var{line-of-text}
+Remove any indentation a line might have. @xref{exdent, ,
+Undoing the Indentation of a address@hidden
+
address@hidden @@address@hidden@}
+Indicate the result of a macro expansion to the reader with a special
+glyph: @address@hidden
address@hidden, , @expansion{} Indicating an address@hidden
+
address@hidden @@address@hidden@address@hidden
+Highlight the name of a file, buffer, node, or directory. @xref{file, ,
address@hidden@@address@hidden
+
address@hidden @@finalout
+Prevent @TeX{} from printing large black warning rectangles beside
+over-wide lines. @xref{Overfull address@hidden
+
address@hidden @@findex @var{entry}
+Add @var{entry} to the index of functions. @xref{Index Entries, ,
+Defining the Entries of an address@hidden
+
address@hidden @@flushleft
address@hidden @@flushright
+Left justify every line but leave the right end ragged.
+Leave font as is. Pair with @code{@@end flushleft}.
address@hidden@@flushright} analogous.
address@hidden & flushright, , @code{@@flushleft} and
address@hidden@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Enter a footnote. Footnote text is printed at the bottom of the page
+by @TeX{}; Info may format in either `End' node or `Separate' node style.
address@hidden@refill
+
address@hidden @@footnotestyle @var{style}
+Specify an Info file's footnote style, either @samp{end} for the end
+node style or @samp{separate} for the separate node style.
address@hidden@refill
+
address@hidden @@format
+Begin a kind of example. Like @code{@@display}, but do not narrow the
+margins. Pair with @code{@@end format}. @xref{example,,
address@hidden@@example}}.
+
address@hidden @@ftable @var{formatting-command}
+Begin a two-column table, using @code{@@item} for each entry.
+Automatically enter each of the items in the first column into the
+index of functions. Pair with @code{@@end ftable}. The same as
address@hidden@@table}, except for indexing. @xref{ftable vtable, ,
address@hidden@@ftable} and @code{@@address@hidden
+
address@hidden @@group
+Hold text together that must appear on one printed page. Pair with
address@hidden@@end group}. Not relevant to Info. @xref{group, ,
address@hidden@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}.
+
address@hidden @@heading @var{title}
+Print an unnumbered section-like heading in the text, but not in the
+table of contents of a printed manual. In Info, the title is
+underlined with equal signs. @xref{unnumberedsec appendixsec heading,
+, Section address@hidden
+
address@hidden @@headings @var{on-off-single-double}
+Turn page headings on or off, and/or specify single-sided or double-sided
+page headings for printing. @xref{headings on off, , The
address@hidden@@headings} Command}.
+
address@hidden @@html
+Enter HTML completely. Pair with @code{@@end html}. @xref{Raw
+Formatter Commands}.
+
address@hidden @@address@hidden@var{hy-phen-a-ted address@hidden
+Explicitly define hyphenation points. @xref{- and hyphenation,,
address@hidden@@-} and @code{@@hyphenation}}.
+
address@hidden @@address@hidden@address@hidden
+Print @var{text} in @i{italic} font. No effect in Info. @xref{Fonts}.
+
address@hidden @@ifclear @var{flag}
+If @var{flag} is cleared, the Texinfo formatting commands format text
+between @code{@@ifclear @var{flag}} and the following @code{@@end
+ifclear} command.
address@hidden clear value, , @code{@@set} @code{@@clear} @code{@@address@hidden
+
address@hidden @@ifhtml
address@hidden @@ifinfo
+Begin a stretch of text that will be ignored by @TeX{} when it typesets
+the printed manual. @code{@@ifhtml} text appears only in the HTML
+output. @code{@@ifinfo} output appears in both Info and (for historical
+compatibility) plain text output . Pair with @code{@@end ifhtml}
+resp.@: @code{@@end ifinfo}. @xref{Conditionals}.
+
address@hidden @@ifnothtml
address@hidden @@ifnotinfo
address@hidden @@ifnotplaintext
address@hidden @@ifnottex
+Begin a stretch of text that will be ignored in one output format but
+not the others. The text appears in the formats not specified:
address@hidden@@ifnothtml} text is omitted from html output, etc. The exception
+is @code{@@ifnotinfo} text, which is omitted from plain text output as
+well as Info output. Pair with @code{@@end ifnothtml} resp.@:
address@hidden@@end ifnotinfo} resp.@: @code{@@end ifnotplaintext} resp.@:
address@hidden@@end ifnottex}. @xref{Conditionals}.
+
address@hidden @@ifplaintext
+Begin a stretch of text that appears only in the plain text output.
+Pair with @code{@@end ifplaintext}. @xref{Conditionals}.
+
address@hidden @@ifset @var{flag}
+If @var{flag} is set, the Texinfo formatting commands format text
+between @code{@@ifset @var{flag}} and the following @code{@@end ifset}
+command.
address@hidden clear value, , @code{@@set} @code{@@clear} @code{@@address@hidden
+
address@hidden @@iftex
+Begin a stretch of text that will not appear in the Info file, but
+will be processed only by @TeX{}. Pair with @code{@@end iftex}.
address@hidden, , Conditionally Visible address@hidden
+
address@hidden @@ignore
+Begin a stretch of text that will not appear in either the Info file
+or the printed output. Pair with @code{@@end ignore}.
address@hidden, , Comments and Ignored address@hidden
+
address@hidden @@address@hidden@var{filename}, address@hidden, address@hidden,
address@hidden, address@hidden@}
+Include graphics image in external @var{filename} scaled to the given
address@hidden and/or @var{height}, using @var{alt} text and looking for
address@hidden@address@hidden in HTML. @xref{Images}.
+
address@hidden @@include @var{filename}
+Incorporate the contents of the file @var{filename} into the Info file
+or printed document. @xref{Include address@hidden
+
address@hidden @@address@hidden@var{node-name}, address@hidden, @address@hidden
+Make a cross reference to an Info file for which there is no printed
+manual. @xref{inforef, , Cross references using
address@hidden@@address@hidden
+
address@hidden \input @var{macro-definitions-file}
+Use the specified macro definitions file. This command is used only
+in the first line of a Texinfo file to cause @TeX{} to make use of the
address@hidden macro definitions file. The backslash in @code{\input}
+is used instead of an @code{@@} because @TeX{} does not
+recognize @code{@@} until after it has read the definitions file.
address@hidden File Header}.
+
address@hidden @@item
+Indicate the beginning of a marked paragraph for @code{@@itemize} and
address@hidden@@enumerate}; indicate the beginning of the text of a first column
+entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}.
address@hidden and address@hidden
+
address@hidden @@itemize @var{mark-generating-character-or-command}
+Produce a sequence of indented paragraphs, with a mark inside the left
+margin at the beginning of each paragraph. Pair with @code{@@end
+itemize}. @xref{itemize, , @code{@@address@hidden
+
address@hidden @@itemx
+Like @code{@@item} but do not generate extra vertical space above the
+item text. @xref{itemx, , @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate text that is characters of input to be typed by
+users. @xref{kbd, , @code{@@address@hidden
+
address@hidden @@kbdinputstyle @var{style}
+Specify when @code{@@kbd} should use a font distinct from @code{@@code}.
address@hidden, , @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate a name for a key on a keyboard.
address@hidden, , @code{@@address@hidden
+
address@hidden @@kindex @var{entry}
+Add @var{entry} to the index of keys.
address@hidden Entries, , Defining the Entries of an address@hidden
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Generate the uppercase and lowercase Polish suppressed-L letters,
+respectively: @L{}, @l{}.
+
address@hidden Possibly this can be tossed now that we have macros. --karl,
16sep96.
address@hidden Yes, let's toss it, it's pretty weird. --karl, 15jun97.
address@hidden @item @@global@@address@hidden@var{existing-command}
address@hidden Equate a new highlighting command with an existing one. Only for
address@hidden @TeX{}. Write definition inside of @code{@@iftex} @dots{}
@code{@@end
address@hidden iftex}. @xref{Customized address@hidden
+
address@hidden @@lisp
+Begin an example of Lisp code. Indent text, do not fill, and select
+fixed-width font. Pair with @code{@@end lisp}. @xref{lisp, , @code{@@lisp}}.
+
address@hidden @@lowersections
+Change subsequent chapters to sections, sections to subsections, and so
+on. @xref{Raise/lower sections, , @code{@@raisesections} and
address@hidden@@address@hidden
+
address@hidden @@macro @var{macroname} @address@hidden@}
+Define a new Texinfo command @code{@@@address@hidden@address@hidden
+Only supported by @code{makeinfo} and @code{texi2dvi}. @xref{Defining
+Macros}.
+
address@hidden @@majorheading @var{title}
+Print a chapter-like heading in the text, but not in the table of
+contents of a printed manual. Generate more vertical whitespace before
+the heading than the @code{@@chapheading} command. In Info, the chapter
+heading line is underlined with asterisks. @xref{majorheading &
+chapheading, , @code{@@majorheading} and @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Format a mathematical expression.
address@hidden, , @code{@@math}: Inserting Mathematical Expressions}.
+
address@hidden @@menu
+Mark the beginning of a menu of nodes in Info. No effect in a printed
+manual. Pair with @code{@@end menu}. @address@hidden
+
address@hidden @@address@hidden@}
+Generate a minus sign, address@hidden'. @xref{minus, , @code{@@address@hidden
+
address@hidden @@multitable @var{column-width-spec}
+Begin a multi-column table. Pair with @code{@@end multitable}.
address@hidden Column Widths}.
+
address@hidden @@need @var{n}
+Start a new page in a printed manual if fewer than @var{n} mils
+(thousandths of an inch) remain on the current page. @xref{need, ,
address@hidden@@address@hidden
+
address@hidden @@node @var{name}, @var{next}, @var{previous}, @var{up}
+Define the beginning of a new node in Info, and serve as a locator for
+references for @TeX{}. @xref{node, , @code{@@address@hidden
+
address@hidden @@noindent
+Prevent text from being indented as if it were a new paragraph.
address@hidden, , @code{@@address@hidden
+
address@hidden @@novalidate
+Suppress validation of node references, omit creation of auxiliary files
+with @TeX{}. Use before @code{@@setfilename}. @xref{Pointer Validation}.
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Generate the uppercase and lowercase O-with-slash letters, respectively:
address@hidden, @o{}.
+
address@hidden @@oddfooting address@hidden @@| address@hidden @@|
address@hidden
address@hidden @@oddheading address@hidden @@| address@hidden @@| address@hidden
+Specify page footings resp.@: headings for odd-numbered (right-hand)
+pages. @xref{Custom Headings, ,
+How to Make Your Own address@hidden
+
address@hidden @@address@hidden@}
address@hidden @@address@hidden@}
+Generate the uppercase and lowercase OE ligatures, respectively:
address@hidden, @oe{}. @xref{Inserting Accents}.
+
address@hidden @@address@hidden@address@hidden
+Indicate a command-line option, such as @option{-l} or @option{--help}.
address@hidden,, @code{@@option}}.
+
address@hidden @@page
+Start a new page in a printed manual. No effect in Info.
address@hidden, , @code{@@address@hidden
+
address@hidden @@pagesizes address@hidden, @var{height}]
+Change page dimensions. @xref{pagesizes}.
+
address@hidden @@paragraphindent @var{indent}
+Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve
+source file indentation if @var{indent} is @code{asis}.
address@hidden,, Paragraph Indenting}.
+
address@hidden @@pindex @var{entry}
+Add @var{entry} to the index of programs. @xref{Index Entries, , Defining
+the Entries of an address@hidden
+
address@hidden @@address@hidden@}
+Indicate the position of point in a buffer to the reader with a
+glyph: @address@hidden @xref{Point Glyph, , Indicating
+Point in a address@hidden
+
address@hidden @@address@hidden@}
+Generate the pounds sterling currency sign.
address@hidden,,@code{@@address@hidden@}}}.
+
address@hidden @@address@hidden@}
+Indicate printed output to the reader with a glyph:
address@hidden@print{}}. @xref{Print address@hidden
+
address@hidden @@printindex @var{index-name}
+Print an alphabetized two-column index in a printed manual or generate
+an alphabetized menu of index entries for Info. @xref{Printing
+Indices & address@hidden
+
address@hidden @@address@hidden@var{node-name}, address@hidden, address@hidden,
address@hidden, address@hidden@}
+Make a reference that starts with a lower case `see' in a printed
+manual. Use within parentheses only. Do not follow command with a
+punctuation mark---the Info formatting commands automatically insert
+terminating punctuation as needed. Only the first argument is mandatory.
address@hidden, , @code{@@address@hidden
+
address@hidden @@address@hidden@}
+Generate an upside-down question mark. @xref{Inserting Accents}.
+
address@hidden @@quotation
+Narrow the margins to indicate text that is quoted from another real
+or imaginary work. Write command on a line of its own. Pair with
address@hidden@@end quotation}. @xref{quotation, ,
address@hidden@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Print @var{text} in @r{roman} font. No effect in Info.
address@hidden@refill
+
address@hidden @@raisesections
+Change subsequent sections to chapters, subsections to sections, and so
+on. @xref{Raise/lower sections, , @code{@@raisesections} and
address@hidden@@address@hidden
+
address@hidden @@address@hidden@var{node-name}, address@hidden, address@hidden,
address@hidden, address@hidden@}
+Make a reference. In a printed manual, the reference does not start
+with a `See'. Follow command with a punctuation mark. Only the first
+argument is mandatory. @xref{ref, , @code{@@address@hidden
+
address@hidden @@refill
+In Info, refill and indent the paragraph after all the other processing
+has been done. No effect on @TeX{}, which always refills. This command
+is no longer needed, since all formatters now automatically refill.
address@hidden address@hidden
+
address@hidden @@address@hidden@}
+Indicate the result of an expression to the reader with a special
+glyph: @address@hidden @xref{result, , @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Generate a ring accent over the next character, as in @ringaccent{o}.
address@hidden Accents}.
+
address@hidden @@address@hidden@address@hidden
+Highlight @var{text} that is a literal example of a sequence of
+characters. Used for single characters, for statements, and often for
+entire shell commands. @xref{samp, , @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Set @var{text} in a printed output in @sc{the small caps font} and
+set text in the Info file in uppercase letters.
address@hidden@refill
+
address@hidden @@section @var{title}
+Begin a section within a chapter. In a printed manual, the section
+title is numbered and appears in the table of contents. In Info, the
+title is underlined with equal signs. @xref{section, ,
address@hidden@@address@hidden
+
address@hidden @@set @var{flag} address@hidden
+Make @var{flag} active, causing the Texinfo formatting commands to
+format text between subsequent pairs of @code{@@ifset @var{flag}} and
address@hidden@@end ifset} commands. Optionally, set value of @var{flag} to
address@hidden
address@hidden clear value, , @code{@@set} @code{@@clear} @code{@@value}}.
+
address@hidden @@setchapternewpage @var{on-off-odd}
+Specify whether chapters start on new pages, and if so, whether on
+odd-numbered (right-hand) new pages. @xref{setchapternewpage, ,
address@hidden@@setchapternewpage}}.
+
address@hidden @@setcontentsaftertitlepage
+Put the table of contents after the @samp{@@end titlepage} even if the
address@hidden@@contents} command is not there. @xref{Contents}.
+
address@hidden @@setfilename @var{info-file-name}
+Provide a name to be used by the Info file. This command is essential
+for @TeX{} formatting as well, even though it produces no output.
address@hidden, , @code{@@setfilename}}.
+
address@hidden @@setshortcontentsaftertitlepage
+Place the short table of contents after the @samp{@@end titlepage}
+command even if the @code{@@shortcontents} command is not there.
address@hidden
+
address@hidden @@settitle @var{title}
+Provide a title for page headers in a printed manual, and the default
+document description for HTML @samp{<head>}.
address@hidden, , @code{@@address@hidden
+
address@hidden @@shortcontents
+Print a short table of contents. Not relevant to Info, which uses
+menus rather than tables of contents. A synonym for
address@hidden@@summarycontents}. @xref{Contents, , Generating a Table of
address@hidden
+
address@hidden @@shorttitlepage @var{title}
+Generate a minimal title page. @xref{titlepage,,@code{@@titlepage}}.
+
address@hidden @@smallbook
+Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format
+rather than the regular 8.5 by 11 inch format. @xref{smallbook, ,
+Printing Small Books}. Also, see @ref{small}.
+
address@hidden @@smalldisplay
+Begin a kind of example. Like @code{@@smallexample} (narrow margins, no
+filling), but do not select the fixed-width font. Pair with @code{@@end
+smalldisplay}. @xref{small}.
+
address@hidden @@smallexample
+Indent text to indicate an example. Do not fill, select fixed-width
+font, narrow the margins. In printed manuals, print text in a smaller
+font than with @code{@@example}. Pair with @code{@@end smallexample}.
address@hidden
+
address@hidden @@smallformat
+Begin a kind of example. Like @code{@@smalldisplay}, but do not narrow
+the margins. Pair with @code{@@end smallformat}. @xref{small}.
+
address@hidden @@smalllisp
+Begin an example of Lisp code. Same as @code{@@smallexample}. Pair
+with @code{@@end smalllisp}. @xref{small}.
+
address@hidden @@sp @var{n}
+Skip @var{n} blank lines. @xref{sp, , @code{@@address@hidden
+
address@hidden @@address@hidden@}
+Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}.
+
address@hidden @@strong @address@hidden@}
+Emphasize @var{text} by typesetting it in a @strong{bold} font for the
+printed manual and by surrounding it with asterisks for Info.
address@hidden & strong, , Emphasizing address@hidden
+
address@hidden @@subheading @var{title}
+Print an unnumbered subsection-like heading in the text, but not in
+the table of contents of a printed manual. In Info, the title is
+underlined with hyphens. @xref{unnumberedsubsec appendixsubsec
+subheading, , @code{@@unnumberedsubsec} @code{@@appendixsubsec}
address@hidden@@address@hidden
+
address@hidden @@subsection @var{title}
+Begin a subsection within a section. In a printed manual, the
+subsection title is numbered and appears in the table of contents. In
+Info, the title is underlined with hyphens. @xref{subsection, ,
address@hidden@@address@hidden
+
address@hidden @@subsubheading @var{title}
+Print an unnumbered subsubsection-like heading in the text, but not in
+the table of contents of a printed manual. In Info, the title is
+underlined with periods. @xref{subsubsection, , The `subsub'
address@hidden
+
address@hidden @@subsubsection @var{title}
+Begin a subsubsection within a subsection. In a printed manual,
+the subsubsection title is numbered and appears in the table of
+contents. In Info, the title is underlined with periods.
address@hidden, , The `subsub' address@hidden
+
address@hidden @@subtitle @var{title}
+In a printed manual, set a subtitle in a normal sized font flush to
+the right-hand side of the page. Not relevant to Info, which does not
+have title pages. @xref{title subtitle author, , @code{@@title}
address@hidden@@subtitle} and @code{@@author} address@hidden
+
address@hidden @@summarycontents
+Print a short table of contents. Not relevant to Info, which uses
+menus rather than tables of contents. A synonym for
address@hidden@@shortcontents}. @xref{Contents, , Generating a Table of
address@hidden
+
address@hidden @@syncodeindex @var{from-index} @var{into-index}
+Merge the index named in the first argument into the index named in
+the second argument, printing the entries from the first index in
address@hidden@@code} font. @xref{Combining address@hidden
+
address@hidden @@synindex @var{from-index} @var{into-index}
+Merge the index named in the first argument into the index named in
+the second argument. Do not change the font of @var{from-index}
+entries. @xref{Combining address@hidden
+
address@hidden @@address@hidden@address@hidden
+Print @var{text} in a @t{fixed-width}, typewriter-like font.
+No effect in Info. @address@hidden
+
address@hidden @@tab
+Separate columns in a multitable. @xref{Multitable Rows}.
+
address@hidden @@table @var{formatting-command}
+Begin a two-column table, using @code{@@item} for each entry. Write
+each first column entry on the same line as @code{@@item}. First
+column entries are printed in the font resulting from
address@hidden Pair with @code{@@end table}.
address@hidden Tables, , Making a Two-column Table}.
+Also see @ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}},
+and @ref{itemx, , @code{@@address@hidden
+
address@hidden @@address@hidden@}
+Insert the logo @TeX{}. @xref{TeX and copyright, , Inserting @TeX{}
+and @address@hidden
+
address@hidden @@tex
+Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Raw
+Formatter Commands}.
+
address@hidden @@thischapter
address@hidden @@thischaptername
address@hidden @@thisfile
address@hidden @@thispage
address@hidden @@thistitle
+Only allowed in a heading or footing. Stands for the number and name of
+the current chapter (in the format `Chapter 1: Title'), the chapter name
+only, the filename, the current page number, and the title of the
+document, respectively. @xref{Custom Headings, , How to Make Your Own
address@hidden
+
address@hidden @@address@hidden@address@hidden
+Generate a tie-after accent over the next two characters @var{cc}, as in
address@hidden'. @xref{Inserting Accents}.
+
address@hidden @@tindex @var{entry}
+Add @var{entry} to the index of data types. @xref{Index Entries, ,
+Defining the Entries of an address@hidden
+
address@hidden @@title @var{title}
+In a printed manual, set a title flush to the left-hand side of the
+page in a larger than normal font and underline it with a black rule.
+Not relevant to Info, which does not have title pages. @xref{title
+subtitle author, , The @code{@@title} @code{@@subtitle} and
address@hidden@@author} address@hidden
+
address@hidden @@address@hidden@address@hidden
+In a printed manual, print @var{text} in a larger than normal font.
+Not relevant to Info, which does not have title pages.
address@hidden center sp, , The @code{@@titlefont} @code{@@center}
+and @code{@@sp} address@hidden
+
address@hidden @@titlepage
+Indicate to Texinfo the beginning of the title page. Write command on
+a line of its own. Pair with @code{@@end titlepage}. Nothing between
address@hidden@@titlepage} and @code{@@end titlepage} appears in Info.
address@hidden, , @code{@@address@hidden
+
address@hidden @@address@hidden@}
+Insert the current date, in `1 Jan 1900' style. @xref{Custom
+Headings, , How to Make Your Own address@hidden
+
address@hidden @@top @var{title}
+In a Texinfo file to be formatted with @code{makeinfo}, identify the
+topmost @code{@@node} in the file, which must be written on the line
+immediately preceding the @code{@@top} command. Used for
address@hidden's node pointer insertion feature. The title is
+underlined with asterisks. Both the @code{@@node} line and the @code{@@top}
+line normally should be enclosed by @code{@@ifnottex} and @code{@@end
+ifnottex}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
+command is merely a synonym for @code{@@unnumbered}. @xref{makeinfo
+Pointer Creation, , Creating Pointers with @code{makeinfo}}.
+
address@hidden @@address@hidden@address@hidden
address@hidden @@address@hidden@address@hidden
address@hidden @@address@hidden@address@hidden
+Generate a breve, underbar, or underdot accent, respectively, over or
+under the character @var{c}, as in @u{o}, @ubaraccent{o},
address@hidden @xref{Inserting Accents}.
+
address@hidden @@unnumbered @var{title}
+In a printed manual, begin a chapter that appears without chapter
+numbers of any kind. The title appears in the table of contents of a
+printed manual. In Info, the title is underlined with asterisks.
address@hidden & appendix, , @code{@@unnumbered} and
address@hidden@@address@hidden
+
address@hidden @@unnumberedsec @var{title}
+In a printed manual, begin a section that appears without section
+numbers of any kind. The title appears in the table of contents of a
+printed manual. In Info, the title is underlined with equal signs.
address@hidden appendixsec heading, , Section address@hidden
+
address@hidden @@unnumberedsubsec @var{title}
+In a printed manual, begin an unnumbered subsection within a
+chapter. The title appears in the table of contents of a printed
+manual. In Info, the title is underlined with hyphens.
address@hidden appendixsubsec subheading, ,
address@hidden@@unnumberedsubsec} @code{@@appendixsubsec}
address@hidden@@address@hidden
+
address@hidden @@unnumberedsubsubsec @var{title}
+In a printed manual, begin an unnumbered subsubsection within a
+chapter. The title appears in the table of contents of a printed
+manual. In Info, the title is underlined with periods.
address@hidden, , The `subsub' address@hidden
+
address@hidden @@address@hidden@var{url}[, @var{displayed-text}][,
@address@hidden
+Define a cross reference to an external uniform resource locator for the
+World Wide Web. @xref{uref, , @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Indicate text that is a uniform resource locator for the World Wide
+Web. @xref{url, , @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Generate check accent over the character @var{c}, as in @v{o}.
address@hidden Accents}.
+
address@hidden @@address@hidden@address@hidden
+Replace @var{flag} with the value to which it is set by @code{@@set
address@hidden
address@hidden clear value, , @code{@@set} @code{@@clear} @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Highlight a metasyntactic variable, which is something that stands for
+another piece of text. @xref{var, , Indicating Metasyntactic
address@hidden
+
address@hidden @@address@hidden@var{delim} @var{literal} @address@hidden
+Output @var{literal}, delimited by the single character @var{delim},
+exactly as is (in the fixed-width font), including any whitespace or
+Texinfo special characters. @xref{verb,,@code{verb}}.
+
address@hidden @@verbatim
+Output the text of the environment exactly as is (in the fixed-width
+font). Pair with @code{@@end verbatim}. @xref{verbatim,,@code{verbatim}}.
+
address@hidden @@verbatiminclude @var{filename}
+Output the contents of @var{filename} exactly as is (in the fixed-width font).
address@hidden,,@code{verbatiminclude}}.
+
address@hidden @@vindex @var{entry}
+Add @var{entry} to the index of variables. @xref{Index Entries, ,
+Defining the Entries of an address@hidden
+
address@hidden @@vskip @var{amount}
+In a printed manual, insert whitespace so as to push text on the
+remainder of the page towards the bottom of the page. Used in
+formatting the copyright page with the argument @samp{0pt plus
+1filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used
+only in contexts ignored for Info. @xref{Copyright}.
+
address@hidden @@vtable @var{formatting-command}
+Begin a two-column table, using @code{@@item} for each entry.
+Automatically enter each of the items in the first column into the
+index of variables. Pair with @code{@@end vtable}. The same as
address@hidden@@table}, except for indexing. @xref{ftable vtable, ,
address@hidden@@ftable} and @code{@@address@hidden
+
address@hidden @@address@hidden@address@hidden
+Prevent @var{text} from being split across two lines. Do not end a
+paragraph that uses @code{@@w} with an @code{@@refill} command.
address@hidden, , @code{@@address@hidden
+
address@hidden @@address@hidden@var{node-name}, address@hidden, address@hidden,
address@hidden, address@hidden@}
+Make a reference that starts with `See' in a printed manual. Follow
+command with a punctuation mark. Only the first argument is
+mandatory. @xref{xref, , @code{@@address@hidden
address@hidden table
+
+
address@hidden Tips
address@hidden Tips and Hints
+
+Here are some tips for writing Texinfo documentation:@refill
+
address@hidden Tips
address@hidden Usage tips
address@hidden Hints
address@hidden @bullet
address@hidden
+Write in the present tense, not in the past or the future.
+
address@hidden
+Write actively! For example, write ``We recommend that @dots{}'' rather
+than ``It is recommended that @dots{}''.
+
address@hidden
+Use 70 or 72 as your fill column. Longer lines are hard to read.
+
address@hidden
+Include a copyright notice and copying permissions.
address@hidden itemize
+
address@hidden Index, Index, Index!
+
+Write many index entries, in different ways.
+Readers like indices; they are helpful and convenient.
+
+Although it is easiest to write index entries as you write the body of
+the text, some people prefer to write entries afterwards. In either
+case, write an entry before the paragraph to which it applies. This
+way, an index entry points to the first page of a paragraph that is
+split across pages.
+
+Here are more hints we have found valuable:
+
address@hidden @bullet
address@hidden
+Write each index entry differently, so each entry refers to a different
+place in the document.
+
address@hidden
+Write index entries only where a topic is discussed significantly. For
+example, it is not useful to index ``debugging information'' in a
+chapter on reporting bugs. Someone who wants to know about debugging
+information will certainly not find it in that chapter.
+
address@hidden
+Consistently capitalize the first word of every concept index entry,
+or else consistently use lower case. Terse entries often call for
+lower case; longer entries for capitalization. Whichever case
+convention you use, please use one or the other consistently! Mixing
+the two styles looks bad.
+
address@hidden
+Always capitalize or use upper case for those words in an index for
+which this is proper, such as names of countries or acronyms. Always
+use the appropriate case for case-sensitive names, such as those in C or
+Lisp.
+
address@hidden
+Write the indexing commands that refer to a whole section immediately
+after the section command, and write the indexing commands that refer to
+a paragraph before that paragraph.
+
+In the example that follows, a blank line comes after the index
+entry for ``Leaping'':
+
address@hidden
address@hidden
+@@section The Dog and the Fox
+@@cindex Jumping, in general
+@@cindex Leaping
+
+@@cindex Dog, lazy, jumped over
+@@cindex Lazy dog jumped over
+@@cindex Fox, jumps over dog
+@@cindex Quick fox jumps over dog
+The quick brown fox jumps over the lazy dog.
address@hidden group
address@hidden example
+
address@hidden
+(Note that the example shows entries for the same concept that are
+written in different address@hidden dog}, and @samp{Dog, lazy}---so
+readers can look up the concept in different ways.)
address@hidden itemize
+
address@hidden Blank Lines
+
address@hidden @bullet
address@hidden
+Insert a blank line between a sectioning command and the first following
+sentence or paragraph, or between the indexing commands associated with
+the sectioning command and the first following sentence or paragraph, as
+shown in the tip on indexing. Otherwise, a formatter may fold title and
+paragraph together.
+
address@hidden
+Always insert a blank line before an @code{@@table} command and after an
address@hidden@@end table} command; but never insert a blank line after an
address@hidden@@table} command or before an @code{@@end table} command.
+
address@hidden 1000
+For example,
+
address@hidden
address@hidden
+Types of fox:
+
+@@table @@samp
+@@item Quick
+Jump over lazy dogs.
address@hidden group
+
address@hidden
+@@item Brown
+Also jump over lazy dogs.
+@@end table
+
address@hidden group
address@hidden
+@@noindent
+On the other hand, @dots{}
address@hidden group
address@hidden example
+
+Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end
+itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the
+same way.
address@hidden itemize
+
address@hidden Complete Phrases
+
+Complete phrases are easier to read than @dots{}
+
address@hidden @bullet
address@hidden
+Write entries in an itemized list as complete sentences; or at least, as
+complete phrases. Incomplete expressions @dots{} awkward @dots{} like
+this.
+
address@hidden
+Write the prefatory sentence or phrase for a multi-item list or table as
+a complete expression. Do not write ``You can set:''; instead, write
+``You can set these variables:''. The former expression sounds cut off.
address@hidden itemize
+
address@hidden Editions, Dates and Versions
+
+Include edition numbers, version numbers, and dates in the
address@hidden@@copying} text (for people reading the Texinfo file, and for the
+legal copyright in the output files). Then use @code{@@insertcopying}
+in the @code{@@titlepage} section (for people reading the printed
+output) and the Top node (for people reading the online output).
+
+It is easiest to do this using @code{@@set} and @code{@@value}.
address@hidden Example, , @code{@@value} Example}, and @ref{GNU Sample Texts}.
+
+
address@hidden Definition Commands
+
+Definition commands are @code{@@deffn}, @code{@@defun},
address@hidden@@defmac}, and the like, and enable you to write descriptions in
+a uniform address@hidden
+
address@hidden @bullet
address@hidden
+Write just one definition command for each entity you define with a
+definition command. The automatic indexing feature creates an index
+entry that leads the reader to the definition.
+
address@hidden
+Use @code{@@table} @dots{} @code{@@end table} in an appendix that
+contains a summary of functions, not @code{@@deffn} or other definition
+commands.
address@hidden itemize
+
address@hidden Capitalization
+
address@hidden @bullet
address@hidden
+Capitalize ``Texinfo''; it is a name. Do not write the @samp{x} or
address@hidden in upper case.
+
address@hidden
+Capitalize ``Info''; it is a name.
+
address@hidden
+Write @TeX{} using the @code{@@address@hidden@}} command. Note the uppercase
address@hidden and @samp{X}. This command causes the formatters to
+typeset the name according to the wishes of Donald Knuth, who wrote
address@hidden
address@hidden itemize
+
address@hidden Spaces
+
+Do not use spaces to format a Texinfo file, except inside of
address@hidden@@example} @dots{} @code{@@end example} and similar commands.
+
address@hidden 700
+For example, @TeX{} fills the following:
+
address@hidden
address@hidden
+ @@address@hidden address@hidden
+ @@address@hidden address@hidden
+ Perform the next logical operation
+ on the version-controlled file
+ corresponding to the current buffer.
address@hidden group
address@hidden example
+
address@hidden 950
address@hidden
+so it looks like this:
+
address@hidden
+`C-x v' `M-x vc-next-action' Perform the next logical operation on the
+version-controlled file corresponding to the current buffer.
address@hidden quotation
+
address@hidden
+In this case, the text should be formatted with
address@hidden@@table}, @code{@@item}, and @code{@@itemx}, to create a table.
+
address@hidden @@code, @@samp, @@var, and @samp{---}
+
address@hidden @bullet
address@hidden
+Use @code{@@code} around Lisp symbols, including command names.
+For example,
+
address@hidden
+The main function is @@address@hidden@}, @dots{}
address@hidden example
+
address@hidden
+Avoid putting letters such as @samp{s} immediately after an
address@hidden@@code}. Such letters look bad.
+
address@hidden
+Use @code{@@var} around meta-variables. Do not write angle brackets
+around them.
+
address@hidden
+Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{}
+typesets these as a long dash and the Info formatters reduce three
+hyphens to two.
address@hidden itemize
+
address@hidden Periods Outside of Quotes
+
+Place periods and other punctuation marks @emph{outside} of quotations,
+unless the punctuation is part of the quotation. This practice goes
+against publishing conventions in the United States, but enables the
+reader to distinguish between the contents of the quotation and the
+whole passage.
+
+For example, you should write the following sentence with the period
+outside the end quotation marks:
+
address@hidden
+Evidently, @samp{au} is an abbreviation for ``author''.
address@hidden example
+
address@hidden
+since @samp{au} does @emph{not} serve as an abbreviation for
address@hidden (with a period following the word).
+
address@hidden Introducing New Terms
+
address@hidden @bullet
address@hidden
+Introduce new terms so that a reader who does not know them can
+understand them from context; or write a definition for the term.
+
+For example, in the following, the terms ``check in'', ``register'' and
+``delta'' are all appearing for the first time; the example sentence should be
+rewritten so they are understandable.
+
address@hidden
+The major function assists you in checking in a file to your
+version control system and registering successive sets of changes to
+it as deltas.
address@hidden quotation
+
address@hidden
+Use the @code{@@dfn} command around a word being introduced, to indicate
+that the reader should not expect to know the meaning already, and
+should expect to learn the meaning from this passage.
address@hidden itemize
+
address@hidden @@pxref
+
address@hidden !!! maybe include this in the tips on pxref
+Absolutely never use @code{@@pxref} except in the special context for
+which it is designed: inside parentheses, with the closing parenthesis
+following immediately after the closing brace. One formatter
+automatically inserts closing punctuation and the other does not. This
+means that the output looks right both in printed output and in an Info
+file, but only when the command is used inside parentheses.
+
address@hidden Invoking from a Shell
+
+You can invoke programs such as Emacs, GCC, and @code{gawk} from a
+shell. The documentation for each program should contain a section that
+describes this. Unfortunately, if the node names and titles for these
+sections are all different, they are difficult for users to find.
+
+So, there is a convention to name such sections with a phrase beginning
+with the word `Invoking', as in `Invoking Emacs'; this way, users can
+find the section easily.
+
+
address@hidden ANSI C Syntax
+
+When you use @code{@@example} to describe a C function's calling
+conventions, use the ANSI C syntax, like this:@refill
+
address@hidden
+void dld_init (char *@@address@hidden@});
address@hidden example
+
address@hidden
+And in the subsequent discussion, refer to the argument values by
+writing the same argument names, again highlighted with
address@hidden@@address@hidden
+
address@hidden 800
+Avoid the obsolete style that looks like this:@refill
+
address@hidden
+#include <dld.h>
+
+dld_init (path)
+char *path;
address@hidden example
+
+Also, it is best to avoid writing @code{#include} above the
+declaration just to indicate that the function is declared in a
+header file. The practice may give the misimpression that the
address@hidden belongs near the declaration of the function. Either
+state explicitly which header file holds the declaration or, better
+yet, name the header file used for a group of functions at the
+beginning of the section that describes the address@hidden
+
address@hidden Bad Examples
+
+Here are several examples of bad writing to avoid:
+
+In this example, say, `` @dots{} you must @code{@@address@hidden
address@hidden the new version.'' That flows better.
+
address@hidden
+When you are done editing the file, you must perform a
address@hidden@@address@hidden address@hidden
address@hidden quotation
+
+In the following example, say, address@hidden makes a unified interface such
as VC
+mode possible.''
+
address@hidden
+SCCS, RCS and other version-control systems all perform similar
+functions in broadly similar ways (it is this resemblance which makes
+a unified control mode like this possible).
address@hidden quotation
+
+And in this example, you should specify what `it' refers to:
+
address@hidden
+If you are working with other people, it assists in coordinating
+everyone's changes so they do not step on each other.
address@hidden quotation
+
address@hidden And Finally @dots{}
+
address@hidden @bullet
address@hidden
+Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last
+sound in the name `Bach'. But pronounce Texinfo as in `speck':
+``teckinfo''.
+
address@hidden
+Write notes for yourself at the very end of a Texinfo file after the
address@hidden@@bye}. None of the formatters process text after the
address@hidden@@bye}; it is as if the text were within @code{@@ignore} @dots{}
address@hidden@@end ignore}.
address@hidden itemize
+
+
address@hidden Sample Texinfo Files
address@hidden Sample Texinfo Files
address@hidden Sample Texinfo files
+
+The first example is from the first chapter (@pxref{Short Sample}),
+given here in its entirety, without commentary. The second sample
+includes the full texts to be used in GNU manuals.
+
address@hidden
+* Short Sample Texinfo File::
+* GNU Sample Texts::
address@hidden menu
+
+
address@hidden Short Sample Texinfo File
address@hidden Short Sample
address@hidden Sample Texinfo file, no comments
+
+Here is a complete, short sample Texinfo file, without any commentary.
+You can see this file, with comments, in the first chapter. @xref{Short
+Sample}.
+
+In a nutshell: The @command{makeinfo} program transforms a Texinfo
+source file such as this into an Info file or HTML; and @TeX{} typesets
+it for a printed manual.
+
+
address@hidden 1
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@c %**start of header
+@@setfilename sample.info
+@@settitle Sample Manual 1.0
+@@c %**end of header
+
+@@copying
+This is a short example of a complete Texinfo file.
+
+Copyright (C) 2002 Free Software Foundation, Inc.
+@@end copying
+
+@@titlepage
+@@title Sample Title
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
+@@end titlepage
+
+@@c Output the table of the contents at the beginning.
+@@contents
+
+@@ifnottex
+@@node Top
+
+@@insertcopying
+@@end ifnottex
+
+@@menu
+* First Chapter:: The first chapter is the
+ only chapter in this sample.
+* Index:: Complete index.
+@@end menu
+
+
+@@node First Chapter
+@@chapter First Chapter
+
+@@cindex chapter, first
+
+This is the first chapter.
+@@cindex index entry, another
+
+Here is a numbered list.
+
+@@enumerate
+@@item
+This is the first item.
+
+@@item
+This is the second item.
+@@end enumerate
+
+
+@@node Index
+@@unnumbered Index
+
+@@printindex cp
+
+@@bye
address@hidden example
+
+
address@hidden GNU Sample Texts
address@hidden GNU Sample Texts
+
address@hidden GNU sample texts
address@hidden Sample texts, GNU
address@hidden Full texts, GNU
+
+Here 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.
+
address@hidden Sample}, for a minimal example of a Texinfo file.
address@hidden a File}, for a full explanation of that minimal
+example.
+
+Here are some notes on the example:
+
address@hidden @bullet
address@hidden
address@hidden $ @c Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $
comment
address@hidden CVS Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $, in
Texinfo
address@hidden RCS Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $, in
Texinfo
+The @samp{Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $} comment is
for CVS (@pxref{Top,, Overview, cvs,
+Concurrent Versions System}) or RCS (see rcsintro(1)) version control
+systems, which expand it into a string such as:
address@hidden
+Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $
address@hidden example
+(This is useful in all sources that use version control, not just manuals.)
+
address@hidden
address@hidden address@hidden, and version info}
+The @file{version.texi} in the @code{@@include} command is maintained
+automatically by Automake (@pxref{Top,, Introduction, automake, GNU
+Automake}). It sets the @samp{VERSION} and @samp{UPDATED} values used
+elsewhere. If your distribution doesn't use Automake, you can mimic
+these or equivalent settings.
+
address@hidden
+The @code{@@syncodeindex} command reflects the recommendation to use only
+one index if at all possible, to make it easier for readers.
+
address@hidden
+The @code{@@dircategory} is for constructing the Info directory.
address@hidden Dir Entries}, which includes a variety of recommended
+category names.
+
address@hidden
+The `Invoking' node is a GNU standard to help users find the basic
+information about command-line usage of a given program. @xref{Manual
+Structure Details,,,standards, GNU Coding Standards}.
+
address@hidden
+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 of doing so. The @file{fdl.texi}
+file is available on the GNU machines (and in the Texinfo and other GNU
+distributions).
+
+The FDL provides for omitting itself under certain conditions, but in
+that case the sample texts given here have to be modified. @xref{GNU
+Free Documentation License}.
+
address@hidden
+If your manual has invariant sections (again, see the license itself for
+details), then don't forget to include them.
address@hidden itemize
+
+Here is the sample document:
+
address@hidden We do the first part of this with @example instead of @verbatim
address@hidden because the literal @setfilename and @include confuse Automake.
Argh.
address@hidden
+\input texinfo @@c -*-texinfo-*-
+@@comment Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $
+@@comment %**start of header
+@@setfilename sample.info
+@@include version.texi
+@@settitle GNU Sample @@address@hidden@}
+@@syncodeindex pg cp
+@@comment %**end of header
+@@copying
+This manual is for GNU Sample
+(version @@address@hidden@}, @@address@hidden@}),
+which is an example in the Texinfo documentation.
+
+Copyright @@address@hidden@} 2002 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 @@address@hidden@}, @@address@hidden@}
+@@author A.U. Thor (@@address@hidden@@@@address@hidden)
+@@page
+@@vskip 0pt plus 1filll
+@@insertcopying
+@@end titlepage
+
+@@contents
+
+@@ifnottex
+@@node Top
+@@top GNU Sample
+
+@@insertcopying
+@@end ifnottex
+
+@@menu
+* Invoking sample::
+* Copying This Manual::
+* Index::
+@@end menu
+
+
+@@node Invoking sample
+@@chapter Invoking sample
+
+@@pindex sample
+@@cindex invoking @@address@hidden@}
+
+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
address@hidden example
+
+
address@hidden Include Files
address@hidden Include Files
address@hidden Include files
+
+When @TeX{} or an Info formatting command sees an @code{@@include}
+command in a Texinfo file, it processes the contents of the file named
+by the command and incorporates them into the DVI or Info file being
+created. Index entries from the included file are incorporated into
+the indices of the output file.
+
+Include files let you keep a single large document as a collection of
+conveniently small parts.
+
address@hidden
+* Using Include Files:: How to use the @code{@@include} command.
+* texinfo-multiple-files-update:: How to create and update nodes and
+ menus when using included files.
+* Include File Requirements:: What @code{texinfo-multiple-files-update}
expects.
+* 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.
address@hidden menu
+
address@hidden Using Include Files, texinfo-multiple-files-update, Include
Files, Include Files
address@hidden How to Use Include Files
address@hidden include
+
+To include another file within a Texinfo file, write the
address@hidden@@include} command at the beginning of a line and follow it on
+the same line by the name of a file to be included. For
+example:@refill
+
address@hidden
+@@include buffers.texi
address@hidden example
+
+An included file should simply be a segment of text that you expect to
+be included as is into the overall or @dfn{outer} Texinfo file; it
+should not contain the standard beginning and end parts of a Texinfo
+file. In particular, you should not start an included file with a
+line saying @samp{\input texinfo}; if you do, that phrase is inserted
+into the output file as is. Likewise, you should not end an included
+file with an @code{@@bye} command; nothing after @code{@@bye} is
address@hidden
+
+In the past, you were required to write an @code{@@setfilename} line at the
+beginning of an included file, but no longer. Now, it does not matter
+whether you write such a line. If an @code{@@setfilename} line exists
+in an included file, it is address@hidden
+
+Conventionally, an included file begins with an @code{@@node} line that
+is followed by an @code{@@chapter} line. Each included file is one
+chapter. This makes it easy to use the regular node and menu creating
+and updating commands to create the node pointers and menus within the
+included file. However, the simple Emacs node and menu creating and
+updating commands do not work with multiple Texinfo files. Thus you
+cannot use these commands to fill in the `Next', `Previous', and `Up'
+pointers of the @code{@@node} line that begins the included file. Also,
+you cannot use the regular commands to create a master menu for the
+whole file. Either you must insert the menus and the `Next',
+`Previous', and `Up' pointers by hand, or you must use the GNU Emacs
+Texinfo mode command, @code{texinfo-multiple-files-update}, that is
+designed for @code{@@include} address@hidden
+
address@hidden texinfo-multiple-files-update, Include File Requirements, Using
Include Files, Include Files
address@hidden @code{texinfo-multiple-files-update}
address@hidden texinfo-multiple-files-update
+
+GNU Emacs Texinfo mode provides the @code{texinfo-multiple-files-update}
+command. This command creates or updates `Next', `Previous', and `Up'
+pointers of included files as well as those in the outer or overall
+Texinfo file, and it creates or updates a main menu in the outer file.
+Depending whether you call it with optional arguments, the command
+updates only the pointers in the first @code{@@node} line of the
+included files or all of them:@refill
+
address@hidden @kbd
address@hidden M-x texinfo-multiple-files-update
+Called without any arguments:@refill
+
address@hidden @minus
address@hidden
+Create or update the `Next', `Previous', and `Up' pointers of the
+first @code{@@node} line in each file included in an outer or overall
+Texinfo address@hidden
+
address@hidden
+Create or update the `Top' level node pointers of the outer or
+overall address@hidden
+
address@hidden
+Create or update a main menu in the outer address@hidden
address@hidden itemize
+
address@hidden C-u M-x texinfo-multiple-files-update
+Called with @kbd{C-u} as a prefix argument:
+
address@hidden @minus{}
address@hidden
+Create or update pointers in the first @code{@@node} line in each
+included file.
+
address@hidden
+Create or update the `Top' level node pointers of the outer file.
+
address@hidden
+Create and insert a master menu in the outer file. The master menu
+is made from all the menus in all the included address@hidden
address@hidden itemize
+
address@hidden C-u 8 M-x texinfo-multiple-files-update
+Called with a numeric prefix argument, such as @kbd{C-u 8}:
+
address@hidden @minus
address@hidden
+Create or update @strong{all} the `Next', `Previous', and `Up' pointers
+of all the included address@hidden
+
address@hidden
+Create or update @strong{all} the menus of all the included
address@hidden
+
address@hidden
+Create or update the `Top' level node pointers of the outer or
+overall address@hidden
+
address@hidden
+And then create a master menu in the outer file. This is similar to
+invoking @code{texinfo-master-menu} with an argument when you are
+working with just one address@hidden
address@hidden itemize
address@hidden table
+
+Note the use of the prefix argument in interactive use: with a regular
+prefix argument, just @address@hidden, the
address@hidden command inserts a master menu;
+with a numeric prefix argument, such as @kbd{C-u 8}, the command
+updates @strong{every} pointer and menu in @strong{all} the files and then
inserts a
+master address@hidden
+
+
address@hidden Include File Requirements
address@hidden Include File Requirements
address@hidden Include file requirements
address@hidden Requirements for include files
+
+If you plan to use the @code{texinfo-multiple-files-update} command,
+the outer Texinfo file that lists included files within it should
+contain nothing but the beginning and end parts of a Texinfo file, and
+a number of @code{@@include} commands listing the included files. It
+should not even include indices, which should be listed in an included
+file of their address@hidden
+
+Moreover, each of the included files must contain exactly one highest
+level node (conventionally, @code{@@chapter} or equivalent),
+and this node must be the first node in the included file.
+Furthermore, each of these highest level nodes in each included file
+must be at the same hierarchical level in the file structure.
+Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an
address@hidden@@unnumbered} node. Thus, normally, each included file contains
+one, and only one, chapter or equivalent-level address@hidden
+
+The outer file should contain only @emph{one} node, the `Top' node. It
+should @emph{not} contain any nodes besides the single `Top' node. The
address@hidden command will not process
address@hidden
+
address@hidden Sample Include File, Include Files Evolution, Include File
Requirements, Include Files
address@hidden Sample File with @code{@@include}
address@hidden Sample @code{@@include} file
address@hidden Include file sample
address@hidden @code{@@include} file sample
+
+Here is an example of a complete outer Texinfo file with @code{@@include} files
+within it before running @code{texinfo-multiple-files-update}, which
+would insert a main or master menu:@refill
+
address@hidden
address@hidden
+\input texinfo @@c -*-texinfo-*-
address@hidden %**start of header
+@@setfilename include-example.info
+@@settitle Include Example
address@hidden %**end of header
address@hidden group
+
address@hidden
+@@setchapternewpage odd
+@@titlepage
+@@sp 12
+@@center @@address@hidden address@hidden
+@@sp 2
+@@center by Whom Ever
address@hidden group
+
address@hidden
+@@page
+@@vskip 0pt plus 1filll
+Copyright @@address@hidden@} 2002 Free Software Foundation, Inc.
+@@end titlepage
address@hidden group
+
address@hidden
+@@ifinfo
+@@node Top, First, , (dir)
+@@top Master Menu
+@@end ifinfo
address@hidden group
+
address@hidden
+@@include foo.texinfo
+@@include bar.texinfo
+@@include concept-index.texinfo
address@hidden group
+
address@hidden
+@@summarycontents
+@@contents
+
+@@bye
address@hidden group
address@hidden example
+
+An included file, such as @file{foo.texinfo}, might look like this:
+
address@hidden
address@hidden
+@@node First, Second, , Top
+@@chapter First Chapter
+
+Contents of first chapter @dots{}
address@hidden group
address@hidden example
+
+The full contents of @file{concept-index.texinfo} might be as simple as this:
+
address@hidden
address@hidden
+@@node Concept Index
+@@unnumbered Concept Index
+
+@@printindex cp
address@hidden group
address@hidden example
+
+The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference
+Manual} is named @file{elisp.texi}. This outer file contains a master
+menu with 417 entries and a list of 41 @code{@@include}
address@hidden
+
+
address@hidden Include Files Evolution
address@hidden Evolution of Include Files
+
+When Info was first created, it was customary to create many small
+Info files on one subject. Each Info file was formatted from its own
+Texinfo source file. This custom meant that Emacs did not need to
+make a large buffer to hold the whole of a large Info file when
+someone wanted information; instead, Emacs allocated just enough
+memory for the small Info file that contained the particular
+information sought. This way, Emacs could avoid wasting address@hidden
+
+References from one file to another were made by referring to the file
+name as well as the node name. (@xref{Other Info Files, , Referring to
+Other Info Files}. Also, see @ref{Four and Five Arguments, ,
address@hidden@@xref} with Four and Five Arguments}.)@refill
+
+Include files were designed primarily as a way to create a single,
+large printed manual out of several smaller Info files. In a printed
+manual, all the references were within the same document, so @TeX{}
+could automatically determine the references' page numbers. The Info
+formatting commands used include files only for creating joint
+indices; each of the individual Texinfo files had to be formatted for
+Info individually. (Each, therefore, required its own
address@hidden@@setfilename} line.)@refill
+
+However, because large Info files are now split automatically, it is
+no longer necessary to keep them address@hidden
+
+Nowadays, multiple Texinfo files are used mostly for large documents,
+such as @cite{The GNU Emacs Lisp Reference Manual}, and for projects
+in which several different people write different sections of a
+document address@hidden
+
+In addition, the Info formatting commands have been extended to work
+with the @code{@@include} command so as to create a single large Info
+file that is split into smaller files if necessary. This means that
+you can write menus and cross references without naming the different
+Texinfo address@hidden
+
+
address@hidden Headings
address@hidden Page Headings
address@hidden Headings
address@hidden Footings
address@hidden Page numbering
address@hidden Page headings
address@hidden Formatting headings and footings
+
+Most printed manuals contain headings along the top of every page
+except the title and copyright pages. Some manuals also contain
+footings. (Headings and footings have no meaning to Info, which is
+not paginated.)@refill
+
address@hidden
+* 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.
address@hidden menu
+
address@hidden Headings Introduced, Heading Format, Headings, Headings
address@hidden Headings Introduced
+
+Texinfo provides standard page heading formats for manuals that are
+printed on one side of each sheet of paper and for manuals that are
+printed on both sides of the paper. Typically, you will use these
+formats, but you can specify your own format if you address@hidden
+
+In addition, you can specify whether chapters should begin on a new
+page, or merely continue the same page as the previous chapter; and if
+chapters begin on new pages, you can specify whether they must be
+odd-numbered address@hidden
+
+By convention, a book is printed on both sides of each sheet of paper.
+When you open a book, the right-hand page is odd-numbered, and
+chapters begin on right-hand pages---a preceding left-hand page is
+left blank if necessary. Reports, however, are often printed on just
+one side of paper, and chapters begin on a fresh page immediately
+following the end of the preceding chapter. In short or informal
+reports, chapters often do not begin on a new page at all, but are
+separated from the preceding text by a small amount of address@hidden
+
+The @code{@@setchapternewpage} command controls whether chapters begin
+on new pages, and whether one of the standard heading formats is used.
+In addition, Texinfo has several heading and footing commands that you
+can use to generate your own heading and footing address@hidden
+
+In Texinfo, headings and footings are single lines at the tops and
+bottoms of pages; you cannot create multiline headings or footings.
+Each header or footer line is divided into three parts: a left part, a
+middle part, and a right part. Any part, or a whole line, may be left
+blank. Text for the left part of a header or footer line is set
+flushleft; text for the middle part is centered; and, text for the
+right part is set address@hidden
+
address@hidden Heading Format, Heading Choice, Headings Introduced, Headings
address@hidden node-name, next, previous, up
address@hidden Standard Heading Formats
+
+Texinfo provides two standard heading formats, one for manuals printed
+on one side of each sheet of paper, and the other for manuals printed
+on both sides of the paper.
+
+By default, nothing is specified for the footing of a Texinfo file,
+so the footing remains address@hidden
+
+The standard format for single-sided printing consists of a header
+line in which the left-hand part contains the name of the chapter, the
+central part is blank, and the right-hand part contains the page
address@hidden
+
address@hidden 950
+A single-sided page looks like this:
+
address@hidden
address@hidden
+ _______________________
+ | |
+ | chapter page number |
+ | |
+ | Start of text ... |
+ | ... |
+ | |
+
address@hidden group
address@hidden example
+
+The standard format for two-sided printing depends on whether the page
+number is even or odd. By convention, even-numbered pages are on the
+left- and odd-numbered pages are on the right. (@TeX{} will adjust the
+widths of the left- and right-hand margins. Usually, widths are
+correct, but during double-sided printing, it is wise to check that
+pages will bind properly---sometimes a printer will produce output in
+which the even-numbered pages have a larger right-hand margin than the
+odd-numbered pages.)@refill
+
+In the standard double-sided format, the left part of the left-hand
+(even-numbered) page contains the page number, the central part is
+blank, and the right part contains the title (specified by the
address@hidden@@settitle} command). The left part of the right-hand
+(odd-numbered) page contains the name of the chapter, the central part
+is blank, and the right part contains the page address@hidden
+
address@hidden 750
+Two pages, side by side as in an open book, look like this:@refill
+
address@hidden
address@hidden
+ _______________________ _______________________
+ | | | |
+ | page number title | | chapter page number |
+ | | | |
+ | Start of text ... | | More text ... |
+ | ... | | ... |
+ | | | |
+
address@hidden group
address@hidden example
+
address@hidden
+The chapter name is preceded by the word ``Chapter'', the chapter number
+and a colon. This makes it easier to keep track of where you are in the
address@hidden
+
address@hidden Heading Choice, Custom Headings, Heading Format, Headings
address@hidden node-name, next, previous, up
address@hidden Specifying the Type of Heading
+
address@hidden does not begin to generate page headings for a standard Texinfo
+file until it reaches the @code{@@end titlepage} command. Thus, the
+title and copyright pages are not numbered. The @code{@@end
+titlepage} command causes @TeX{} to begin to generate page headings
+according to a standard format specified by the
address@hidden@@setchapternewpage} command that precedes the
address@hidden@@titlepage} address@hidden
+
address@hidden 1000
+There are four possibilities:@refill
+
address@hidden @asis
address@hidden No @code{@@setchapternewpage} command
+Cause @TeX{} to specify the single-sided heading format, with chapters
+on new pages. This is the same as @code{@@setchapternewpage address@hidden
+
address@hidden @code{@@setchapternewpage on}
+Specify the single-sided heading format, with chapters on new address@hidden
+
address@hidden @code{@@setchapternewpage off}
+Cause @TeX{} to start a new chapter on the same page as the last page of
+the preceding chapter, after skipping some vertical whitespace. Also
+cause @TeX{} to typeset for single-sided printing. (You can override
+the headers format with the @code{@@headings double} command; see
address@hidden on off, , The @code{@@headings} Command}.)@refill
+
address@hidden @code{@@setchapternewpage odd}
+Specify the double-sided heading format, with chapters on new address@hidden
address@hidden table
+
address@hidden
+Texinfo lacks an @code{@@setchapternewpage even} address@hidden
+
address@hidden Custom Headings, , Heading Choice, Headings
address@hidden node-name, next, previous, up
address@hidden How to Make Your Own Headings
+
+You can use the standard headings provided with Texinfo or specify
+your own. By default, Texinfo has no footers, so if you specify them,
+the available page size for the main text will be slightly reduced.
+
+Texinfo provides six commands for specifying headings and
+footings:
address@hidden @bullet
address@hidden
address@hidden@@everyheading} @code{@@everyfooting} generate page headers and
+footers that are the same for both even- and odd-numbered pages.
address@hidden
address@hidden@@evenheading} and @code{@@evenfooting} command generate headers
+and footers for even-numbered (left-hand) pages.
address@hidden
address@hidden@@oddheading} and @code{@@oddfooting} generate headers and footers
+for odd-numbered (right-hand) pages.
address@hidden itemize
+
+Write custom heading specifications in the Texinfo file immediately
+after the @code{@@end titlepage} command.
+You must cancel the predefined heading commands with the
address@hidden@@headings off} command before defining your own
address@hidden
+
address@hidden 1000
+Here is how to tell @TeX{} to place the chapter name at the left, the
+page number in the center, and the date at the right of every header
+for both even- and odd-numbered pages:@refill
+
address@hidden
address@hidden
+@@headings off
+@@everyheading @@thischapter @@| @@thispage @@| @@address@hidden@}
address@hidden group
address@hidden example
+
address@hidden
+You need to divide the left part from the central part and the central
+part from the right part by inserting @samp{@@|} between parts.
+Otherwise, the specification command will not be able to tell where
+the text for one part ends and the next part address@hidden
+
+Each part can contain text or @@-commands. The text
+is printed as if the part were within an ordinary paragraph in the
+body of the page. The @@-commands replace
+themselves with the page number, date, chapter name, or
address@hidden
+
address@hidden 950
+Here are the six heading and footing commands:@refill
+
address@hidden everyheading
address@hidden everyfooting
address@hidden @code
address@hidden @@everyheading @var{left} @@| @var{center} @@| @var{right}
address@hidden @@everyfooting @var{left} @@| @var{center} @@| @var{right}
+
+The `every' commands specify the format for both even- and odd-numbered
+pages. These commands are for documents that are printed on one side
+of each sheet of paper, or for documents in which you want symmetrical
+headers or address@hidden
+
address@hidden evenheading
address@hidden evenfooting
address@hidden oddheading
address@hidden oddfooting
address@hidden @@evenheading @var{left} @@| @var{center} @@| @var{right}
address@hidden @@oddheading @var{left} @@| @var{center} @@| @var{right}
+
address@hidden @@evenfooting @var{left} @@| @var{center} @@| @var{right}
address@hidden @@oddfooting @var{left} @@| @var{center} @@| @var{right}
+
+The `even' and `odd' commands specify the format for even-numbered
+pages and odd-numbered pages. These commands are for books and
+manuals that are printed on both sides of each sheet of paper.
address@hidden table
+
+Use the @samp{@@address@hidden series of @@-commands to
+provide the names of chapters
+and sections and the page number. You can use the
address@hidden@@address@hidden commands in the left, center, or right portions
+of headers and footers, or anywhere else in a Texinfo file so long as
+they are between @code{@@iftex} and @code{@@end iftex} address@hidden
+
address@hidden 1000
+Here are the @samp{@@address@hidden commands:@refill
+
address@hidden @code
address@hidden thispage
address@hidden @@thispage
+Expands to the current page address@hidden
address@hidden !!! Karl Berry says that `thissection' can fail on page breaks.
+
address@hidden thischaptername
address@hidden @@thischaptername
+Expands to the name of the current address@hidden
+
address@hidden thischapter
address@hidden @@thischapter
+Expands to the number and name of the current
+chapter, in the format `Chapter 1: Title'address@hidden
+
address@hidden thistitle
address@hidden @@thistitle
+Expands to the name of the document, as specified by the
address@hidden@@settitle} address@hidden
+
address@hidden thisfile
address@hidden @@thisfile
+For @code{@@include} files only: expands to the name of the current
address@hidden@@include} file. If the current Texinfo source file is not an
address@hidden@@include} file, this command has no effect. This command does
address@hidden provide the name of the current Texinfo source file unless
+it is an @code{@@include} file. (@xref{Include Files}, for more
+information about @code{@@include} files.)@refill
address@hidden table
+
address@hidden
+You can also use the @code{@@address@hidden@}} command, which expands to the
+current date, in `1 Jan 1900' address@hidden
address@hidden today
+
+Other @@-commands and text are printed in a header or footer just as
+if they were in the body of a page. It is useful to incorporate text,
+particularly when you are writing drafts:@refill
+
address@hidden
address@hidden
+@@headings off
+@@everyheading @@address@hidden@} @@| @@thispage @@| @@thischapter
+@@everyfooting @@| @@| Version: 0.27: @@address@hidden@}
address@hidden group
address@hidden example
+
+Beware of overlong titles: they may overlap another part of the
+header or footer and blot it address@hidden
+
+
address@hidden Catching Mistakes
address@hidden Formatting Mistakes
address@hidden Structure, catching mistakes in
address@hidden Nodes, catching mistakes
address@hidden Catching mistakes
address@hidden Correcting mistakes
address@hidden Mistakes, catching
address@hidden Problems, catching
address@hidden Debugging the Texinfo structure
+
+Besides mistakes in the content of your documentation, there are two
+kinds of mistake you can make with Texinfo: you can make mistakes with
+@@-commands, and you can make mistakes with the structure of the nodes
+and chapters.
+
+Emacs has two tools for catching the @@-command mistakes and two for
+catching structuring address@hidden
+
+For finding problems with @@-commands, you can run @TeX{} or a region
+formatting command on the region that has a problem; indeed, you can
+run these commands on each region as you write address@hidden
+
+For finding problems with the structure of nodes and chapters, you can use
address@hidden C-s} (@code{texinfo-show-structure}) and the related @code{occur}
+command and you can use the @kbd{M-x Info-validate} address@hidden
+
address@hidden
+* 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 texinfo-show-structure:: How to use @code{texinfo-show-structure}.
+* Using occur:: How to list all lines containing a pattern.
+* Running Info-Validate:: How to find badly referenced nodes.
address@hidden menu
+
address@hidden makeinfo Preferred, Debugging with Info, Catching Mistakes,
Catching Mistakes
address@hidden @code{makeinfo} Find Errors
+
+The @code{makeinfo} program does an excellent job of catching errors
+and reporting them---far better than @code{texinfo-format-region} or
address@hidden In addition, the various functions for
+automatically creating and updating node pointers and menus remove
+many opportunities for human address@hidden
+
+If you can, use the updating commands to create and insert pointers
+and menus. These prevent many errors. Then use @code{makeinfo} (or
+its Texinfo mode manifestations, @code{makeinfo-region} and
address@hidden) to format your file and check for other
+errors. This is the best way to work with Texinfo. But if you
+cannot use @code{makeinfo}, or your problem is very puzzling, then you
+may want to use the tools described in this address@hidden
+
address@hidden Debugging with Info, Debugging with TeX, makeinfo Preferred,
Catching Mistakes
address@hidden node-name, next, previous, up
address@hidden Catching Errors with Info Formatting
address@hidden Catching errors with Info formatting
address@hidden Debugging with Info formatting
+
+After you have written part of a Texinfo file, you can use the
address@hidden or the @code{makeinfo-region} command to
+see whether the region formats address@hidden
+
+Most likely, however, you are reading this section because for some
+reason you cannot use the @code{makeinfo-region} command; therefore, the
+rest of this section presumes that you are using
address@hidden@refill
+
+If you have made a mistake with an @@-command,
address@hidden will stop processing at or after the
+error and display an error message. To see where in the buffer the
+error occurred, switch to the @samp{*Info Region*} buffer; the cursor
+will be in a position that is after the location of the error. Also,
+the text will not be formatted after the place where the error
+occurred (or more precisely, where it was detected)address@hidden
+
+For example, if you accidentally end a menu with the command @code{@@end
+menus} with an `s' on the end, instead of with @code{@@end menu}, you
+will see an error message that says:@refill
+
address@hidden
+@@end menus is not handled by texinfo
address@hidden example
+
address@hidden
+The cursor will stop at the point in the buffer where the error
+occurs, or not long after it. The buffer will look like this:@refill
+
address@hidden
address@hidden
+---------- Buffer: *Info Region* ----------
+* Menu:
+
+* Using texinfo-show-structure:: How to use
+ `texinfo-show-structure'
+ to catch mistakes.
+* Running Info-Validate:: How to check for
+ unreferenced nodes.
+@@end menus
address@hidden
+---------- Buffer: *Info Region* ----------
address@hidden group
address@hidden example
+
+The @code{texinfo-format-region} command sometimes provides slightly
+odd error messages. For example, the following cross reference fails to
format:@refill
+
address@hidden
+(@@address@hidden Mistakes, for more info.)
address@hidden example
+
address@hidden
+In this case, @code{texinfo-format-region} detects the missing closing
+brace but displays a message that says @samp{Unbalanced parentheses}
+rather than @samp{Unbalanced braces}. This is because the formatting
+command looks for mismatches between braces as if they were
address@hidden
+
+Sometimes @code{texinfo-format-region} fails to detect mistakes. For
+example, in the following, the closing brace is swapped with the
+closing parenthesis:@refill
+
address@hidden
+(@@address@hidden Mistakes), for more address@hidden
address@hidden example
+
address@hidden
+Formatting produces:
address@hidden
+(*Note for more info.: Catching Mistakes)
address@hidden example
+
+The only way for you to detect this error is to realize that the
+reference should have looked like this:@refill
+
address@hidden
+(*Note Catching Mistakes::, for more info.)
address@hidden example
+
+Incidentally, if you are reading this node in Info and type @kbd{f
address@hidden (@code{Info-follow-reference}), you will generate an error
+message that says:
+
address@hidden
+No such node: "Catching Mistakes) The only way @dots{}
address@hidden example
+
address@hidden
+This is because Info perceives the example of the error as the first
+cross reference in this node and if you type a @key{RET} immediately
+after typing the Info @kbd{f} command, Info will attempt to go to the
+referenced node. If you type @kbd{f catch @key{TAB} @key{RET}}, Info
+will complete the node name of the correctly written example and take
+you to the `Catching Mistakes' node. (If you try this, you can return
+from the `Catching Mistakes' node by typing @kbd{l}
+(@code{Info-last}).)
+
address@hidden !!! section on using Elisp debugger ignored.
+
address@hidden Debugging with TeX, Using texinfo-show-structure, Debugging with
Info, Catching Mistakes
address@hidden node-name, next, previous, up
address@hidden Catching Errors with @TeX{} Formatting
address@hidden Catching errors with @TeX{} formatting
address@hidden Debugging with @TeX{} formatting
+
+You can also catch mistakes when you format a file with @address@hidden
+
+Usually, you will want to do this after you have run
address@hidden (or, better, @code{makeinfo-buffer}) on
+the same file, because @code{texinfo-format-buffer} sometimes displays
+error messages that make more sense than @TeX{}. (@xref{Debugging
+with Info}, for more information.)@refill
+
+For example, @TeX{} was run on a Texinfo file, part of which is shown
+here:@refill
+
address@hidden
+---------- Buffer: texinfo.texi ----------
+name of the Texinfo file as an extension. The
+@@address@hidden@} are `wildcards' that cause the shell to
+substitute all the raw index files. (@@address@hidden
+indices, for more information about sorting
+indices.)@@refill
+---------- Buffer: texinfo.texi ----------
address@hidden example
+
address@hidden
+(The cross reference lacks a closing brace.)
address@hidden produced the following output, after which it stopped:@refill
+
address@hidden
+---------- Buffer: *tex-shell* ----------
+Runaway argument?
address@hidden indices, for more information about sorting
+indices.) @@refill @@ETC.
+! Paragraph ended before @@xref was complete.
+<to be read again>
+ @@par
+l.27
+
+?
+---------- Buffer: *tex-shell* ----------
address@hidden example
+
+In this case, @TeX{} produced an accurate and
+understandable error message:
+
address@hidden
+Paragraph ended before @@xref was complete.
address@hidden example
+
address@hidden
address@hidden@@par} is an internal @TeX{} command of no relevance to Texinfo.
address@hidden means that @TeX{} detected the problem on line 27 of the
+Texinfo file. The @samp{?} is the prompt @TeX{} uses in this
address@hidden
+
+Unfortunately, @TeX{} is not always so helpful, and sometimes you must
+truly be a Sherlock Holmes to discover what went address@hidden
+
+In any case, if you run into a problem like this, you can do one of three
address@hidden
+
address@hidden
address@hidden
+You can tell @TeX{} to continue running and ignore just this error by
+typing @key{RET} at the @samp{?} address@hidden
+
address@hidden
+You can tell @TeX{} to continue running and to ignore all errors as best
+it can by typing @kbd{r @key{RET}} at the @samp{?} address@hidden
+
+This is often the best thing to do. However, beware: the one error
+may produce a cascade of additional error messages as its consequences
+are felt through the rest of the file. To stop @TeX{} when it is
+producing such an avalanche of error messages, type @kbd{C-c} (or
address@hidden C-c}, if you are running a shell inside Emacs).
+
address@hidden
+You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}}
+at the @samp{?} address@hidden
address@hidden enumerate
+
+If you are running @TeX{} inside Emacs, you need to switch to the shell
+buffer and line at which @TeX{} offers the @samp{?} prompt.
+
+Sometimes @TeX{} will format a file without producing error messages even
+though there is a problem. This usually occurs if a command is not ended
+but @TeX{} is able to continue processing anyhow. For example, if you fail
+to end an itemized list with the @code{@@end itemize} command, @TeX{} will
+write a DVI file that you can print out. The only error message that
address@hidden will give you is the somewhat mysterious comment address@hidden
+
address@hidden
+(@@end occurred inside a group at level 1)
address@hidden example
+
address@hidden
+However, if you print the DVI file, you will find that the text
+of the file that follows the itemized list is entirely indented as if
+it were part of the last item in the itemized list. The error message
+is the way @TeX{} says that it expected to find an @code{@@end}
+command somewhere in the file; but that it could not determine where
+it was address@hidden
+
+Another source of notoriously hard-to-find errors is a missing
address@hidden@@end group} command. If you ever are stumped by
+incomprehensible errors, look for a missing @code{@@end group} command
address@hidden
+
+If the Texinfo file lacks header lines,
address@hidden may stop in the
+beginning of its run and display output that looks like the following.
+The @samp{*} indicates that @TeX{} is waiting for address@hidden
+
address@hidden
+This is TeX, Version 3.14159 (Web2c 7.0)
+(test.texinfo [1])
+*
address@hidden example
+
address@hidden
+In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then
+write the header lines in the Texinfo file and run the @TeX{} command
+again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\}
+instead of @samp{@@}; and in this circumstance, you are working
+directly with @TeX{}, not with Texinfo.)@refill
+
address@hidden Using texinfo-show-structure, Using occur, Debugging with TeX,
Catching Mistakes
address@hidden node-name, next, previous, up
address@hidden Using @code{texinfo-show-structure}
address@hidden Showing the structure of a file
address@hidden texinfo-show-structure
+
+It is not always easy to keep track of the nodes, chapters, sections, and
+subsections of a Texinfo file. This is especially true if you are revising
+or adding to a Texinfo file that someone else has address@hidden
+
+In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure}
+command lists all the lines that begin with the @@-commands that
+specify the structure: @code{@@chapter}, @code{@@section},
address@hidden@@appendix}, and so on. With an argument (@address@hidden
+as prefix argument, if interactive),
+the command also shows the @code{@@node} lines. The
address@hidden command is bound to @kbd{C-c C-s} in
+Texinfo mode, by address@hidden
+
+The lines are displayed in a buffer called the @samp{*Occur*} buffer,
+indented by hierarchical level. For example, here is a part of what was
+produced by running @code{texinfo-show-structure} on this manual:@refill
+
address@hidden
address@hidden
+ Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\|
+ unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
+ in buffer texinfo.texi.
+ @dots{}
+ 4177:@@chapter Nodes
+ 4198: @@heading Two Paths
+ 4231: @@section Node and Menu Illustration
+ 4337: @@section The @@address@hidden@@@@address@hidden Command
+ 4393: @@subheading Choosing Node and Pointer Names
+ 4417: @@subsection How to Write an @@address@hidden@@@@address@hidden
Line
+ 4469: @@subsection @@address@hidden@@@@address@hidden Line Tips
+ @dots{}
address@hidden group
address@hidden example
+
+This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin
+with the @code{@@section}, @code{@@subheading}, and @code{@@subsection}
+commands respectively. If you move your cursor into the @samp{*Occur*}
+window, you can position the cursor over one of the lines and use the
address@hidden C-c} command (@code{occur-mode-goto-occurrence}), to jump to
+the corresponding spot in the Texinfo file. @xref{Other Repeating
+Search, , Using Occur, emacs, The GNU Emacs Manual}, for more
+information about @address@hidden
+
+The first line in the @samp{*Occur*} window describes the @dfn{regular
+expression} specified by @var{texinfo-heading-pattern}. This regular
+expression is the pattern that @code{texinfo-show-structure} looks for.
address@hidden, , Using Regular Expressions, emacs, The GNU Emacs Manual},
+for more address@hidden
+
+When you invoke the @code{texinfo-show-structure} command, Emacs will
+display the structure of the whole buffer. If you want to see the
+structure of just a part of the buffer, of one chapter, for example,
+use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the
+region. (@xref{Narrowing, , , emacs, The GNU Emacs Manual}.) This is
+how the example used above was generated. (To see the whole buffer
+again, use @kbd{C-x n w} (@code{widen}).)@refill
+
+If you call @code{texinfo-show-structure} with a prefix argument by
+typing @address@hidden C-c C-s}}, it will list lines beginning with
address@hidden@@node} as well as the lines beginning with the @@-sign commands
+for @code{@@chapter}, @code{@@section}, and the address@hidden
+
+You can remind yourself of the structure of a Texinfo file by looking at
+the list in the @samp{*Occur*} window; and if you have mis-named a node
+or left out a section, you can correct the address@hidden
+
address@hidden Using occur, Running Info-Validate, Using
texinfo-show-structure, Catching Mistakes
address@hidden node-name, next, previous, up
address@hidden Using @code{occur}
address@hidden Occurrences, listing with @code{@@occur}
address@hidden occur
+
+Sometimes the @code{texinfo-show-structure} command produces too much
+information. Perhaps you want to remind yourself of the overall structure
+of a Texinfo file, and are overwhelmed by the detailed list produced by
address@hidden In this case, you can use the @code{occur}
+command directly. To do this, address@hidden
+
address@hidden
address@hidden occur}
address@hidden example
+
address@hidden
+and then, when prompted, type a @dfn{regexp}, a regular expression for
+the pattern you want to match. (@xref{Regexps, , Regular Expressions,
+emacs, The GNU Emacs Manual}.) The @code{occur} command works from
+the current location of the cursor in the buffer to the end of the
+buffer. If you want to run @code{occur} on the whole buffer, place
+the cursor at the beginning of the address@hidden
+
+For example, to see all the lines that contain the word
address@hidden@@chapter} in them, just type @samp{@@chapter}. This will
+produce a list of the chapters. It will also list all the sentences
+with @samp{@@chapter} in the middle of the address@hidden
+
+If you want to see only those lines that start with the word
address@hidden@@chapter}, type @samp{^@@chapter} when prompted by
address@hidden If you want to see all the lines that end with a word
+or phrase, end the last word with a @samp{$}; for example,
address@hidden mistakes$}. This can be helpful when you want to see
+all the nodes that are part of the same chapter or section and
+therefore have the same `Up' address@hidden
+
address@hidden Repeating Search, , Using Occur, emacs , The GNU Emacs Manual},
+for more address@hidden
+
address@hidden Running Info-Validate, , Using occur, Catching Mistakes
address@hidden node-name, next, previous, up
address@hidden Finding Badly Referenced Nodes
address@hidden Info-validate
address@hidden Nodes, checking for badly referenced
address@hidden Checking for badly referenced nodes
address@hidden Looking for badly referenced nodes
address@hidden Finding badly referenced nodes
address@hidden Badly referenced nodes
+
+You can use the @code{Info-validate} command to check whether any of
+the `Next', `Previous', `Up' or other node pointers fail to point to a
+node. This command checks that every node pointer points to an
+existing node. The @code{Info-validate} command works only on Info
+files, not on Texinfo address@hidden
+
+The @code{makeinfo} program validates pointers automatically, so you
+do not need to use the @code{Info-validate} command if you are using
address@hidden You only may need to use @code{Info-validate} if you
+are unable to run @code{makeinfo} and instead must create an Info file
+using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or
+if you write an Info file from address@hidden
+
address@hidden
+* Using 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.
address@hidden menu
+
address@hidden Using Info-validate, Unsplit, Running Info-Validate, Running
Info-Validate
address@hidden Running @code{Info-validate}
address@hidden Running @code{Info-validate}
address@hidden Info validating a large file
address@hidden Validating a large file
+
+To use @code{Info-validate}, visit the Info file you wish to check and
+type:@refill
+
address@hidden
+M-x Info-validate
address@hidden example
+
address@hidden
+Note that the @code{Info-validate} command requires an upper case
+`I'. You may also need to create a tag table before running
address@hidden @xref{Tagifying}.
+
+If your file is valid, you will receive a message that says ``File appears
+valid''. However, if you have a pointer that does not point to a node,
+error messages will be displayed in a buffer called @samp{*problems in
+info address@hidden
+
+For example, @code{Info-validate} was run on a test file that contained
+only the first node of this manual. One of the messages said:@refill
+
address@hidden
+In node "Overview", invalid Next: Texinfo Mode
address@hidden example
+
address@hidden
+This meant that the node called @samp{Overview} had a `Next' pointer that
+did not point to anything (which was true in this case, since the test file
+had only one node in it)address@hidden
+
+Now suppose we add a node named @samp{Texinfo Mode} to our test case
+but we do not specify a `Previous' for this node. Then we will get
+the following error message:@refill
+
address@hidden
+In node "Texinfo Mode", should have Previous: Overview
address@hidden example
+
address@hidden
+This is because every `Next' pointer should be matched by a
+`Previous' (in the node where the `Next' points) which points address@hidden
+
address@hidden also checks that all menu entries and cross references
+point to actual address@hidden
+
address@hidden requires a tag table and does not work with files
+that have been split. (The @code{texinfo-format-buffer} command
+automatically splits large files.) In order to use @code{Info-validate}
+on a large file, you must run @code{texinfo-format-buffer} with an
+argument so that it does not split the Info file; and you must create a
+tag table for the unsplit file.
+
address@hidden Unsplit, Tagifying, Using Info-validate, Running Info-Validate
address@hidden node-name, next, previous, up
address@hidden Creating an Unsplit File
address@hidden Creating an unsplit file
address@hidden Unsplit file creation
+
+You can run @code{Info-validate} only on a single Info file that has a
+tag table. The command will not work on the indirect subfiles that
+are generated when a master file is split. If you have a large file
+(longer than 70,000 bytes or so), you need to run the
address@hidden or @code{makeinfo-buffer} command in such
+a way that it does not create indirect subfiles. You will also need
+to create a tag table for the Info file. After you have done this,
+you can run @code{Info-validate} and look for badly referenced
address@hidden
+
+The first step is to create an unsplit Info file. To prevent
address@hidden from splitting a Texinfo file into
+smaller Info files, give a prefix to the @kbd{M-x
+texinfo-format-buffer} command:@refill
+
address@hidden
+C-u M-x texinfo-format-buffer
address@hidden example
+
address@hidden
+or else
+
address@hidden
+C-u C-c C-e C-b
address@hidden example
+
address@hidden
+When you do this, Texinfo will not split the file and will not create
+a tag table for it. @refill
address@hidden Making a tag table manually
address@hidden Tag table, making manually
+
address@hidden Tagifying, Splitting, Unsplit, Running Info-Validate
address@hidden Tagifying a File
+
+After creating an unsplit Info file, you must create a tag table for
+it. Visit the Info file you wish to tagify and type:@refill
+
address@hidden
+M-x Info-tagify
address@hidden example
+
address@hidden
+(Note the upper case @samp{I} in @code{Info-tagify}.) This creates an
+Info file with a tag table that you can address@hidden
+
+The third step is to validate the Info file:@refill
+
address@hidden
+M-x Info-validate
address@hidden example
+
address@hidden
+(Note the upper case @samp{I} in @code{Info-validate}.)
+In brief, the steps are:@refill
+
address@hidden
address@hidden
+C-u M-x texinfo-format-buffer
+M-x Info-tagify
+M-x Info-validate
address@hidden group
address@hidden example
+
+After you have validated the node structure, you can rerun
address@hidden in the normal way so it will construct a
+tag table and split the file automatically, or you can make the tag
+table and split the file address@hidden
+
address@hidden Splitting, , Tagifying, Running Info-Validate
address@hidden node-name, next, previous, up
address@hidden Splitting a File Manually
address@hidden Splitting an Info file manually
address@hidden Info file, splitting manually
+
+You should split a large file or else let the
address@hidden or @code{makeinfo-buffer} command do it
+for you automatically. (Generally you will let one of the formatting
+commands do this job for you. @xref{Creating an Info File}.)@refill
+
+The split-off files are called the indirect address@hidden
+
+Info files are split to save memory. With smaller files, Emacs does not
+have make such a large buffer to hold the address@hidden
+
+If an Info file has more than 30 nodes, you should also make a tag
+table for it. @xref{Using Info-validate}, for information
+about creating a tag table. (Again, tag tables are usually created
+automatically by the formatting command; you only need to create a tag
+table yourself if you are doing the job manually. Most likely, you
+will do this for a large, unsplit file on which you have run
address@hidden)@refill
+
address@hidden Info-split is autoloaded in `loaddefs.el' in Emacs 18.51
+
+Visit the Info file you wish to tagify and split and type the two
+commands:@refill
+
address@hidden
+M-x Info-tagify
+M-x Info-split
address@hidden example
+
address@hidden
+(Note that the @samp{I} in @samp{Info} is upper case.)@refill
+
+When you use the @code{Info-split} command, the buffer is modified into a
+(small) Info file which lists the indirect subfiles. This file should be
+saved in place of the original visited file. The indirect subfiles are
+written in the same directory the original file is in, with names generated
+by appending @samp{-} and a number to the original file address@hidden
+
+The primary file still functions as an Info file, but it contains just
+the tag table and a directory of address@hidden
+
+
address@hidden Refilling Paragraphs
address@hidden Refilling Paragraphs
address@hidden Refilling paragraphs
address@hidden Filling paragraphs
address@hidden Paragraphs, filling
address@hidden refill
+
+The @code{@@refill} command refills and, optionally, indents the first
+line of a address@hidden the command should have been
+called the @code{@@refillandindent} command, but @code{@@refill} is
+shorter and the name was chosen before indenting was possible.} The
address@hidden@@refill} command is no longer important, but we describe it here
+because you once needed it. You will see it in many old Texinfo
address@hidden
+
+Without refilling, paragraphs containing long @@-constructs may look
+bad after formatting because the formatter removes @@-commands and
+shortens some lines more than others. In the past, neither the
address@hidden command nor the
address@hidden command refilled paragraphs
+automatically. The @code{@@refill} command had to be written at the
+end of every paragraph to cause these formatters to fill them. (Both
address@hidden and @code{makeinfo} have always refilled paragraphs
+automatically.) Now, all the Info formatters automatically fill and
+indent those paragraphs that need to be filled and address@hidden
+
+The @code{@@refill} command causes @code{texinfo-format-region} and
address@hidden to refill a paragraph in the Info file
address@hidden all the other processing has been done. For this reason,
+you can not use @code{@@refill} with a paragraph containing either
address@hidden@@*} or @code{@@address@hidden @dots{} @}} since the refilling
action will
+override those two address@hidden
+
+The @code{texinfo-format-region} and @code{texinfo-format-buffer}
+commands now automatically append @code{@@refill} to the end of each
+paragraph that should be filled. They do not append @code{@@refill} to
+the ends of paragraphs that contain @code{@@*} or
@address@hidden@@address@hidden @address@hidden
+and therefore do not refill or indent address@hidden
+
+
address@hidden Command Syntax
address@hidden @@-Command Syntax
address@hidden @@-command syntax
address@hidden Syntax, of @@-commands
address@hidden Command syntax
+
+The character @samp{@@} is used to start special Texinfo commands.
+(It has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo
+has four types of @@-command:@refill
+
address@hidden @asis
address@hidden 1. Non-alphabetic commands.
+These commands consist of an @@ followed by a punctuation mark or other
+character that is not part of the alphabet. Non-alphabetic commands are
+almost always part of the text within a paragraph, and never take any
+argument. The two characters (@@ and the other one) are complete in
+themselves; none is followed by braces. The non-alphabetic commands
+are: @code{@@.}, @code{@@:}, @code{@@*}, @code{@@@kbd{SPACE}},
address@hidden@@@kbd{TAB}}, @code{@@@kbd{NL}}, @code{@@@@}, @code{@@@{}, and
address@hidden@@@address@hidden
+
address@hidden 2. Alphabetic commands that do not require arguments.
+These commands start with @@ followed by a word followed by left- and
+right-hand braces. These commands insert special symbols in the
+document; they do not require arguments. For example,
address@hidden@@address@hidden@}} @result{} @address@hidden,
@code{@@address@hidden@}}
address@hidden @address@hidden, @code{@@address@hidden@}} @result{}
address@hidden',
+and @code{@@address@hidden@}} @result{} @address@hidden@refill
+
address@hidden 3. Alphabetic commands that require arguments within braces.
+These commands start with @@ followed by a letter or a word, followed by an
+argument within braces. For example, the command @code{@@dfn} indicates
+the introductory or defining use of a term; it is used as follows: @samp{In
+Texinfo, @@@@-commands are @@address@hidden@} address@hidden
+
address@hidden 4. Alphabetic commands that occupy an entire line.
+These commands occupy an entire line. The line starts with @@,
+followed by the name of the command (a word); for example, @code{@@center}
+or @code{@@cindex}. If no argument is needed, the word is followed by
+the end of the line. If there is an argument, it is separated from
+the command name by a space. Braces are not address@hidden
address@hidden table
+
address@hidden Braces and argument syntax
+Thus, the alphabetic commands fall into classes that have
+different argument syntaxes. You cannot tell to which class a command
+belongs by the appearance of its name, but you can tell by the
+command's meaning: if the command stands for a glyph, it is in
+class 2 and does not require an argument; if it makes sense to use the
+command together with other text as part of a paragraph, the command
+is in class 3 and must be followed by an argument in braces;
+otherwise, it is in class 4 and uses the rest of the line as its
address@hidden
+
+The purpose of having a different syntax for commands of classes 3 and
+4 is to make Texinfo files easier to read, and also to help the GNU
+Emacs paragraph and filling commands work properly. There is only one
+exception to this rule: the command @code{@@refill}, which is always
+used at the end of a paragraph immediately following the final period
+or other punctuation character. @code{@@refill} takes no argument and
+does @emph{not} require braces. @code{@@refill} never confuses the
+Emacs paragraph commands because it cannot appear at the beginning of
+a address@hidden
+
+
address@hidden Obtaining TeX
address@hidden How to Obtain @TeX{}
address@hidden Obtaining @TeX{}
address@hidden @TeX{}, how to obtain
+
address@hidden !!! Here is information about obtaining TeX. Update it whenever.
address@hidden !!! Also consider updating TeX.README on ftp.gnu.org.
address@hidden Updated by RJC on 1 March 1995, conversation with MacKay.
address@hidden Updated by address@hidden on 29 July 1996.
address@hidden Updated by address@hidden on 25 April 1997.
address@hidden Updated by address@hidden on 27 February 1998.
address@hidden is freely redistributable. You can obtain @TeX{} for Unix
+systems via anonymous ftp or on physical media. The core material
+consists of the Web2c @TeX{} distribution (@uref{http://tug.org/web2c}).
+
+Instructions for retrieval by anonymous ftp and information on other
+available distributions:
address@hidden
address@hidden://tug.org/tex/unixtex.ftp}
address@hidden://tug.org/unixtex.ftp}
address@hidden example
+
+The Free Software Foundation provides a core distribution on its Source
+Code CD-ROM suitable for printing Texinfo manuals. To order it, contact:
+
address@hidden
address@hidden
+Free Software Foundation, Inc.
+59 Temple Place Suite 330
+Boston, MA @ @ 02111-1307
+USA
+Telephone: @w{+1-617-542-5942}
+Fax: (including Japan) @w{+1-617-542-2652}
+Free Dial Fax (in Japan):
address@hidden } @w{ } @w{ } 0031-13-2473 (KDD)
address@hidden } @w{ } @w{ } 0066-3382-0158 (IDC)
+Electronic mail: @code{gnu@@gnu.org}
address@hidden group
address@hidden display
+
+Many other @TeX{} distributions are available; see
address@hidden://tug.org/}.
+
+
address@hidden These are no longer ``new'', and the explanations
address@hidden are all given elsewhere anyway, I think. --karl, 25apr97.
address@hidden So ignore the entire appendix.
+
+
address@hidden Copying This Manual
address@hidden Copying This Manual
+
address@hidden
+* GNU Free Documentation License:: License for copying this manual.
address@hidden menu
+
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
+
address@hidden FDL, GNU Free Documentation License
address@hidden Version 1.1, March 2000
+
address@hidden
+Copyright @copyright{} 2000 Free Software Foundation, Inc.
+59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
address@hidden display
+
address@hidden 0
address@hidden
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+written document @dfn{free} in the sense of freedom: to assure everyone
+the effective freedom to copy and redistribute it, with or without
+modifying it, either commercially or noncommercially. Secondarily,
+this License preserves for the author and publisher a way to get
+credit for their work, while not being considered responsible for
+modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
address@hidden
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work that contains a
+notice placed by the copyright holder saying it can be distributed
+under the terms of this License. The ``Document'', below, refers to any
+such manual or work. Any member of the public is a licensee, and is
+addressed as ``you''.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (For example, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, whose contents can be viewed and edited directly and
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is
+not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
address@hidden without markup, Texinfo input format, address@hidden input
format,
address@hidden or @acronym{XML} using a publicly available
address@hidden, and standard-conforming simple @acronym{HTML} designed
+for human modification. Opaque formats include PostScript,
address@hidden, proprietary formats that can be read and edited only by
+proprietary word processors, @acronym{SGML} or @acronym{XML} for which
+the @acronym{DTD} and/or processing tools are not generally available,
+and the machine-generated @acronym{HTML} produced by some word
+processors for output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
address@hidden
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
address@hidden
+COPYING IN QUANTITY
+
+If you publish printed copies of the Document numbering more than 100,
+and the Document's license notice requires Cover Texts, you must enclose
+the copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols. If you use the latter
+option, you must take reasonably prudent steps, when you begin
+distribution of Opaque copies in quantity, to ensure that this
+Transparent copy will remain thus accessible at the stated location
+until at least one year after the last time you distribute an Opaque
+copy (directly or through your agents or retailers) of that edition to
+the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
address@hidden
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
address@hidden A
address@hidden
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
address@hidden
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has less than five).
+
address@hidden
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
address@hidden
+Preserve all the copyright notices of the Document.
+
address@hidden
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
address@hidden
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
address@hidden
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
address@hidden
+Include an unaltered copy of this License.
+
address@hidden
+Preserve the section entitled ``History'', and its title, and add to
+it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
address@hidden
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
address@hidden
+In any section entitled ``Acknowledgments'' or ``Dedications'',
+preserve the section's title, and preserve in the section all the
+substance and tone of each of the contributor acknowledgments
+and/or dedications given therein.
+
address@hidden
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
address@hidden
+Delete any section entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
address@hidden
+Do not retitle any existing section as ``Endorsements''
+or to conflict in title with any Invariant Section.
address@hidden enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
address@hidden
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections entitled ``History''
+in the various original documents, forming one section entitled
+``History''; likewise combine any sections entitled ``Acknowledgments'',
+and any sections entitled ``Dedications''. You must delete all sections
+entitled ``Endorsements.''
+
address@hidden
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
address@hidden
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, does not as a whole count as a Modified Version
+of the Document, provided no compilation copyright is claimed for the
+compilation. Such a compilation is called an ``aggregate'', and this
+License does not apply to the other self-contained works thus compiled
+with the Document, on account of their being thus compiled, if they
+are not themselves derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one quarter
+of the entire aggregate, the Document's Cover Texts may be placed on
+covers that surround only the Document within the aggregate.
+Otherwise they must appear on covers around the whole aggregate.
+
address@hidden
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License provided that you also include the
+original English version of this License. In case of a disagreement
+between the translation and the original English version of this
+License, the original English version will prevail.
+
address@hidden
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
address@hidden
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
address@hidden://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
address@hidden enumerate
+
address@hidden
address@hidden ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
address@hidden
address@hidden
+ Copyright (C) @var{year} @var{your name}.
+ 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 the Invariant Sections being @var{list their titles}, with the
+ Front-Cover Texts being @var{list}, and with the Back-Cover Texts being
@var{list}.
+ A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
address@hidden group
address@hidden smallexample
+
+If you have no Invariant Sections, write ``with no Invariant Sections''
+instead of saying which ones are invariant. If you have no
+Front-Cover Texts, write ``no Front-Cover Texts'' instead of
+``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
address@hidden Local Variables:
address@hidden ispell-local-pdict: "ispell-dict"
address@hidden End:
+
+
+
address@hidden Command and Variable Index
address@hidden Command and Variable Index
+
+This is an alphabetical list of all the @@-commands, assorted Emacs Lisp
+functions, and several variables. To make the list easier to use, the
+commands are listed without their preceding @samp{@@address@hidden
+
address@hidden fn
+
+
address@hidden Concept Index
address@hidden Concept Index
+
address@hidden cp
+
+
address@hidden
- [Texi2html-cvs] texi2html/test/manuals res/ccvs/cvs.2 res/ccvs_...,
Patrice Dumas <=