texinfo ChangeLog doc/texinfo.txi util/htmlxref...

[Karl Berry]

CVSROOT:        /sources/texinfo
Module name:    texinfo
Changes by:     Karl Berry <karl>       10/08/02 18:28:28

Modified files:
        .              : ChangeLog 
        doc            : texinfo.txi 
        util           : htmlxref.cnf 

Log message:
        (init file basics): edit

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1087&r2=1.1088
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.277&r2=1.278
http://cvs.savannah.gnu.org/viewcvs/texinfo/util/htmlxref.cnf?cvsroot=texinfo&r1=1.6&r2=1.7

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1087
retrieving revision 1.1088
diff -u -b -r1.1087 -r1.1088
--- ChangeLog   2 Aug 2010 00:43:55 -0000       1.1087
+++ ChangeLog   2 Aug 2010 18:28:27 -0000       1.1088
@@ -1,3 +1,7 @@
+2010-08-02  Karl Berry  <address@hidden>
+
+       * doc/texinfo.txi (Initialization File Basics): capitalize+edit.
+
 2010-08-01  Karl Berry  <address@hidden>
 
        * doc/texinfo.txi (Loading Initialization Files): capitalize+edit.

Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.277
retrieving revision 1.278
diff -u -b -r1.277 -r1.278
--- doc/texinfo.txi     2 Aug 2010 00:43:56 -0000       1.277
+++ doc/texinfo.txi     2 Aug 2010 18:28:27 -0000       1.278
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.277 2010/08/02 00:43:56 karl Exp $
address@hidden $Id: texinfo.txi,v 1.278 2010/08/02 18:28:27 karl Exp $
 @c Ordinarily, Texinfo files have the extension .texi.  But texinfo.texi
 @c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi.
 
@@ -655,8 +655,7 @@
 texi2any Output Customization
 
 * Loading Initialization Files::   Initialization files and their search paths.
-* Initialization files basics::       General informations on initialization 
-                                      files.
+* Initialization File Basics::     General information on init files.
 * Elements::                          The main division of output document.
 * Special elements::                  Customizing special elements text and 
                                       layout.
@@ -18417,12 +18416,12 @@
 in the canonical @file{htmlxref.cnf}):
 
 @smallexample
-R = http://www.gnu.org
-RS = address@hidden@}/software
-hello mono    address@hidden@}/hello/manual/hello.html
-hello node    address@hidden@}/hello/manual/html_node/
-hello section address@hidden@}/hello/manual/html_section/
-hello chapter address@hidden@}/hello/manual/html_chapter/
+G = http://www.gnu.org
+GS = address@hidden@}/software
+hello mono    address@hidden@}/hello/manual/hello.html
+hello node    address@hidden@}/hello/manual/html_node/
+hello section address@hidden@}/hello/manual/html_section/
+hello chapter address@hidden@}/hello/manual/html_chapter/
 @end smallexample
 
 @cindex monolithic manuals, for HTML cross-references
@@ -18524,8 +18523,7 @@
 
 @menu
 * Loading Initialization Files::   Initialization files and their search paths.
-* Initialization files basics::       General informations on initialization 
-                                      files.
+* Initialization File Basics::     General information on init files.
 * Elements::                          The main division of output document.
 * Navigation panel customization::
 * Page layout customization::
@@ -18606,80 +18604,87 @@
 @option{--conf-dir} option.
 
 
address@hidden Initialization files basics
address@hidden General informations on initialization files
address@hidden Initialization File Basics
address@hidden Initialization File Basics
 
-Initialization files are Perl source.
-A good source of inspiration could be the initialization files provided
-in the Texinfo distribution.  They all have @samp{.init} extension.
-The @file{texi2html.init} file is used to set all the defaults, and,
-although quite large is an interesting source of examples.
-Simpler initialization files are installed in the default case, they may
-also be interesting starting points.
address@hidden Initialization file basics
+
+Initialization files are written in Perl, and by convention have
+extension @file{.init}.  Many initialization files are included in the
+Texinfo distribution, and can serve as a good model for writing your
+own.  In particular, the @file{texi2html.init} file is used to set all
+the defaults for Texinfo.  Although it is large, it contains many
+useful examples of settings.  Smaller examples include
address@hidden, @file{html32.init}, and plenty more.
+
+We divide the kinds of variables that can appear in initialization
+files into three general categories:
 
-In initialization file three kind of variables appear.
 @table @asis
 @item configuration variables
-Those variables, described in @ref{makeinfo Configuration Variables}
-are set and accessed through specific functions in initialization files.
address@hidden scalar, arrays and hashes
-Normal perl variable. The order of loading of initialization
-files and of command-line options processing may be important when 
-they are modified,
-later changes modifying former changes.
address@hidden references on functions
-This allows a dynamical redefinition of functions used to produce
-the output.
-
-As the functions are defined by a reference name, we will always
-use the reference name in function prototypes.  For the function arguments
-we will use @code{\@@array} for a reference on an array and similarly
address@hidden for a reference on a hash.
-
-Thus, the prototype for the function associated with the function
-reference @samp{$formatting_function} will be:
+Configuration variables are set and accessed through specific
+functions in initialization files (@pxref{makeinfo Configuration
+Variables})
+
address@hidden scalars, lists and hashes
+Normal Perl variables.  The order of loading of initialization files
+and of command-line options is important: later changes override
+earlier ones.
+
address@hidden function references
+These allow dynamic redefinition of functions used to produce output.
+
+As such functions are defined by a reference name, we will always use
+the reference name in function prototypes.  For the function arguments
+we will use @code{\@@array} for a reference to a list and
address@hidden for a reference to a hash.
+
+To illustrate these conventions, here is the prototype for the
+function associated with a function reference
address@hidden:
 
 @deftypefn {Function Reference} $text formatting_function $arg1 \@@arg2
address@hidden takes as first argument @var{$arg2},
-as second argument a reference on an array @var{\@@arg2}
address@hidden has a first argument @var{$arg1},
+a second argument a reference to an array @var{\@@arg2},
 and returns the formatted text @var{$text}.
 @end deftypefn
 
-To redefined the corresponding function, you should write:
+To redefine this function, you would write:
 
 @example
 $formatting_function = \&my_formatting_function;
-
 sub my_formatting_function($ $)
 @{
     my $arg1 = shift;
     my $arg2 = shift;
     # prepare $formatted_text
-    .....
+  ...
     return $formatted_text;
 @}
 @end example
 @end table
 
-Initialization file are loaded from the main program by
-the mean of a @code{require}, while in the @code{Texi2HTML::Config}
-namespace. This means that the namespace of the main program and
-the namespace of initialization files are distinct, which ensures
-that no name clash should happen.  The scalars,
-arrays and hashes are declared with
address@hidden vars}, such that it should be possible to use the
address@hidden strict} pragma in the initialization file code.
-
-To avoid messing with the variables in the @code{main} namespace
-all the global variables which could be of use in the init files
-are in the @code{Texi2HTML} namespace.  Notice that the functions
-of the main program are still in the @code{main} namespace.
-
-Since the program can proceed more than one file on the
-command line, you should make sure that you initialize the variables
-that are used during a manual formatting.  It is possible to call
-functions at different stages for that 
-use (@pxref{Calling functions at different stages}).
address@hidden Texi2HTML::Config @r{namespace}
+Initialization file are loaded from the main program via a
address@hidden call in the @code{Texi2HTML::Config} namespace. This
+means that the namespace of the main program and the namespace of
+initialization files are distinct, which minimizes the chance of a
+name clash.  The standard scalars, arrays and hashes are declared with
address@hidden vars}, so that it should be possible to use the @code{use
+strict} pragma in initialization files.
+
address@hidden Texi2HTML @r{namespace}
address@hidden main @r{namespace}
+To avoid accidentally altering the variables in the @code{main}
+namespace, all the global variables which could be of use in the init
+files are available in the @code{Texi2HTML} namespace.  For
+convenience, the functions of the main program, however, are still in
+the @code{main} namespace.
+
+Since the program can process more than one file on the command line,
+you must ensure that you properly initialize the variables used during
+formatting.  It is possible to call functions at different stages to
+help with that (@pxref{Calling functions at different stages}).
 
 @menu
 * Setting and getting configuration variable value::
@@ -24227,7 +24232,7 @@
 (@url{http://www.gnu.org/software/rcs}) version control systems, which
 expand it into a string such as:
 @example
-$Id: texinfo.txi,v 1.277 2010/08/02 00:43:56 karl Exp $
+$Id: texinfo.txi,v 1.278 2010/08/02 18:28:27 karl Exp $
 @end example
 (This is useful in all sources that use version control, not just manuals.)
 You may wish to include the @samp{$Id:} comment in the @code{@@copying}
@@ -24306,7 +24311,7 @@
 
 @verbatim
 \input texinfo   @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.277 2010/08/02 00:43:56 karl Exp $
address@hidden $Id: texinfo.txi,v 1.278 2010/08/02 18:28:27 karl Exp $
 @comment %**start of header
 @setfilename sample.info
 @include version.texi

Index: util/htmlxref.cnf
===================================================================
RCS file: /sources/texinfo/texinfo/util/htmlxref.cnf,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -b -r1.6 -r1.7
--- util/htmlxref.cnf   2 Aug 2010 00:43:56 -0000       1.6
+++ util/htmlxref.cnf   2 Aug 2010 18:28:28 -0000       1.7
@@ -1,5 +1,5 @@
 # htmlxref.cnf - reference file for Texinfo files on the web.
-htmlxrefversion=2010-08-01.16; # UTC
+htmlxrefversion=2010-08-02.18; # UTC
 
 # Copyright 2010 Free Software Foundation, Inc.
 # 
@@ -13,20 +13,26 @@
 # Maintainers: for information on putting manuals on the web, including
 # automatically generating all the useful formats, see
 # http://www.gnu.org/prep/maintain/html_node/Manuals-on-Web-Pages.html.
+#
+# All the manuals in this file should follow the naming convention for
+# nodes described at
+# http://www.gnu.org/software/texinfo/manual/texinfo/html_node/HTML-Xref.html
+# (otherwise cross-references fail).  This is what makeinfo and
+# texi2html implement.
  
 # shorten references to manuals on www.gnu.org.
-R = http://www.gnu.org
-RS = ${R}/software
+G = http://www.gnu.org
+GS = ${G}/software
 
-anubis         chapter ${RS}/anubis/manual/html_chapter/
-anubis         section ${RS}/anubis/manual/html_section/
-anubis         node    ${RS}/anubis/manual/html_node/
+anubis         chapter ${GS}/anubis/manual/html_chapter/
+anubis         section ${GS}/anubis/manual/html_section/
+anubis         node    ${GS}/anubis/manual/html_node/
 
-autoconf       mono    ${RS}/autoconf/manual/autoconf.html
-autoconf       node    ${RS}/autoconf/manual/html_node/
+autoconf       mono    ${GS}/autoconf/manual/autoconf.html
+autoconf       node    ${GS}/autoconf/manual/html_node/
 
-automake       mono    ${RS}/automake/manual/automake.html
-automake       node    ${RS}/automake/manual/html_node/
+automake       mono    ${GS}/automake/manual/automake.html
+automake       node    ${GS}/automake/manual/html_node/
 
 bpel2owfn      mono    
http://www.gnu.org/software/bpel2owfn/manual/2.0.x/bpel2owfn.html
 
@@ -34,16 +40,16 @@
 
 #cvs cannot be handled here; see http://ximbiot.com/cvs/manual.
 
-elisp          mono    ${RS}/emacs/manual/html_mono/elisp.html
-elisp          node    ${RS}/emacs/manual/html_node/
+elisp          mono    ${GS}/emacs/manual/html_mono/elisp.html
+elisp          node    ${GS}/emacs/manual/html_node/
 
-emacs          mono    ${RS}/emacs/manual/html_mono/emacs.html
-emacs          node    ${RS}/emacs/manual/html_node/
+emacs          mono    ${GS}/emacs/manual/html_mono/emacs.html
+emacs          node    ${GS}/emacs/manual/html_node/
 
-emms           node    ${RS}/emms/manual/
+emms           node    ${GS}/emms/manual/
 
-gcal           mono    ${RS}/gcal/manual/gcal.html
-gcal           node    ${RS}/gcal/manual/html_node/
+gcal           mono    ${GS}/gcal/manual/gcal.html
+gcal           node    ${GS}/gcal/manual/html_node/
 
 gccint         node    http://gcc.gnu.org/onlinedocs/gccint/
 gcj            node    http://gcc.gnu.org/onlinedocs/gcj/
@@ -52,38 +58,43 @@
 gnat_ugn_unw   node    http://gcc.gnu.org/onlinedocs/gnat_ugn_unw/
 libgomp                node    http://gcc.gnu.org/onlinedocs/libgomp/
 
-gnubg          mono    ${RS}/gnubg/manual/gnubg.html
-gnubg          node    ${RS}/gnubg/manual/html_node/
+gnubg          mono    ${GS}/gnubg/manual/gnubg.html
+gnubg          node    ${GS}/gnubg/manual/html_node/
+
+gnubik         mono    ${GS}/gnubik/manual/gnubik.html
+gnubik         node    ${GS}/gnubik/manual/html_node/
+
+gnus           mono    ${GS}/emacs/manual/html_node/mh-e/
+gnus           node    ${GS}/emacs/manual/html_mono/mh-e.html
 
-gnubik         mono    ${RS}/gnubik/manual/gnubik.html
-gnubik         node    ${RS}/gnubik/manual/html_node/
+gnuschool      mono    ${GS}/gnuschool/gnuschool.html
 
-gnus           mono    ${RS}/emacs/manual/html_node/mh-e/
-gnus           node    ${RS}/emacs/manual/html_mono/mh-e.html
+gtypist                mono    ${GS}/gtypist/doc/
 
-gnuschool      mono    ${RS}/gnuschool/gnuschool.html
+libextractor   mono    ${GS}/libextractor/extractor.html
 
-gtypist                mono    ${RS}/gtypist/doc/
+liquidwar6     mono    ${GS}/liquidwar6/manual/liquidwar6.html
+liquidwar6     node    ${GS}/liquidwar6/manual/html_node/
 
-libextractor   mono    ${RS}/libextractor/extractor.html
+mailutils      mono    ${GS}/mailutils/manual/mailutils.html
+mailutils      node    ${GS}/mailutils/manual/html_node/
 
-mailutils      mono    ${RS}/mailutils/manual/mailutils.html
-mailutils      node    ${RS}/mailutils/manual/html_node/
+maintain       mono    ${G}/prep/maintain/maintain.html
+maintain       node    ${G}/prep/maintain/html_node/
 
-maintain       mono    ${R}/prep/maintain/maintain.html
-maintain       node    ${R}/prep/maintain/html_node/
+mdk            mono    ${GS}/mdk/manual/mdk.html
+mdk            node    ${GS}/mdk/manual/html_node/
 
-mdk            mono    ${RS}/mdk/manual/mdk.html
-mdk            node    ${RS}/mdk/manual/html_node/
+mh-e           mono    ${GS}/emacs/manual/html_node/mh-e/
+mh-e           node    ${GS}/emacs/manual/html_mono/mh-e.html
 
-mh-e           mono    ${RS}/emacs/manual/html_node/mh-e/
-mh-e           node    ${RS}/emacs/manual/html_mono/mh-e.html
+motti          node    ${GS}/motti/manual/
 
-standards      mono    ${R}/prep/standards/standards.html
-standards      node    ${R}/prep/standards/html_node/
+standards      mono    ${G}/prep/standards/standards.html
+standards      node    ${G}/prep/standards/html_node/
 
-texinfo                mono    ${RS}/texinfo/manual/texinfo/texinfo.html
-texinfo                node    ${RS}/texinfo/manual/texinfo/html_node/
+texinfo                mono    ${GS}/texinfo/manual/texinfo/texinfo.html
+texinfo                node    ${GS}/texinfo/manual/texinfo/html_node/
 
 # Local Variables:
 # eval: (add-hook 'write-file-hooks 'time-stamp)