Re: a new release

--dDRMvlgZJXvWKvBx
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

> I won't be too picky about requiring this for the release.  We can
> change the NEWS file to read something like, see the i18n/* files for
> examples.
> 
> When you're ready to do doc, you can send me patches and I can go over

Well I have allready done that. I didn't made patches because there were 
so much changes that I think reading the new files is simpler. I attached
the updated manual files.

I made a mail some time ago explaining that I posted the updated manual
on a website... The attached files are the latest versions and in sync
with the code, except that there is nothing about i18n.

> them and correct your English and commit them, if that's what you mean,
> though your English is pretty good.  I've certainly seen much worse, and
> in open source manuals.  :)
> 
> Not, "maid", in this sense.  It's "made".  Maids clean up after people.
> :)  The pronunciation is the same.

:)))
You see that my english isn't so good... Maybe there are even more funny 
things in the manual ;-).

> If it's not something a non-developer would touch, I wouldn't worry
> about it.  Implementation details should be left out of the NEWS file.
> The NEWS file is intended for users, not developers.

It is something a non developer could touch, because those structures
were global and there were some comments on how to use them to customize
things. However I believe not a lot of people really used that, as it wasn't 
in the texi2html.init but rather in texi2html.pl.
 
> As far as other developers are concerned, there aren't many of us and
> the mailing list, the ChangeLog, and CVS commands will probably do the
> trick.  If you really think those sources won't be sufficient, you could
> always create a DEVELOPER-NEWS file or the like.

Right. I think too that there is allready enough information.

Pat

--dDRMvlgZJXvWKvBx
Content-Type: application/x-texinfo
Content-Disposition: attachment; filename="texi2html.texi"
Content-Transfer-Encoding: quoted-printable

\input texinfo @c -*-texinfo-*-=0A@c=0A@c This is the ``Texinfo to HTML Con=
verter'' manual which=0A@c which is part of the ``texi2html'' distribution.=
=0A@c=0A@c License:=0A@c    Copyright (C) 1999, 2000  Free Software Foundat=
ion, Inc.=0A@c=0A@c    This program is free software; you can redistribute =
it=0A@c    and/or modify it under the terms of the GNU General Public=0A@c =
   License as published by the Free Software Foundation;=0A@c    either ver=
sion 2 of the License, or (at your option) any=0A@c    later version.=0A@c=
=0A@c    This program is distributed in the hope that it will be=0A@c    us=
eful, but WITHOUT ANY WARRANTY; without even the implied=0A@c    warranty o=
f MERCHANTABILITY or FITNESS FOR A PARTICULAR=0A@c    PURPOSE.  See the GNU=
 General Public License for more=0A@c    details.=0A@c=0A@c    You should h=
ave received a copy of the GNU General=0A@c    Public License along with th=
is program; if not, write to=0A@c    the Free Software Foundation, Inc., 59=
 Temple Place, Suite=0A@c    330, Boston, MA  02111-1307  USA=0A@c=0A@c=0A@=
c Revisions:=0A@c $Id: texi2html.texi,v 1.3 2001/09/15 09:37:50 reiter Exp =
$=0A@c=0A@c Author:=0A@c   Karl Heinz Marbaise <[email protected]>=0A@c=0A@=
c --------------------------------------------------------=0A@c=0A@c Curren=
tly most of the material is copied out of=0A@c texi2html.init file. It's ju=
st a start point.=0A@c In other words this is a draft manual ;-)=0A@c=0A@se=
tfilename texi2html.info=0A@c ---------------------------------------------=
-----------=0A@c Edition and last update date of the manual which might=0A@=
c differ to the scripts last update date etc.=0A@set MANUAL_UPD 14. August =
2000=0A@set MANUAL_ED 0.21=0A@c=0A@set MANUAL_AUTHOR Karl Heinz Marbaise=0A=
@set MANUAL_AUTHOR_EMAIL khmarbaise@@gmx.de=0A@c=0A@c Get the version of th=
e script itself through=0A@c configure/autoconf etc.=0A@c version.texi is a=
utomatically generated through=0A@c configure/autoconf.=0A@include version.=
texi=0A@c --------------------------------------------------------=0A@c Ind=
ex for command line options=0A@defindex op=0A@c ---------------------------=
-----------------------------=0A@settitle Texinfo to HTML=0A@c @setchaptern=
ewpage on=0A@setchapternewpage odd=0A@footnotestyle separate=0A@ifset short=
titlepage-enabled=0A@shorttitlepage Texinfo to HTML=0A@end ifset=0A@c -----=
---------------------------------------------------=0A@c support old style =
Info Dir entries.=0A@ifset OLDSTYLE-INFO-DIR=0A@ifinfo=0A@format=0ASTART-IN=
FO-DIR-ENTRY=0A* Texi2html: (texi2html).  Texinfo 2 HTML Converter (texi2ht=
ml).=0AEND-INFO-DIR-ENTRY=0A@end format=0A@end ifinfo=0A@end ifset=0A@c ---=
-----------------------------------------------------=0A@c Informations for=
 install-info.=0A@c I think the conversion script should be found=0A@c wher=
e the documentation system lives.=0A@c What do you think?=0A@dircategory Te=
xinfo documentation system=0A@direntry=0A* Texi2html: (texi2html).  Texinfo=
 to HTML Converter.=0A@end direntry=0A@c ----------------------------------=
----------------------=0A@ifnottex=0AThis file documents the texi2html scri=
pt which converts=0ATexinfo into HTML.=0A=0ACopyright (C) 1999, 2000  Free =
Software Foundation, Inc.=0A=0AThis edition is for texi2html version @value=
{VERSION},=0A@value{UPDATED}.=0A=0APermission is granted to make and distri=
bute verbatim=0Acopies of this manual provided the copyright notice and=0At=
his permission notice are preserved on all copies.=0A=0A@ignore=0APermissio=
n is granted to process this file through TeX and=0Aprint the results, prov=
ided the printed document carries=0Acopying permission notice identical to =
this one except for=0Athe removal of this paragraph (this paragraph not bei=
ng=0Arelevant to the printed manual).=0A=0A@end ignore=0APermission is gran=
ted to copy and distribute modified=0Aversions of this manual under the con=
ditions for verbatim=0Acopying, provided that the entire resulting derived =
work is=0Adistributed under the terms of a permission notice=0Aidentical to=
 this one.=0A=0APermission is granted to copy and distribute translations=
=0Aof this manual into another language, under the above=0Aconditions for m=
odified versions, except that this=0Apermission notice may be stated in a t=
ranslation approved=0Aby the Free Software Foundation.=0A@end ifnottex=0A@c=
 --------------------------------------------------------=0A@titlepage=0A@t=
itle Texinfo to HTML Converter=0A@subtitle Manual Edition @value{MANUAL_ED}=
=0A@subtitle Last Update: @value{MANUAL_UPD}=0A@subtitle for Version @value=
{VERSION} of @command{texi2html} script.=0A@author Lionel Cons=0A@author Ka=
rl Berry=0A@author Olaf Bachmann=0A@author and many others.=0A@author Karl =
Heinz Marbaise (manual)=0A@page=0A@vskip 0pt plus 1filll=0ACopyright @copyr=
ight{} Lionel Cons@*=0ACopyright @copyright{} Karl Berry@*=0ACopyright @cop=
yright{} Olaf Bachmann@*=0ACopyright @copyright{} and many others.@*=0ACopy=
right @copyright{} Karl Heinz Marbaise (manual)@*=0A=0APermission is grante=
d to make and distribute verbatim=0Acopies of this manual provided the copy=
right notice and=0Athis permission notice are preserved on all copies.=0A=
=0APermission is granted to copy and distribute modified=0Aversions of this=
 manual under the conditions for verbatim=0Acopying, provided that the enti=
re resulting derived work is=0Adistributed under the terms of a permission =
notice=0Aidentical to this one.=0A=0APermission is granted to copy and dist=
ribute translations=0Aof this manual into another language, under the above=
=0Aconditions for modified versions, except that this=0Apermission notice m=
ay be stated in a translation approved=0Aby the Free Software Foundation.=
=0A@end titlepage=0A@c =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=0A@summarycontents=0A@contents=
=0A@c=0A@ifnottex=0A@c @page=0A@c =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=0A@c @node Top, Over=
view, (dir), (dir)=0A@c @top=0A@c @chapter About=0A@node Top=0A@top Texi2ht=
ml=0A=0AThis Manual (Edition @value{MANUAL_ED}, last updated at=0A@value{MA=
NUAL_UPD}) describes the @command{texi2html} Perl=0Ascript which converts=
=0A@c The following construct allows me to get=0A@c real URL link in HTML a=
nd working refs in=0A@c info.=0A@c (pertusus: some support for html cross m=
anual now=0A@c exists in texi2html, but it implies having the texinfo=0A@c =
html manual at the right place, which isn't the case=0A@c in most cases). A=
nd also the resulting ref is less=0A@c pretty in info.=0A@ifhtml=0A@uref{ht=
tp://www.texinfo.org,Texinfo}=0A@end ifhtml=0A@ifnothtml=0ATexinfo (@pxref{=
Top,,Texinfo,Texinfo})=0A@end ifnothtml=0Ainto @acronym{HTML}.=0A=0APlease =
send bug reports about this manual to Karl Heinz=0AMarbaise @email{khmarbai=
se@@gmx.de}. Please state exact=0Aversion/edition of the manual (can be fou=
nd at start of=0ATexinfo source file; use the entry Id under Revisions).=0A=
=0APlease note:=0A@example=0AThis manual is currently under=0Aconstruction =
and of course incomplete ;-)=0A@end example=0A=0A@c The following line with=
in a menu does not work!=0A@c (pertusus: what doesn't work ?)=0A@c * Why te=
xi2html and not Makeinfo?:whytexi2html.      Why texi2html and not makeinfo=
?.=0A@menu=0A@c * MenuName:NodeName.       Description.=0A* Overview::     =
             Overview about @emph{texi2html}.=0A* Installation::           =
   Installation process.=0A* Invoking texi2html::         Description of th=
e command line options.=0A* Initialization files::      What kind of variab=
les and subroutines appear=0A                              in init files an=
d how they are called.=0A* Changing the page layout::  Fine tuning of the p=
age layout.=0A* Customizing HTML::          Fine tuning of the @acronym{HTM=
L} elements associated=0A                              with the texinfo con=
structs.=0A* Indexop::                   Command Line Option Index.=0A* Ind=
exvr::                   Variable Index.=0A* Indexcp::                   Co=
ncept Index.=0A@c functions are scattered through the manual...=0A@c * Refe=
rence::                 Reference Manual of functions.=0A=0A@detailmenu=0A=
=0A/// The Detailed Node Listing ///=0A=0A--- Overview ---=0A=0A* Why texi2=
html and not Makeinfo?:whytexi2html.      Why =0A                  texi2htm=
l and not makeinfo?=0A=0A--- Invoking @command{texi2html} ---=0A=0A* Splitt=
ig output::           How the texinfo manual is split.=0A* Output files::  =
            Determining output file and directory names.=0A* Expansion::   =
              Specify what region get expanded.=0A* Texinfo related options=
::  Command line options related with =0A                              texi=
nfo language features.=0A* Page layout options::       Customize output pag=
e layout with command line=0A                              options=0A* Styl=
e options::             Customize @acronym{HTML} and text style with=0A    =
                          command line options=0A* Expanding TeX regions:: =
    Expand @code{@@tex} and @code{@@math} regions using La@TeX{}2HTML=0A* U=
sing init files::          Specifying initialization files for fine tuning.=
=0A=0A--- Initialization files ---=0A=0A* Redefining functions::      Funct=
ion redefinition is achieved with =0A                              redefini=
tion of references on functions.=0A* Function prototypes::       Convention=
s used in that manual for function =0A                              referen=
ce prototypes display.=0A                              =0A--- Customization=
 of the pages layout ---=0A=0A* The different pages::       The different c=
ategories of pages.=0A* The page layout::           The elements of a page.=
=0A* Navigation panel::          How to change the navigation panel.=0A* Pr=
ogram variables::         The available main program variables and some =0A=
                              usefull functions from the main program.=0A* =
css::                       Customizing css lines.=0A* Customizing header::=
=0A* Customizing section::=0A* Customizing footer::=0A* Special pages::    =
         Customizing table of contents, top, about page.=0A=0A--- Customiza=
tion of the @acronym{HTML} produced by the texinfo commands ---=0A=0A* Two =
contexts::                 there are two different contexts for command=0A =
                                expansion: normal text and preformatted tex=
t.=0A* Commands without argument:: =0A* Style and accent commands::    =0A*=
 Anchors images and spaces::    Formatting of @code{@@anchor}, @code{@@imag=
e} and @code{@@sp}=0A* Text::                         Some characters are s=
pecial in @acronym{HTML} and=0A                                 should be p=
rotected=0A* Skipped commands::           =0A* References::=0A* Alignement =
commands::           @code{@@center}, @code{@@flushleft}@dots{}=0A* Paragra=
ph and preformatted region::=0A* Complex formats::              @code{@@exa=
mple}, @code{@@display}@dots{}=0A* Lists tables and quotation::=0A* Definit=
ions::=0A* Headings::=0A* Special regions::              @code{@@verbatim},=
 @code{@@cartouche}=0A* Menus::                    =0A* Indices::=0A* Footn=
otes::=0A=0A--- Indices ---=0A=0A* Indexop::                   Command Line=
 Option Index.=0A* Indexvr::                   Variable Index.=0A* Indexcp:=
:                   Concept Index.=0A=0A@end detailmenu=0A@end menu=0A@end =
ifnottex=0A@c =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=0A@node Overview=0A@chapter Overview abou=
t @emph{texi2html}=0A@uref{http://www.texinfo.org,Texinfo} is the official=
=0Adocumentation format of the @uref{http://www.gnu.org,GNU}=0Aproject. It =
uses a single source file to produce both=0Aonline information and printed =
output.=0A=0A@c much thinking about ...=0AIt is often proposed to have a wa=
y to produce=0A@acronym{HTML} from Texinfo sources, like the GNU-Info=0Afor=
mat. It is much simpler to create one converter instead=0Aof writing all do=
cumentation new in @acronym{HTML}, cause=0Athere is so much documentation i=
n Texinfo all over=0Athe world.=0A=0ASome time ago @command{makeinfo} wasn'=
t able to produce=0A@acronym{HTML} output format, but there were needs to h=
ave=0A@acronym{HTML}. This was the borning hour for=0A@emph{texi2html}. The=
 basic purpose of @emph{texi2html}=0Ais to convert Texinfo documents into @=
acronym{HTML}.=0A=0ANowadays, the main interests of @emph{texi2html} are th=
e possibilites=0Aof customization. Some important parameters of the =0Aresu=
lting files may be specified by command line options, and the use of =0Aini=
tialization=0Afiles provides further possibilities of fine tuning of most a=
spects of=0Athe generated manual. =0AInitialization files are written in =
=0A@command{perl}, like the main program. Everything being specified as=0Aa=
 command line switch may also be written down in an initialization =0Afile,=
 by giving some values to variables associated with command line =0Aoptions=
. More variables are=0Acustomizable in the initialization files, and some f=
unctions can also=0Abe defined, to be called from the main program and achi=
eve a high degree =0Aof customization.=0A=0AFor an example of what you can =
produces with=0A@emph{texi2html} have a look at the following sites:=0A@ure=
f{http://www.singular.uni-kl.de/Manual/html/}=0A=0A@menu=0A* whytexi2html::=
       Why texi2html and not makeinfo?.=0A@end menu=0A@c ------------------=
--------------------------------------=0A=0A@node whytexi2html=0A@section W=
hy texi2html and not makeinfo?=0A=0AYou would like to @acronym{HTML} files =
out of your Texinfo=0Afiles? There exist two ways which you can go.=0AThe f=
irst is to use @command{makeinfo} to produce=0A@acronym{HTML} output (@pxre=
f{Generating HTML,,Generating HTML,texinfo,Texinfo}). The second is to use=
=0A@command{texi2html}.=0A=0AThe basic idea of @command{makeinfo}'s @acrony=
m{HTML}=0Aoutput was to get a readable @acronym{HTML} output.=0ANothing sop=
histicated.=0A@c nor good styling just readable.=0AThe current development =
of texi2html is going into=0Adifferent direction.=0A=0AThe main purpose of =
texi2html development is to be able to have =0Acustomizable style and desig=
n of the created @acronym{HTML} pages. =0AThis is achieved by using command=
 line options and =0Apossibly changing initialization files to fit your=0Ao=
wn needs.=0A=0A@c The main disadvantage of @acronym{makeinfo}'s=0A@c @acron=
ym{HTML} output is your getting only one big file.=0A@c This is of course r=
eadable but not very usable. The problem=0A@c of this is, while you like to=
 have splitted chapters or=0A@c nodes the Texinfo source has to be read at =
minimum twice=0A@c times. This makes it impossible to implement this in=0A@=
c @command{makeinfo}. This would result in complete new=0A@c implementation=
 of @command{makeinfo}'s source.=0A=0A@c think more about this????=0AIn con=
trast to the @acronym{HTML} produced by @command{makeinfo=0A--html} (the @c=
ommand{makeinfo} program is part of the=0ATexinfo distribution), the @acron=
ym{HTML} output of @command{texi2html}=0Ais highly configurable. Among othe=
r differences, =0A@command{texi2html} allows you to customize the entire=0A=
page layout (like headers, footers, style sheets, etc)=0Aand the low level =
@acronym{HTML} formatting, to =0Asplit documents at various levels, and to =
use=0A@command{latex2html} to convert @code{@@tex} sections.=0A=0A@command{=
texi2html} should reasonably convert all Texinfo=0A4.6 constructs. If not, =
please send a bug report to=0A@c @email{texi2html@@mathematik.uni-kl.de}.=
=0A@email{users@@texi2html.cvshome.org}.=0A=0A@c =3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=0A@no=
de Installation=0A@chapter Installation of @emph{texi2html}=0A@cindex Insta=
llation=0A=0ATo run @command{texi2html} you need @command{perl} version =0A=
5.004 or above. The current version has not been tested=0Aextensively on ve=
rsions below 5.6, however.=0A=0A@emph{texi2html} is a standard Automake-bas=
ed distribution.=0AIf you have a source version, you should run @command{./=
configure}=0Ato regenerate the script file @file{texi2html}. This leads to=
=0Athe inclusion in @file{texi2html.pl} of three files:=0A@itemize=0A@item =
@file{MySimple.pm} which =0Ahandles the command line options, =0A@item @fil=
e{texi2html.init} the =0Adefault configuration file and =0A@item @file{T2h_=
i18n.pm} used for =0Ainternationalisation.=0A@end itemize=0A=0ATo make the =
documentation run @command{make}.=0A =0AInstalling @command{texi2html} in y=
our path should be sufficient =0Ato run it. In case you want to use a confi=
guration file for=0ALa@TeX{}toHTML when using @command{latex2html} to =0Aco=
nvert @code{@@tex} sections (@pxref{Expanding TeX regions}), or you =0Awant=
 to have some=0Adefault initialization files, you should install these file=
s =0Ain a suitable directory (usually @file{/usr/share/texi2html/} or=0A@fi=
le{/usr/local/share/texi2html/} depending on the =0A@option{--pkgdatadir=3D=
dir} option of the=0A@command{configure} script, see @ref{Using init files}=
). =0A=0A@command{make install} will=0Ado the installation for you. If you =
want to change the location of the =0Adirectories used by @command{texi2htm=
l} you should use the =0Aappropriate @command{configure} options (see @comm=
and{./configure --help}).=0A=0A@c =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=0A@node Invoking tex=
i2html=0A@chapter Invoking @command{texi2html}=0A=0ATo produce an html manu=
al, run @command{texi2html} with a texinfo file as =0Aargument. For example=
 this manual is created with:=0A=0A@example=0A$ texi2html texi2html.texi=0A=
@end example=0A=0AThe behaviour of @command{texi2html} may be changed with =
command line=0Aoptions. These command line options are always associated wi=
th corresponding=0A@command{perl} variables which may appear in init files,=
 and these =0Avariables are presented each=0Atime a switch is described. =
=0A=0AThe boolean command line switch always have=0Aa corresponding negated=
 switch, obtained by prepending @samp{no} or =0A@samp{no-} to the switch na=
me. For example @option{--nomenu} does the =0Areverse of @option{--menu}.=
=0A=0A@menu=0A* Splittig output::           The @acronym{HTML} output may b=
e split at =0A                              different levels.=0A* Output fi=
les::              Determining output file and directory names.=0A* Expansi=
on::                 Specify what region get expanded.=0A* Texinfo related =
options::  Command line options related with =0A                           =
   texinfo language features.=0A* Page layout options::       Customize out=
put page layout with command line=0A                              options=
=0A* Style options::             Customize @acronym{HTML} and text style wi=
th=0A                              command line options=0A* Expanding TeX r=
egions::     Expand @@tex and @@math regions using La@TeX{}2HTML=0A* Using =
init files::          Specifying initialization files for fine tuning.=0A@e=
nd menu=0A=0A@c --------------------------------------------------------=0A=
@node Splittig output=0A@section Specifying the splitting of the document=
=0A=0AThe @acronym{HTML} manual resulting from the processing of the Texinf=
o source=0Amay be splitted in files at different levels. This is specified =
with the=0Aoption @option{--split} which takes an argument, namely the leve=
l of splitting=0A(variable: @code{$SPLIT}). This level may be: =0A=0A@table=
 @asis=0A@item @samp{chapter}=0AThe document is split at @code{@@chapter}, =
@code{@@appendix}, or @code{@@unnumbered}.=0A@item @samp{section}=0AThe doc=
ument is split at chapter, and also at @code{@@section}, @code{@@appendixse=
c} or @code{@@unnumberedsec}.=0A@item @samp{node}=0AThe document is split a=
t each sectionning command. It is not necessarily =0Asplit at each node, if=
 the @code{@@node} structure doesn't correspond with=0Athe sectionning comm=
ands structure (see below).=0A@item @samp{none}=0AThe document isn't split.=
 This is the default.=0A@end table=0A=0AThere are two kind of commands whic=
h may be used to define sectionning=0Aelements in Texinfo: @code{@@node} an=
d structuring commands (@code{@@top},=0A@code{@@section}, @code{@@appendixs=
ubsec} and so on). =0AIn any case a node just preceding a structuring comma=
nd is=0Aconsidered to be part of the same sectionning element than that com=
mand.=0AIf the @code{@@node Top} isn't associated with a structuring comman=
d it=0Aalso defines a sectionning element.=0A=0AIn the default setting, nod=
es which aren't associated with a structuring =0Acommand are not considered=
 to be sectionning commands, they are always =0Aconsidered to =0Abe part of=
 a sectionning element defined by a structuring command.=0AIt is possible t=
o change =0Athis behaviour, by setting @option{--use-nodes} (variable @code=
{$USE_NODES}).=0AIn that case nodes not associated with structuring command=
 which aren't the =0A@samp{Top} node are also considered as sectionning com=
mands and define a=0Asectionning element.=0A=0AThe default behaviour mimics=
 @command{texi2dvi} behaviour, which ignores =0A@code{@@node} commands for =
the purprose of sectionning, while the second=0Alooks like @command{makeinf=
o} behaviour (@pxref{Two Paths, , Two Path, texinfo, Texinfo}). =0A=0AFor a=
n illustration, we show how a sample Texinfo code is divided in =0Asectionn=
ing elements with @option{--use-nodes} used or not:=0A=0A@c @multitable @co=
lumnfractions 1 1 1=0A@multitable {      @@chapter node 1} {      @@chapter=
 node 1} {      @@chapter node 1}=0A@item=0ATexinfo code=0A=0A@tab=0Adefaul=
t case=0A=0A@tab=0Awith --use-nodes=0A=0A@item=0A@*=0A@*=0A@example=0A@@nod=
e node1=0A@@chapter node 1=0Anode1 text=0A=0A@@node node2=0Anode2 text=0A=
=0A@@node node3=0Anode3 text=0A@@chapter node 3=0Achapter text=0A@end examp=
le=0A=0A@tab=0A=0Afirst element:=0A=0A@example=0A@@node node1=0A@@chapter n=
ode 1=0Anode1 text=0A=0A@@node node2=0Anode2 text=0A@end example=0A=0Asecon=
d element:=0A=0A@example=0A@@node node3=0Anode3 text=0A@@chapter node 3=0Ac=
hapter text=0A@end example=0A=0A@tab=0A=0Afirst element:=0A=0A@example=0A@@=
node node1=0A@@chapter node 1=0Anode1 text=0A@end example=0A=0Asecond eleme=
nt:=0A=0A@example=0A@@node node2=0Anode2 text=0A@end example=0A=0Athird ele=
ment:=0A=0A@example=0A@@node node3=0Anode3 text=0A@@chapter node 3=0Achapte=
r text=0A@end example=0A=0A@end multitable=0A=0A@c ------------------------=
--------------------------------=0A@node Output files=0A@section Output fil=
e and directory names=0A=0AThe default behaviour is to put files in the cur=
rent directory. The basename=0Afor the files is constructed by stripping  e=
nding @samp{.texi}, @samp{.txi}, =0A@samp{.texinfo} or @samp{.txinfo} from =
the Texinfo file name. If the =0Aoutput is split, an underscore followed by=
 a number is appended to that =0Abasename for the files corresponding with =
sectionning elements except for =0Athe top element. The files containing sp=
ecial elements pages have an underscore=0Aand a 3 letters code correspondin=
g with the kind of page (@samp{toc} for=0Atable of contents, @samp{abt} for=
 about, @samp{ovr} for overview) appended.=0AA file extension @samp{.html} =
it then appended.=0A=0AThus, if the texinfo file @file{afile.texi} is proce=
ssed and split at chapters=0Ain 3 files, the generated files will be:=0A=0A=
@example=0Aafile.html         --> @code{@@node Top} or @code{@@top} section=
=0Aafile_1.html=0Aafile_2.html=0Aafile_toc.html     --> table of contents=
=0Aafile_abt.html     --> about page=0A@end example=0A=0AQuite a lot of opt=
ions permit the modification of that behaviour.=0AIf the output isn't split=
, the file name may be overrided by @option{--output}=0A(variable @code{$OU=
T}). If the output is split, and @option{--output} is =0Aalso set, the file=
s are placed in the directory specified by the option.=0A=0AThe basename ma=
y be overrided with @option{--prefix} (variable @code{$PREFIX}).=0AIf @opti=
on{--short-ext} is given @samp{.htm} is appended instead of @samp{.html}.=
=0AThe option @option{--top-file} enables to specify a name for the=0Atop e=
lement file (variable @code{$TOP_FILE}). This can be usefull if you =0Awant=
 to use @samp{index.html} for your top element file. Similarly=0A @option{-=
-toc-file} changes the name of the table of contents file (variable=0A@code=
{$TOC_FILE}).=0A=0AIf we reuse the same example as above, but this time cal=
l=0A=0A@example=0A$ texi2html --split chapter --prefix manual --short-ext -=
-top-file index.htm --toc-file contents.htm=0A@end example=0A=0Awe get:=0A=
=0A@example=0Aindex.htm          --> @code{@@node Top} or @code{@@top} sect=
ion=0Amanual_1.htm=0Amanual_2.htm=0Acontents.htm       --> table of content=
s=0Amanual_abt.htm     --> about page=0A@end example=0A=0AThe file names ge=
nerated by @command{texi2html} differ from those generated=0Aby @command{ma=
keinfo}, as @command{makeinfo} use the node name to construct=0Athe file na=
mes while splitting at nodes. It is possible to do the same=0Awith @command=
{texi2html} by specifying @option{--node-files} (variable =0A@code{NODE_FIL=
ES}). If the output isn't split at nodes, @command{texi2html}=0Awill nevert=
heless output files with name the nodes names, without real content=0Abut r=
edirecting to the right file. With this trick it is possible for the=0Agene=
rated html manual to be a target for the cross-references of other=0Amanual=
s generated by @command{makeinfo} or @command{texi2html}. =0A@strong{Warnin=
g}: the way @command{makeinfo} (and hopefully =0A@command{texi2html})=0Ado =
html manual cross references should change in the future.=0A=0A@c ---------=
-----------------------------------------------=0A@node Expansion=0A@sectio=
n Specify what region get expanded=0A=0AThe default for @command{texi2html}=
 is to expand the @code{@@ifhtml}, =0A@code{@@html}, @code{@@menu} regions,=
 all the @code{@@ifnot} regions =0Aexcept @code{@@ifnothtml} and no other @=
code{@@if} region of output =0Astyle specific region.=0A=0AIt is possible t=
o expand other regions by setting @option{--if<region>}=0Awith @samp{<regio=
n>} replaced by the name of the region. Symetrically,=0Aif @option{--no-if<=
region>} is precised, the region @samp{<region>} is=0Aignored. In the confi=
guration file an array, @code{@@EXPAND}, holds the =0Anames of region expan=
ded in addition to html regions.=0AIf @option{--nomenu} is set, the @code{@=
@menu} sections are not expanded=0A(variable @code{$SHOW_MENU}).=0A=0A@c --=
------------------------------------------------------=0A@node Texinfo rela=
ted options=0A@section Command line options related with Texinfo constructs=
=0A  =0AMiscalleneous Texinfo related things might be specified with comman=
d line=0Aoptions. =0A=0A@table @asis=0A@item @option{--lang} =0ASets the do=
cument language similarly than with @code{@@documentlanguage} (variable =0A=
@code{$LANG}).=0A@item @option{--no-validate}=0ASuppress node cross-referen=
ce validation, same than @code{@@novalidate}.=0A@item @option{-D}=0ASets to=
 true the specified value. Equivalent to @code{@@set <value> 1}.=0A@item @o=
ption{-U}=0AClearss the specified value. Equivalent to @code{@@clear <value=
>}.=0A@item @option{-P}=0APrepend the specified directory to the list of di=
rectories where =0A@code{@@include} files are searched for before the direc=
tory of the Texinfo=0Afile being processed (the associated array is @code{@=
@PREPEND_DIRS}).=0A@item @option{-I}=0AAppend the specified directory to th=
e list of directories where =0A@code{@@include} files are searched for afte=
r the directory of the=0ATexinfo file being processed (the associated array=
 is @code{@@INCLUDE_DIRS}).=0A@end table=0A=0A@c --------------------------=
------------------------------=0A@node Page layout options=0A@section Page =
layout related command line options=0A=0AIf the option @option{--frames} is=
 specified, @acronym{HTML} frames =0Aare used. A file describing the frame =
layout is generated, and the=0Adocument page is associated with a frame whe=
re the short table of=0Acontent appears (variable @code{$FRAMES}).=0A=0AOth=
erwise the page layout cannot be customized a lot with command line =0Aopti=
ons. It is only possible to suppress sections navigation panel with=0A@opti=
on{--nosec-nav} (variable @code{$SECTION_NAVIGATION}), or=0Ato specify whet=
her footnotes should appear in the same page=0Awhere they are called or in =
a separated page with @option{--separated-footnotes}=0A(variable @code{$SEP=
ARATED_FOOTNOTES}).=0A=0A@c -----------------------------------------------=
---------=0A@node Style options=0A@section Changing @acronym{HTML} and text=
 style=0A=0AMiscalleneous style changes may be achieved with command line o=
ptions. =0A=0A@table @option=0A@item --doctype=0A@itemx --frameset-doctype=
=0AYou can specify the document DTD by setting these options. =0A@option{--=
frameset-doctype} applies to the file describing the frames when =0Aframes =
are used (corresponding variables are @code{$DOCTYPE} and =0A@code{$FRAMESE=
T_DOCTYPE}).=0A=0AFor example, the default for the document doctype is:=0A@=
example=0A<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "h=
ttp://www.w3.org/TR/html401/loose.dtd">=0A@end example=0A=0A@item --iso=0AI=
f this option is set, ISO8859 entities are used for some special symbols,=
=0Alike Copyright (variable @code{$USE_ISO}).=0A@item --css-include=0AThis =
command line switch is provided for inclusion of external css file.=0AMore =
than one file may be specified, and @samp{-} stands for the standard=0Ainpu=
t (the associated array is @code{@@CSS_FILES}, holding the file names). =0A=
=0AThe @code{@@import} lines of the file are pasted before the @command{tex=
i2html}=0Acss rules, and the external file css rules are pasted after the =
=0A@command{texi2html} css rules. This does the same than the corresponding=
=0A@command{makeinfo} switch (@pxref{HTML CSS,,HTML CSS,texinfo,Texinfo}).=
=0A=0A@item --html-xref-prefix=0AThis option sets the base directory for ex=
ternal @acronym{HTML} texinfo manuals =0A(variable @code{$EXTERNAL_DIR}). T=
he default is=0A@samp{../}.=0A@item --def-table=0AIf this option is set, @a=
cronym{HTML} tables are used to format definition =0Acommands, instead of d=
efinitions (variable @code{$DEF_TABLE}).=0A@item --short-ref=0AIf this opti=
on is set  cross-references are given without section numbers=0A(variable @=
code{$SHORT_REF}).=0A@item --number=0AIf this option is negated, sections a=
re not numbered (variable @code{$NUMBER_SECTIONS}).=0A@item --toc-links=0AI=
f this option is set, links from headings to toc entries are created (varia=
ble=0A@code{$TOC_LINKS}).=0A@end table=0A=0A@c ----------------------------=
----------------------------=0A@node Expanding TeX regions=0A@section Expan=
d @code{@@tex} and @code{@@math} regions using La@TeX{}2HTML=0A=0A@c @opind=
ex @option{}=0A@opindex @option{--l2h-l2h}=0A=0AIt is possible to use @uref=
{http://www.latex2html.org/, La@TeX{}2HTML}  =0Ato process @code{@@tex} reg=
ions and @code{@@math@{@}} commands. This=0Ais very usefull in case you wan=
t to have some mathematical constructs=0Anicely displayed in the @acronym{H=
TML} manual. The option @option{--l2h}=0Aactivates that feature (variable @=
code{$L2H}). In most cases it is better =0Ato expand @code{@@tex} sections =
in that case (@pxref{Expansion}).=0A=0AThe option @option{--l2h-l2h} enable=
s changing the name/location of the program=0Aprocessing @TeX{} (variable @=
code{$L2H_L2H}). @option{--l2h-tmp} sets the =0Adirectory used for temporar=
y files, this name shouldn't contain a dot @samp{.} =0A(variable is @code{$=
L2H_TMP}). The file specified by @option{--l2h-file} is=0Aused as La@TeX{}2=
HTML init file. It is searched at the same places than=0Ainit files (@pxref=
{Using init files}), and the default is @file{l2h.init}.=0A=0A@c ----------=
----------------------------------------------=0A@node Using init files=0A@=
section Use initialization files for fine tuning=0A=0AInitialization variab=
les are read first from=0A@file{/usr/local/etc/texi2htmlrc} (the exact loca=
tion being=0Achangeable with the @option{--sysconfdir=3Ddir} option of the=
=0A@command{configure} script, see @ref{Installation}), then from=0A@file{$=
HOME/.texi2htmlrc}. Any command-line option can override=0Athe correspondin=
g option set in init file, and the option @option{--init-file}=0Aspecifies =
an init file to be loaded, with later settings=0Aoverriding earlier ones.=
=0A=0AThe init files specified with @option{--init-file} are searched=0Afir=
st in the current directory, then in the @file{$HOME/.texi2html/}=0Adirecto=
ry, in the @file{/usr/local/etc/texi2html/} directory=0A(the exact location=
 being=0Achangeable with the @option{--sysconfdir=3Ddir} option of the=0A@c=
ommand{configure} script), and lastly in the =0A@file{/usr/local/share/texi=
2html/} directory=0A(the exact location being=0Achangeable with the @option=
{--pkgdatadir=3Ddir} option of the=0A@command{configure} script, see @ref{I=
nstallation}).=0A=0AThe default initialization options are defined in the=
=0A@file{texi2html.init} file contained in the @emph{texi2html}=0Adistribut=
ion (which gets included near the beginning of the=0A@command{texi2html} sc=
ript that gets installed).=0A=0ATo customize @file{texi2html} it is best if=
 you copy the=0Aappropriate sections from the @file{texi2html.init}=0Aconte=
nts into an appropriate local initialization file,=0Amake the necessary cha=
nges there, and then have=0A@command{texi2html} read this initialization fi=
le by one of=0Athe means described above.=0A=0A@c =3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=0A@no=
de Initialization files=0A@chapter Overview of initialization files content=
 and loading=0A=0AThe initialization files are @command{perl} files, read a=
s explained =0Ain @ref{Using init files}. You don't need to know much of @c=
ommand{perl}=0Ato do some simple changes in variable values, however, to be=
 able to =0Areally take advantage of all the features of the initialization=
 file,=0Aa good knowledge of @command{perl} is required.=0A=0AIn initializa=
tion file two kind of variables appear. These are normal=0Avariables (inclu=
ding arrays and hashes) and references on functions. =0AThe later permits t=
he dynamic redefinition of functions used to produce=0Athe @acronym{HTML} m=
anual. You should be able to change the value of some  =0Anormal variables =
without a deep knowledge of @command{perl}, by looking=0Aat the existing ex=
amples. The possible mistakes in that case could be=0Aomitted @samp{;}, and=
 bad quoting.=0A=0AInitialization file are loaded from the main program by=
=0Athe mean of a @code{require}, while in the @code{Texi2HTML::Config}=0Ana=
mespace. This means that the namespace of the main program and=0Athe namesp=
ace of inititalization files are distinct, which ensures=0Athat no name cla=
sh should happen. The variables are declared with the=0A@code{our} specifie=
r, such that it should be possible to use the =0A@code{use strict} pragma i=
n the initialization file code.=0A=0ATo avoid messing with the variables in=
 the @code{main} namespace=0Aall the global variables which could be of use=
 in the init files =0Aare in the @code{Texi2HTML} namespace. Notice that th=
e functions =0Aof the main program are still in the @code{main} namespace.=
=0A=0A@menu=0A* Redefining functions::      Function redefinition is achiev=
ed with =0A                              redefinition of references on func=
tions.=0A* Function prototypes::       Conventions used in that manual for =
function =0A                              reference prototypes display.=0A@=
end menu=0A=0A@c --------------------------------------------------------=
=0A@node Redefining functions=0A@section Redefining functions in initializa=
tion files=0A=0ATo redefine a function you must replace the corresponding f=
untion=0Areference with a reference on your function. =0AThus you should wr=
ite your function, give it a name you=0Aare certain it is unique in the @co=
de{Texi2HTML::Config} namespace,=0Aand override the value of the function r=
eference with your own =0Afunction reference. When another function from th=
e main program=0A(or from another functions of an initialization file) call=
s the reference,=0Ayour function will be used. =0A=0AFor example the functi=
on=0Areference corresponding with the function called when doing an=0Aancho=
r is called @code{$anchor}. Thus if you want to override the=0Acorrespondin=
g function=0Ayou could write:=0A=0A@example=0A# override the function refer=
ence=0A$anchor =3D \&my_own_function;=0A=0A# the function reference now ref=
ers to=0Asub my_own_function @{=0A# process arguments and return an html an=
chor=0A@}=0A@end example=0A=0A@c ------------------------------------------=
--------------=0A@node Function prototypes=0A@section Conventions used for =
function prototypes=0A=0AAs the functions are defined by a reference name, =
we will always=0Ause the reference name in function prototypes. For the fun=
ction arguments=0Awe will use @code{\@@array} for a reference on an array a=
nd similarly =0A@code{\%hash} for a reference on a hash.=0A=0AThus, the pro=
totype for the function associated with the function=0Areference @samp{$for=
matting_function} will be:=0A=0A@deftypefn {Function Reference} $text forma=
tting_function $arg1 \@@arg2=0A@code{$formatting_function} takes as first a=
rgument @var{$arg2},=0Aas second argument a reference on an array @var{\@@a=
rg2}=0Aand returns the formatted text @var{$text}.=0A@end deftypefn=0A=0ATo=
 redefined the corresponding function, you should write:=0A=0A@example=0A$f=
ormatting_function =3D \&my_formatting_function=0A=0Asub my_formatting_func=
tion($$)=0A@{=0A    my $arg1 =3D shift;=0A    my $arg2 =3D shift;=0A    # p=
repare $formatted_text=0A    .....=0A    return $formatted_text=0A@}=0A@end=
 example=0A=0A@c --------------------------------------------------------=
=0A@c -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=
=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D=0A@c =3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=0A@in=
clude custpage.texi=0A@c =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=0A@include custhtml.texi=0A@c=
 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=0A=0A@c commandline option index.=0A@node Indexop=0A@=
appendix Command Line Option Index=0A@printindex op=0A@c ------------------=
--------------------------------------=0A@node Indexvr=0A@appendix Variable=
 Index=0A@printindex vr=0A@c ----------------------------------------------=
----------=0A@node Indexcp=0A@appendix Concept Index=0A@printindex cp=0A@by=
e=0A
--dDRMvlgZJXvWKvBx
Content-Type: application/x-texinfo
Content-Disposition: attachment; filename="custhtml.texi"
Content-Transfer-Encoding: quoted-printable

@c=0A@c This file is part of the ``Texinfo to HTML Converter'' manual=0A@c =
which is part of the ``texi2html'' distribution.=0A@c=0A@c License:=0A@c =
=0A@c    Copyright (C) 2003 Free Software Foundation, Inc.=0A@c   =0A@c    =
Permission is granted to make and distribute verbatim=0A@c    copies of thi=
s manual provided the copyright notice and=0A@c    this permission notice a=
re preserved on all copies.=0A@c    =0A@c    Permission is granted to copy =
and distribute modified=0A@c    versions of this manual under the condition=
s for verbatim=0A@c    copying, provided that the entire resulting derived =
work is=0A@c    distributed under the terms of a permission notice=0A@c    =
identical to this one.=0A@c    =0A@c    Permission is granted to copy and d=
istribute translations=0A@c    of this manual into another language, under =
the above=0A@c    conditions for modified versions, except that this=0A@c  =
  permission notice may be stated in a translation approved=0A@c    by the =
Free Software Foundation.=0A@c=0A@c Revisions:=0A@c $Id$=0A@c=0A@c Author:=
=0A@c   Dumas Patrice <[email protected]>=0A@c=0A@c Description:=0A@c  =
 Informations about customizing html and text style in =0A@c   initializati=
on files.=0A@c=0A@c =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=0A=0A@node Customizing HTML=0A@chap=
ter Customizing @acronym{HTML} and text style in init files=0A=0ASome simpl=
e customization may be achieved with the redefinition of the =0Avariables =
=0Aassociated with the command line options. For the description and an =0A=
explanation of the meaning of these variables, @ref{Style options}.=0A=0AOt=
her variables and hash entries can be modified in initialization file=0Ato =
achieve more customization.=0ALastly, functions references corresponding wi=
th functions called from =0Athe main program and initialization files may =
=0Abe redefined.=0A=0A@menu=0A* Two contexts::                 there are tw=
o different contexts for command=0A                                 expansi=
on: normal text and preformatted text.=0A* Commands without argument:: =0A*=
 Style and accent commands::    =0A* Anchors images and spaces::    Formatt=
ing of @code{@@anchor}, @code{@@image} and @code{@@sp}=0A* Text::          =
               Some characters are special in @acronym{HTML} and=0A        =
                         should be protected=0A* Skipped commands::        =
   =0A* References::=0A* Alignement commands::           @code{@@center}, @=
code{@@flushleft}@dots{}=0A* Paragraph and preformatted region::=0A* Comple=
x formats::              @code{@@example}, @code{@@display}@dots{}=0A* List=
s tables and quotation::=0A* Definitions::=0A* Headings::=0A* Special regio=
ns::              @code{@@verbatim}, @code{@@cartouche}=0A* Menus::        =
            =0A* Indices::=0A* Footnotes::=0A=0A@end menu=0A=0A@c ---------=
-----------------------------------------------=0A@node Two contexts=0A@sec=
tion Two contexts for command and test expansion: preformatted and normal=
=0A=0AThere are two contexts of interest, one is the normal context, the ot=
her=0Ais a special context, called the @dfn{preformatted} context. The pref=
ormatted=0Acontext occurs when the spacing between words is kept. This is t=
he=0Acase, for example, in @code{@@display} or @code{@@example} regions, an=
d in =0Amenu comments (@pxref{Menus}). The preformatted regions are usually=
=0Arendered in @code{<pre>} elements in @acronym{HTML}.=0A=0ASome @acronym{=
HTML} elements are not allowed in preformatted context.=0AThis is the case =
for @code{<table>}, for example.=0AThus, sometime, a function doing some fo=
rmatting have to reopen and =0Areclose the preformatted context around the =
newly generated text.=0A=0AFor example, we suppose we have @acronym{HTML} r=
esulting from command =0A@example=0A@@foo=0A@@item an item=0A@@end foo=0A@e=
nd example=0Alooking like:=0A@example=0A<table><tr><td>an item</td></tr></t=
able>=0A@end example=0Awith @code{foo_item} the function formating the @cod=
e{@@foo} @code{@@item} =0Aline.=0A=0AAnd the @acronym{HTML} resulting from:=
=0A@example=0A@@example=0Asome text=0A@@end example=0A@end example=0Alooks =
like =0A@example=0A<pre>=0Asome text=0A</pre>=0A@end example=0A=0ASuppose t=
hat we want to handle the construct:=0A@example=0A@@example=0A@@foo        =
                                                                   =0A@@ite=
m an item=0A@@end foo=0A@@end example=0A@end example=0AThis could lead to t=
he invalid @acronym{HTML}:=0A@example=0A<pre>=0A<table><tr><td>an item</td>=
</tr></table>=0A</pre>=0A@end example=0ATo avoid that, @code{@@foo} will cl=
ose the preformatted context=0Aopened by @code{@@example}, and the function=
 @code{foo_item} will have to=0Areopen it, leading to=0A@example=0A<table><=
tr><td><pre>=0Aan item=0A</pre></td></tr></table>=0A@end example=0Awhich is=
 valid.=0A=0AAll such function should allready have an hash reference passe=
d as one of their=0Aarguments, the @dfn{state}. The only entry of interest =
in the corresponding=0Ahash is @code{'preformatted'} which is true if the f=
unction was called=0Ain a preformatted context.=0AOpening and closing the p=
reformatted context should then be done by calling =0Aa function from the m=
ain program, @code{main::do_preformatted} with the =0Atext and the state as=
 arguments.=0A=0AHere is an example:=0A=0A@example=0Asub foo_item=0A@{=0Amy=
 $arg1 =3D shift;=0Amy $arg2 =3D shift;=0Amy $state =3D shift;=0A=0Aif ($st=
ate->@{'preformatted'@})=0A@{=0A    my $text;=0A    # add some text to $tex=
t, =0A    # possibly using $arg1 and $arg2.=0A    return '<td>' . main::do_=
preformatted($text, $state) . '</td>';=0A@}=0Aelse=0A@{=0A    .....=0A@}=0A=
@end example=0A=0A@c ------------------------------------------------------=
--=0A@node Commands without argument=0A@section Customizing the formatting =
of commands without argument=0A=0AThis includes the commands whose name is =
a nonletter character like @code{@@@@}, =0Athe commands with lettered chara=
cters and braces=0Abut whose braces should be empty, like @code{@@TeX@{@}},=
 or some commands=0Aassociated with accentted letters like @code{@@AA@{@}}.=
 If there happens to=0Abe something within the braces, it is put after the =
command, thus=0A@example=0A@@TeX@{something@}=0A@end example=0Aleads to the=
 same than=0A@example=0A@@TeX@{@} something=0A@end example=0A=0AEach of the=
se categories of commands have two associated hash, one for normal=0Acontex=
t, the other for preformatted context. The keys of the hashes are the =0Aco=
mmand names, the associated value is the text replacing the command.=0A=0AT=
he hashes are:=0A@multitable {one nonlettered character} {in normal text} {=
in preformatted text}=0A@item command type @tab in normal text @tab in pref=
ormatted text=0A@item one nonlettered character @tab @code{%simple_map} @ta=
b @code{%simple_map_pre}=0A@item nothing in braces @tab @code{%things_map} =
@tab @code{%pre_map}=0A@end multitable=0A=0ATo change the @acronym{HTML} re=
sulting from these constructs, just change the=0Avalue. For example, if you=
 want @code{&shy;} to be outputted for @code{@@-}=0Ain normal and preformat=
ted context, write in your init file:=0A=0A@example=0A$simple_map@{'-'@} =
=3D '&shy;';=0A$simple_map_pre@{'-'@} =3D '&shy;';=0A@end example=0A=0A@c -=
-------------------------------------------------------=0A@node Style and a=
ccent commands=0A@section Customizing accent, style and other simple comman=
ds=0A=0AThe formatting of the @acronym{HTML} produced by style and indicatr=
ic =0Acommands (@code{@@tt}, @code{@@code}, =0A@code{@@email}, @code{@@titl=
efont}), the accentuation related=0Acommands taking argument (@code{@@'}, @=
code{@@udotaccent}, @code{@@dotless})=0Aand miscalleneous commands (@code{@=
@email}, @code{@@verb}, @code{@@w}, =0A@code{@@uref}, @code{@@math}, @code{=
@@asis}) is controlled by two hash, =0A@code{%style_map} for normal context=
 and @code{%style_map_pre} for=0Apreformatted context. =0A=0AThe keys are t=
he command names. The value determine how the command argument=0Ais formatt=
ed. If the value begins with @samp{"}, the result is =0Aenclosed in quotes =
@samp{`} and @samp{'}. The remaining of the value text=0A(or the value text=
 if there were no @samp{"}) is interpreted as follow:=0A=0A@itemize=0A@item=
=0AIf a text is empty the argument of the command is left as is. =0A@item=
=0AIf the text is a @samp{&} followed by a name,=0Alike @samp{&function}, t=
he name is considered to be a function name, =0Aand this function is called=
 to format the argument of the command. The=0Afirst argument of the functio=
n is the command name, the second is =0Athe command argument. For example, =
if the value associated with the=0A(fictituous) command @code{@@foo} is @co=
de{&my_func}=0Aand we have:=0A=0A@example=0Asub my_func=0A@{=0A    my @@arg=
s =3D split /,\s*/ $_[1];=0A    return "$_[0]: $args[0]" if ($args[1] =3D 1=
);=0A    return "$args[0]";=0A@}=0A@end example=0A=0AThe result of =0A@exam=
ple =0A@@foo@{truc, 1@}=0A@@foo@{truc, bidule@}=0A@end example =0Awill be=
=0A@example=0Afoo: truc=0Atruc=0A@end example=0A@item=0AIf the text is a wo=
rd, it is considered to be an @acronym{HTML} element=0Aname, and the argume=
nt is enclosed between the element opening=0Aand the element closing. For e=
xample, if the value is @code{elem}, the=0Aresulting @acronym{HTML} is @cod=
e{<elem>@var{arg}</elem>}.=0ASimilarly @code{"quoted} leads to=0A@code{`<qu=
oted>@var{arg}</quoted>'}.=0A@item=0AIf the text is a word followed by some=
 text, =0Athe word and is interpreted as above, and the=0Atext is considere=
d to be the attributes text of the element. =0AThus @code{elem class=3D"ele=
m"} leads to =0A@code{<elem class=3D"elem">@var{arg}</elem>}.=0A@end itemiz=
e=0A=0ASome remarks are in order:=0A=0A@itemize=0A@item =0AThe command argu=
ment is allready formatted as @acronym{HTML}.=0A@item=0AThe nonlettered acc=
ent commands which following character is considered=0Ato be the argument (=
like in @code{@@`a}) should be keys of the=0Ahash @code{%accent_map} hash, =
even if no value is associated.=0A@item=0A@code{@@math} is handled differen=
tly if La@TeX{}2HTML is used.=0A@end itemize=0A=0A@c ----------------------=
----------------------------------=0A@node Anchors images and spaces=0A@sec=
tion Formatting of special simple commands=0A=0AThe formatting of special s=
imple commands is controlled by functions. To=0Acustomize the output, the c=
orresponding function references should be=0Aredefined.=0A=0AThe formatting=
 of anchors is controlled by @code{$anchor}, but the function=0Aassociated =
with the function reference does more, it is usefull=0Ato produce a referen=
ce target or link.=0A@deftypefn {Function Reference} $anchor anchor $identi=
fier $href $text $attributes=0AIf @var{$identifier} is not empty, this valu=
e should be used to create=0Aa target for links (typically associated with =
a name or id =0Aattribute in @acronym{HTML}).=0AThe @var{$href} argument sp=
ecifies a hpertextual reference which should be=0Aused to link to a target.=
=0AIn case both @var{$identifier} and  @var{$href} are given the text produ=
ced=0Ashould be both a target for @var{$identifier} and a link to @var{$hre=
f}.=0A@var{$text} is the text to be displayed. =0A@var{$attributes} are add=
itional attributes.=0AIt should be reasonable to assume that the attributes=
 are for a @code{<a>}=0A@acronym{HTML} element. =0A@end deftypefn=0A=0AThe =
formatting of @code{@@image} is controlled by:=0A@deftypefn {Function Refer=
ence} $image image $file_name $basename $preformatted=0A@var{$file_name} is=
 the image file name, @var{$basename} is the file name=0Awithout extension.=
 @var{$preformatted} is true if the image appears in =0Apreformatted text.=
=0A@end deftypefn=0A=0AThe formatting of @code{@@sp} is controlled by:=0A@d=
eftypefn {Function Reference} $sp sp $number $preformatted=0A@var{$number} =
is the numeric argument of @code{@@sp}.=0A@var{$preformatted} is true if th=
e @code{@@sp} appears in preformatted text.=0A@end deftypefn=0A=0A@c ------=
--------------------------------------------------=0A@node Text=0A@section =
Protecting special @acronym{HTML} characters in text=0A=0ASome characters a=
re special in @acronym{HTML} (@samp{&}, @samp{"}, @samp{<} and=0A@samp{>}) =
and should be protected.=0AThis is done by the function associated with the=
 function reference=0A=0A@deftypefn {Function Reference} $protected_text pr=
otect_html $text=0AThe function processes the unprotected text @var{$text} =
and returns=0Athe resulting protected text @var{$protected_text}.=0A@end de=
ftypefn=0A=0A@c --------------------------------------------------------=0A=
@node Skipped commands=0A@section Customizing ignored commands and text=0AT=
he ignored commands are the keys of two hashes: @code{%to_skip_texi}=0Afor =
commands skipped during the first pass (expansion of macros and values)=0Aa=
nd @code{%to_skip} for the commands skipped during the second pass=0A(deter=
mination of the document structure).=0A=0AThe associated value determines h=
ow things following the ignored=0Acommand are handled. There are four possi=
bilities:=0A=0A@table @asis=0A@item @code{1}=0Aonly the command is ignored,=
=0A@item @code{space}=0Aspaces following the command are skipped,=0A@item @=
code{arg}=0Aan argument following the command is skipped,=0A@item @code{lin=
e}=0AThe line following the command is skipped.=0A@end table=0A=0A@c ------=
--------------------------------------------------=0A@node References=0A@se=
ction References=0A=0AThe references are produced with two function referen=
ces, one for the reference=0Ato external manuals the other for refences wit=
hin the manual. =0A=0A@deftypefn {Function Reference} $text external_ref $c=
ommand $section $book $node_and_file $href $cross_ref_name=0AThis function =
formats a reference to an external texinfo manual.=0AThe @var{$command} is =
the ref command (@code{ref}, @code{xref} or =0A@code{pxref}, in text, at se=
ntence beginning or in parenthesis).=0AThe optionnal @var{$section} argumen=
t is the section in the book and =0A @var{book} is the book title.=0A@var{$=
node_and_file} is the node and file name formatted according to the =0Aconv=
ention used in info: @samp{(file)node}. @var{$href} it an hypertextual=0Are=
ference to the distant manual constructed using the same conventions=0Athan=
 @command{makeinfo}. @var{$cross_ref_name} is an optionnal cross=0Areferenc=
e name appearing in the reference command. This function returns=0Athe text=
 corresponding with the external html manual reference.=0AThis function ret=
urns the full formatted text of the external reference.=0A@end deftypefn=0A=
=0A@deftypefn {Function Reference} $text internal_ref $command $href $short=
_name $name $is_section=0AThis function formats a reference to a node in th=
e current manual.=0AThe @var{$command} is the ref command (@code{ref}, @cod=
e{xref} or =0A@code{pxref}, in text, at sentence beginning or in parenthesi=
s).=0A@var{$href} it an hypertextual reference linking to the corresponding=
=0Anode or section. @var{$short_name} and @var{$name} hold the text for the=
 =0Areference but @var{$short_name} can be the node name which is assumed t=
o =0Abe shorter than the section name.=0A@var{$is_section} is a boolean tru=
e if the reference is a reference to a =0Asection. This function returns th=
e full formatted text of the internal =0Areference.=0A@end deftypefn=0A=0A@=
c --------------------------------------------------------=0A@node Aligneme=
nt commands=0A@section Commands used for centering and flushing of text=0A=
=0AWhen a command controlling the alignement of text is used (@code{@@cente=
r},=0A@code{@@flushleft} and @code{@@flushright}), the main program takes=
=0Acare of opening and closing paragraphs. The only thing which can be=0Aco=
ntrolled is an argument given to the function doing the formatting of =0Apa=
ragraphs. This is achieved by the mean of a hash, @code{%paragraph_style}.=
=0AThe keys are the names of the Texinfo commands, the value is the argumen=
t=0Apassed down to the function doing the formatting of the paragraphs. =0A=
@xref{Paragraph and preformatted region}.=0A=0A@c -------------------------=
-------------------------------=0A@node Paragraph and preformatted region=
=0A@section Formatting a paragraph or a preformatted region=0A=0AThe format=
ting of a paragraph region or a preformatted region, is controlled=0Aby fun=
ction references:=0A=0A@deftypefn {Function Reference} $paragraph_text para=
graph $text $alignement=0AThis function formats a paragraph. @var{$text} is=
 the text of the paragraph,=0A@var{$alignement} is a specifier for the alig=
nement of the paragraph.=0A@xref{Alignement commands}.=0A@end deftypefn=0A=
=0A@deftypefn {Function Reference} $preformatted_text preformatted $text $r=
egion_name=0AThis function formats a preformatted region. @var{$text} is th=
e text of the=0Apreformatted region, @var{$region_name} is the name of the =
command opening=0Athe preformatted region (@code{example}@dots{}, see @ref{=
Complex formats}) =0Aor a identifier for the preformatted context (for exam=
ple =0A@code{menu-comment}, see @ref{Menus}).=0A=0AThe alignment commands a=
re not taken into account, as the spaces are=0Apreserved in preformatted re=
gions, you should flush and center by hand.=0A@end deftypefn=0A=0A@c ------=
--------------------------------------------------=0A@node Complex formats=
=0A@section Formatting of complex formats (@code{@@example}, @code{@@displa=
y}@dots{})=0A=0AHere we see how a whole complex format is formatted. For th=
e formatting=0Aof the text, see @ref{Paragraph and preformatted region}.=0A=
=0AThe formatting of the complex formats is ultimately controlled by a=0Afu=
nction, however the default for this function uses a hash reference and =0A=
changing the hash reference values should be enough in most cases. This=0Ah=
ash reference is called @code{$complex_format_map}. It has a key for each=
=0Aof the complex format commands (@code{example}, @code{smallexample}, =0A=
@code{lisp}, @code{smalllisp}, @code{display}, @code{smalldisplay}, =0A@cod=
e{format}, @code{smallformat}).=0A=0AThe associated value is also a referen=
ce on a hash. The keys are @code{begin}=0Aand @code{end}. An eval of @code{=
begin} should lead to the beginning of the=0Aformatted @acronym{HTML}, an e=
val of @code{end} should lead to the end of the =0Aformatted @acronym{HTML}=
. The enclosed text will be formatted as described in=0A@ref{Paragraph and =
preformatted region}, and the name of the complex=0Aformat will be availabl=
e to the function formatting the text.=0A=0AIf you aren't satisfied with th=
is scheme, you can redefine the following=0Afunction reference for a better=
 control over the complex format formatting:=0A=0A@deftypefn {Function Refe=
rence} $complex_format_text complex_format $format_name $preformatted_text=
=0A=0A@var{$format_name} is the complex format name, @var{$preformatted_tex=
t} is the =0Atext allready formatted as described in @ref{Paragraph and pre=
formatted region}.=0AThis function returns the whole complex format.=0A@end=
 deftypefn=0A=0A@c --------------------------------------------------------=
=0A@node Lists tables and quotation=0A@section Customizing the formatting o=
f lists, tables and quotations=0A=0AThe formatting of lists and tables is d=
one at two levels:=0A@itemize=0A@item =0AAt the level of the whole region (=
table, list or quotation),=0A@item=0AAt the level of the individual items, =
rows or cells of the list or table.=0A@end itemize=0A=0A@menu=0A* Table and=
 list items::=0A* Whole table list and quotation::=0A@end menu=0A=0A@c -=3D=
-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=
=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D=0A@node Table and list items=0A@subsect=
ion Formatting individual table and list items=0A=0AIn texinfo it is possib=
le to give @code{@@itemize} or table command (hereafter=0Acalled a @dfn{for=
mat command}) a @dfn{formatting command}. =0AFor example @code{@@minus} is =
the formatting command here:=0A@example=0A@@table @@minus=0A@end example=0A=
=0AThe default is to apply the command to the text item, however it is poss=
ible=0Ato avoid it.=0AThe hash @code{%special_list_commands} has an entry f=
or each of the =0Aformat command. Each of these entries is a hash reference=
. If a formatting=0Acommand is a key of the hash reference, then the format=
ting command is not=0Aapplied to the text item for that format command. For=
 example, if we have:=0A=0A@example=0A$special_list_commands@{'itemize'@} =
=3D @{ 'bullet' =3D> '' @};=0A@end example=0A=0Aand we have the following @=
code{@@itemize}:=0A@example=0A@@itemize @@bullet=0A@@item an item=0A@@end i=
temize=0A@end example=0A=0Athen @code{@@bullet} will not be applied to @cod=
e{an item}.=0A=0A@table @emph=0A@item lists=0AThe items of lists are format=
ted using the following function reference:=0A@deftypefn {Function Referenc=
e} $list_item list_item $text $format $command=0AThis function formats the =
text between @code{@@item} commands. @var{$text} =0Ais the text correspondi=
ng with the item. @var{$format} is the type of format,=0A@samp{itemize} or =
@samp{enumerate}. @var{$command} is the formatting command=0Agiven in argum=
ent to @code{@@itemize}.=0A@end deftypefn=0A=0A@item two column tables=0ATh=
e two columns tables (@code{@@table}, @code{@@ftable} and @code{@@vtable}),=
 =0Aitems are formatted using two function references,=0Aone for the first =
line located on the @code{@@item} line corresponding=0Awith the first colum=
n, the other for the text appearing on the=0Afollowing lines, corresponding=
 with the second column text.=0A=0A@deftypefn {Function Reference} $table_i=
tem table_item $item_text $index_label_text $format $command=0AThis functio=
n is used to format the text on the @code{@@item} line.=0A@var{$text_item} =
is the text line. In case there is an index entry =0Aassociated with the @c=
ode{@@item} (as with @code{@@ftable} and =0A@code{@@vtable}), @var{$index_l=
abel_text} is the text inserted at =0Athe place where an index entry appear=
s. @xref{Index entry place}.=0A@var{$format} is the type of format,=0A@samp=
{table}, @samp{ftable} or @samp{vtable}. @var{$command} is the formatting c=
ommand=0Agiven in argument to the table format command.=0A@end deftypefn=0A=
=0A@deftypefn {Function Reference} $table_line table_line $text=0AThis func=
tion is used to format the text on the lines following=0Athe @code{@@item} =
line. @var{$text} is the corresponding text. =0A@end deftypefn=0A=0A@item m=
ultitable=0AThe multitable elements formatting is controlled by the functio=
ns associated=0Awith two function references. One for a cell, and the other=
 for a row.=0A=0A@deftypefn {Function Reference} $multitable_cell cell $tex=
t=0AThis function is used to format the text of a multitable cell, the text=
 =0Afollowing a @code{@@item} or a @code{@@tab}.=0A@var{$text} is the corre=
sponding text. =0A@end deftypefn=0A=0A@deftypefn {Function Reference} $mult=
itable_row row $text=0AThis function is used to format a multitable row. @v=
ar{$text} is=0Athe row text, with cells allready formatted with the @code{$=
cell}=0Afunction reference.=0A@end deftypefn=0A@end table=0A=0A@c -=3D-=3D-=
=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D=
-=3D-=3D-=3D-=3D-=3D-=3D-=3D=0A@node Whole table list and quotation=0A@subs=
ection Formatting of a whole table, list or quotation=0A=0AIf the Texinfo c=
ommand is a key of the @code{%format_map}, the associated=0Avalue is used t=
o specify the formatting of the construct, otherwise a function =0Ais calle=
d. =0AThe value in @code{%format_map} associated with a command is interpre=
ted =0Asimilarly with values associated with more simpler commands:=0A=0A@i=
temize=0A@item=0AIf the text is a word, it is considered to be an @acronym{=
HTML} element=0Aname, and the whole table or list is enclosed between the e=
lement opening=0Aand the element closing.=0A@item=0AIf the text is a word f=
ollowed by some text, =0Athe word and is interpreted as above, and the=0Ate=
xt is considered to be the attributes text of the element. =0A@end itemize=
=0A=0AIn case the @code{%format_map} isn't used, a function reference calle=
d=0A@code{$table_list}=0Ashould be redefined, the associated function will =
be called each time=0Aa command isn't found in @code{%format_map}.=0A=0A@de=
ftypefn {Function Reference} $whole_table_list table_list $command $text=0A=
@var{$command} is the Texinfo command name, @var{$text} is the formatted=0A=
items.=0A@end deftypefn=0A=0A@c -------------------------------------------=
-------------=0A@node Definitions=0A@section Definition commands formatting=
=0A=0AThe formatting of definition commands is controlled by a hash and fou=
r =0Afunctions. The hash describes how the text on the definition line is =
=0Ainterpreted, the functions control the formatting of the definition line=
=0Aand the definition function text.=0A=0A@menu=0A* Definition line::=0A* D=
efinition formatting::=0A@end menu=0A=0A@c -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D=
-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=
=3D-=3D=0A@node Definition line =0A@subsection Customizing the interpretati=
on of a definition line=0A=0AThe keys of the hash @code{%def_map} are defin=
ition command names.=0AThere are two types of entries:=0A=0A@itemize=0A=0A@=
item If the command is a shortcut for =0Aanother definition command the val=
ue is a text and the definition =0Acommand is replaced by the text.=0A=0AFo=
r example if we have:=0A@example=0A$def_map@{'deftruc'@} =3D '@@defvr @{A t=
ruc@}';=0A@end example=0A=0Aand a line like=0A@example =0A@@deftruc var=0A@=
end example=0A=0Athe line will be transformed in=0A@example=0A@@defvr @{A t=
ruc@} var=0A@end example=0A=0A@item=0AIf the command isn't a shortcut, it i=
s associated with an array=0Areference. The first element is @samp{f}, @sam=
p{v} or @samp{t} corresponding=0Awith the index type (@samp{f} for function=
, @samp{v} for variable,=0A@samp{t} for type).=0A=0AThe remaining of the ar=
ray describes how to interpret the text following=0Athe definition command =
on the definition command line. If the entry begins=0Awith @samp{@{}, then =
the corresponding item is the next bracketed item=0Aor the next word. The r=
emaining of the entry word specify what corresponds=0Awith this item. Curre=
ntly the word may be @samp{category}, @samp{name},=0A@samp{type}, @samp{cla=
ss} and @samp{arg}.=0A=0AFor example if we have=0A@example=0Adef_map@{'defv=
r'@} =3D [ 'v', '@{category', '@{name' ];=0A@end example=0A=0AThe first bra=
cketed item following @code{@@defvr} is considered=0Ato be the category and=
 the next one is the name. The index associated=0Awith the definition line =
is the variables index.=0A@end itemize=0A=0A@c -=3D-=3D-=3D-=3D-=3D-=3D-=3D=
-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=
=3D-=3D-=3D=0A@node Definition formatting=0A@subsection Customization of th=
e definition formatting=0A=0AFour functions are used when formatting a defi=
nition command:=0A=0A@table @asis=0A@item category name=0A@deftypefn {Funct=
ion Reference} $category definition_category $category_or_name $class $styl=
e=0AThis function precise a category or an index entry name associating a c=
lass =0A@var{$class} (if given) with @var{$category_or_name}. The @var{$sty=
le} of the=0Adefinition may be @samp{f}, for function, @samp{v}, for variab=
le or @samp{t}, =0Afor type.=0A@end deftypefn=0A@item formatting of the def=
inition line=0A@deftypefn {Function Reference} $line def_line $category $na=
me $type $arguments $index_label=0AThis function formats the definition lin=
e. @var{$category} is the category=0Aformatted with @code{$definition_categ=
ory}, @var{$name}, @var{$type} and =0A@var{arguments} are the element of th=
e definition line. @var{$index_label} is=0Athe text inserted at the place w=
here an index entry appears. =0A@xref{Index entry place}.=0A@end deftypefn=
=0A=0A@item definition text=0A@deftypefn {Function Reference} $definition_t=
ext def_item $text=0AThis function formats the definition text, @var{$text}=
.=0A@end deftypefn=0A=0A@item the whole definition=0A@deftypefn {Function R=
eference} $definition def $text=0AThis function formats the whole definitio=
n. The definition line and text =0Aformatted by the above functions are in =
@var{$text}.=0A@end deftypefn=0A=0A@end table=0A=0A@c ---------------------=
-----------------------------------=0A@node Headings=0A@section Customizing=
 headings formatting=0A=0AA function controls the formatting of sectionning=
 element headings, =0Awith the corresponding function reference:=0A@deftype=
fn {Function Reference} $heading_text heading \%element_reference=0AThe @va=
r{\%element_reference} is a reference on a hash corresponding=0Awith the se=
ctionning element. The following keys are of interest:=0A@table @code=0A@it=
em text=0AThe heading text=0A@item name=0AThe heading text without section =
number=0A@item node=0Atrue if the sectionning element is a node without ass=
ociated structuring command=0A@item level=0AThe level of the element in the=
 document tree. @samp{0} is for @code{@@top},=0A@samp{1} for @code{@@chapte=
r} and so on=0A@item tag_level=0Athe sectionning element name, with @code{@=
@raisesections} and =0A@code{@@lowersections} taken into account=0A@end tab=
le=0A@end deftypefn=0A=0A@c -----------------------------------------------=
---------=0A@node Special regions=0A@section Formatting of special regions =
(@code{@@verbatim}, @code{@@cartouche})=0A=0ARegions corresponding with raw=
 text, like @code{@@verbatim}, @code{@@html}=0Aor @code{@@tex} are formatte=
d according to the following function reference:=0A=0A@deftypefn {Function =
Reference} $raw_region raw $command $text=0A@var{$command} is the command n=
ame, @var{$text} is the raw text.=0A@end deftypefn=0A=0AIf La@TeX{}2HTML is=
 used, @code{@@tex} regions are handled differently,=0Afrom within the main=
 program.=0A=0AThe @code{@@cartouche} command formatting is controlled by t=
he=0Afunction reference:=0A=0A@deftypefn {Function Reference} $cartouche ca=
rtouche $text=0A@var{$text} is the text appearing within the cartouche.=0A@=
end deftypefn=0A=0A@c -----------------------------------------------------=
---=0A@node Menus=0A@section Menu formatting=0A=0ATo understand how the for=
matting of menus is controlled, the different=0Aparts of a menu are first d=
escribed, then how to control the formatting=0Aof each of these parts.=0A=
=0A@menu=0A* Menu parts::                 A menu consists in menu entry and=
 menu =0A                               comments=0A* Menu formatting::=0A@e=
nd menu=0A=0A@c -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=
=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D=0A@node Menu parts=
=0A@subsection The structure of a menu=0A=0AIn @emph{texi2html}, a menu is =
considered to be composed of 2 parts, the=0A@dfn{menu entries} and the @dfn=
{menu comments}. Menu entries are further =0Adivided in an @dfn{entry link}=
 and optionnaly an @dfn{entry description}.=0AThe entry link consists in a =
node name and an optionnal  menu entry=0Aname.=0A=0AA menu entry begins wit=
h @samp{*} at the beginning of the line. It begins=0Awith the entry link, f=
ollowed by the description. The description spans until=0Athe next menu ent=
ry, or some text begining at the first character of a line=0Aor an empty li=
ne, not contained within a command block which begun in the =0Adescription.=
 An empty line or a line with text at the first character=0Astarts a menu c=
omment, which spans until the next menu entry.=0A=0AHere is an illustration=
 of these rules:=0A=0A@example=0A@@menu=0A* node name: entry name.        d=
escription begins=0A   description continues=0A* another menu entry::=0A   =
description begins=0A                    description continues=0A=0A   A me=
nu comment, after an empty line=0A=0A* node::                        descri=
ption begins=0AA menu comment. The line starts at the first character=0A=0A=
* last entry::         description begins @emph{text=0Aof the description, =
even if the line begins at the first character,=0Abecause we are in @@emph}=
.=0A@@end menu=0A@end example=0A=0A@c -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=
=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D=
=0A@node Menu formatting=0A@subsection The formatting of the different menu=
 components=0A=0ASome processing of the menu entry is done in the main prog=
ram without=0Aa possibility of total control. =0AHowever this process may b=
e influenced=0Aby some variable values. =0A=0AIn the default case, the name=
 of the section corresponding with the =0Anode is used instead of the node =
name. If @code{$NODE_NAME_IN_MENU} is true,=0Ahowever, node names are used.=
 If @code{$AVOID_MENU_REDUNDANCY}=0Ais true and menu entry equal menu descr=
iption the description isn't printed.=0ALikewise, if node or section name e=
qual entry name, do not print entry name.=0A=0AA symbol, @code{$MENU_SYMBOL=
} is put at the beginning of menu entries=0Awhen the node name is used. If =
@code{$UNNUMBERED_SYMBOL_IN_MENU} it is also=0Aput at the beginning of unnu=
mbered section names.=0A=0AThe menu comments are considered to be preformat=
ted text. The style =0Aassociated with this preformatted text is determined=
 by =0A@code{$MENU_PRE_STYLE}. The css class associated with menu comments =
is =0A@code{menu-comments}.=0A=0AAlthough the main program controls the tex=
t of the different components,=0Acontrol over the formatting of the compone=
nts themselves is achieved=0Athrough the call of 5 functions. The correspon=
ding function references =0Ashould be redefined to change the default forma=
tting.=0A=0AThree function references are associated with the formatting of=
 the =0Adifferent parts of a menu:=0A@deftypefn {Function Reference} $link =
menu_link $link_text \%state $href=0A@var{$link_text} is the text correspon=
ding with the link name, @var{$href}=0Ais the link hypertextual reference. =
@var{$href} may be absent. @var{\%state}=0Aholds informations about the cur=
rent context. The only key which could be=0Aof interest is @code{preformatt=
ed}, true if the context is a preformatted=0Acontext. @xref{Two contexts}.=
=0A@end deftypefn=0A=0A@deftypefn {Function Reference} $description menu_de=
scription $description_text \%state=0A@var{$description_text} is the text o=
f the menu description. @var{\%state}=0Ashould be used similarly than for t=
he menu link.=0A@end deftypefn=0A=0A@deftypefn {Function Reference} $menu_c=
omment menu_comment $text=0A@var{$text} is the text of the menu comment. It=
 is in a preformatted =0Aenvironment.=0A@end deftypefn=0A=0AThe following f=
unction reference controls the formatting of a wole menu:=0A=0A@deftypefn {=
Function Reference} $menu menu $menu_components_text=0A@var{$menu_component=
s_text} is the formatted menu components text, obtained=0Aas explained abov=
e.=0A@end deftypefn=0A=0AThe last function reference corresponds with a spe=
cial case. It=0Ais used when a menu entry appears within another block comm=
and, to=0Aavoid the possibilities of invalid @acronym{HTML} production.=0AI=
n that case the menu description and menu comments are not formatted =0Aspe=
cially, but treated like normal text.=0A@deftypefn {Function Reference} $li=
nk simple_menu_link $link_text $href=0A@var{$link_text} is the text corresp=
onding with the link name, @var{$href}=0Ais the link hypertextual reference=
.=0A@end deftypefn=0A=0A@c ------------------------------------------------=
--------=0A@node Indices=0A@section Indices formatting=0A=0ATwo different t=
hings needs to be handled for indices formatting, the place=0Awhere the ind=
ex term appears, the index entry, and the index list itself.=0AThe indexing=
 commands like @code{@@cindex} determines where index entries=0Aappear, and=
 the index list is printed with a @code{@@printindex} command. =0A=0A@menu=
=0A* Index entry place::             Index entries in the main document are=
 =0A                                  targets for hypertext references=0A* =
Index list::                    Customizing the formatting of the index lis=
t=0A@end menu=0A=0A@c -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=
=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D=0A@node Index e=
ntry place=0A@subsection Formatting of index entries=0A=0AIndex entry place=
s in the main text may be the target for hypertext =0Areferences. Their for=
matting=0Ais controlled by the function associated with the following funct=
ion =0Areference:=0A=0A@deftypefn {Function Reference} $target index_entry_=
label $identifier $preformatted=0A@var{$identifier} should be used to creat=
e=0Aa target for links (typically associated with a name or id =0Aattribute=
 in @acronym{HTML}).=0A@var{$preformatted} is true if the index entry appea=
red in preformatted text.=0A@end deftypefn=0A=0A@c -=3D-=3D-=3D-=3D-=3D-=3D=
-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=
=3D-=3D-=3D-=3D=0A@node Index list=0A@subsection Customizing the formatting=
 of index lists=0A=0AThe index entries are sorted alphabetically. A whole i=
ndex list is =0Aconsidered to be composed of letter entries. A letter entry=
 is composed=0Aby all the index entries beginning with that letter. A lette=
r may=0Abe a non alphabetical character, but we call it letter here.=0A=0AA=
n index summary appears at the beginning and at the end of an index list,=
=0Aand should be used to jump directly to a letter entry. Indices lists=0Am=
ay be split across pages, thus the different letters may appear on differen=
t=0Afiles. The number of index entries appearing on each page is determined=
=0Aby a variable @code{$SPLIT_INDEX}.=0A=0AThe formatting of all these elem=
ents is controlled by the following=0Afunction references:=0A=0A@table @emp=
h=0A@item formatting of a letter in a summary=0A@deftypefn {Function Refere=
nce} $letter summary_letter $letter $file $identifier=0AThis function is us=
ed to format a letter appearing in a summary, refering=0Ato a letter entry =
in the index list.=0A@var{$letter} is the letter. @var{$file} is the file n=
ame where the letter=0Aentry appears. More precisely, it is empty when the =
letter entry is on the =0Asame page than the summary, it contains the file =
name when the index page=0Ais split accross page. @var{$identifier} is an i=
dentifier for the target =0Aletter entry. =0A@end deftypefn=0A=0A@item form=
atting of a summary=0A@deftypefn {Function Reference} $summary index_summar=
y \@@alphabetical_letters \@@nonalphabetical_letters=0A@var{\@@alphabetical=
_letters} and @var{\@@nonalphabetical_letters} contain the=0Aformatted summ=
ary letters, formatted with the above function.=0A@end deftypefn=0A=0A@item=
 formatting of an index entry=0A@deftypefn {Function Reference} $entry inde=
x_entry $entry_href $entry_text $section_href $section_heading=0A@var{$entr=
y_href} is a reference to the place where the index entry =0Aappeared, @var=
{$entry_text} is the corresponding text. @var{$section_href}=0Ais a referen=
ce to the beginning of the sectionning element containing =0Athe index entr=
y, @var{$section_heading} is the heading of the element.=0A@end deftypefn=
=0A=0A@item formatting of letter entry=0A@deftypefn {Function Reference} $l=
etter_entry index_letter $letter $identifier $index_entries_text=0AThis fun=
ction formats a letter entry, consisting in all the index entries =0Abeginn=
ing with this letter. @var{$letter} is the letter, @var{$identifier} =0Asho=
uld be used to create a target for links (typically links from summaries),=
=0Aand @var{$index_entries_text} is the text of the index entries formatted=
 as =0Adescribed above.=0A@end deftypefn=0A=0A@item formatting of whole ind=
ex=0A@deftypefn {Function Reference} $index print_index $index_text $index_=
name=0A@var{$index_text} is the text of all the index entries grouped by le=
tter=0Aappearing in that page formatted as above. @var{index_name} is the n=
ame of=0Athe index, the argument of @code{@@printindex}.=0A@end deftypefn=
=0A@end table=0A=0A@c -----------------------------------------------------=
---=0A@node Footnotes=0A@section Customizing the footnotes formatting=0A=0A=
Each footnote is associated with a footnote entry. Several footnote entries=
=0Aare grouped in a footnote section. When a footnote appears, two things m=
ust=0Abe formatted: in the main text the place where the footnote appear=0A=
and the footnote text. =0A=0ATwo functions, with corresponding function ref=
erences control the formatting=0Aof the footnotes:=0A=0A@deftypefn {Functio=
n Reference} {(\@@lines $text_for_document)} foot_line_and_ref $number_in_d=
oc $number_in_page $footnote_id $place_id $document_file $footnote_file \@@=
lines \%state=0A@var{$number_in_doc} is the footnote number in the whole do=
cument, =0A@var{$number_in_page} is the footnote number in the current page=
.=0A@var{$footnote_id} is an identifier for the footnote in the footnote te=
xt=0Awhich should be used to make target for references to that footnote,=
=0Awhile @var{$place_id} is an identifier for the location of the footnote=
=0Ain the main document. Similarly, @var{$document_file} is the file name=
=0Aof the file containing the text where the footnote appears in the main =
=0Adocument, while @var{$footnote_file} is the file name of the file where =
=0Athe footnote text appears. =0A=0A@var{\@@lines} is a reference on an arr=
ay containing the footnote text=0Alines, allready formatted.=0AAnd @var{\%s=
tate} holds informations about the context at the footnote=0Aplace in the m=
ain document. As usual the most usefull entry is =0A@code{preformatted} whi=
ch is true if the footnote appears in a preformatted =0Acontext. =0A=0AThis=
 function returns a reference on an array, @var{\@@lines} containing=0Athe =
updated footnote text for the footnote entry, and @var{$text_for_document},=
=0Athe text appearing at the footnote place in the main document, linking=
=0Ato the footnote entry.=0A@end deftypefn=0A=0AThe following function is o=
nly used when footnotes are at the bottom=0Aof a page and the document is s=
plit. =0AFor customization of the footnotes page in case they are on a sepa=
rated =0Apage or section, @ref{Special pages layout}. For =0Athe determinat=
ion of the footnote locations, @ref{Page layout options}.=0A=0A@deffn {Func=
tion Reference} foot_section \@@footnotes_lines=0AThis function formats a g=
roup of footnotes. @var{\@@footnotes_lines} is a=0Areference on an array ho=
lding the lines of all the footnote entries=0Aformatted as explained above.=
 This function modifies the reference.=0A@end deffn=0A=0A@c ---------------=
-----------------------------------------=0A@c -=3D-=3D-=3D-=3D-=3D-=3D-=3D=
-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=
=3D-=3D-=3D=0A@c =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=0A
--dDRMvlgZJXvWKvBx
Content-Type: application/x-texinfo
Content-Disposition: attachment; filename="custpage.texi"
Content-Transfer-Encoding: quoted-printable

@c=0A@c This file is part of the ``Texinfo to HTML Converter'' manual=0A@c =
which is part of the ``texi2html'' distribution.=0A@c=0A@c License:=0A@c =
=0A@c    Copyright (C) 2003 Free Software Foundation, Inc.=0A@c   =0A@c    =
Permission is granted to make and distribute verbatim=0A@c    copies of thi=
s manual provided the copyright notice and=0A@c    this permission notice a=
re preserved on all copies.=0A@c    =0A@c    Permission is granted to copy =
and distribute modified=0A@c    versions of this manual under the condition=
s for verbatim=0A@c    copying, provided that the entire resulting derived =
work is=0A@c    distributed under the terms of a permission notice=0A@c    =
identical to this one.=0A@c    =0A@c    Permission is granted to copy and d=
istribute translations=0A@c    of this manual into another language, under =
the above=0A@c    conditions for modified versions, except that this=0A@c  =
  permission notice may be stated in a translation approved=0A@c    by the =
Free Software Foundation.=0A@c=0A@c Revisions:=0A@c $Id$=0A@c=0A@c Author:=
=0A@c   Dumas Patrice <[email protected]>=0A@c=0A@c Description:=0A@c  =
 Informations about customizing page layout in initialization files.=0A@c=
=0A@c =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=0A=0A@node Changing the page layout=0A@chapter Fin=
e tuning of the page layout=0A=0ASome features of the page layout might be =
specified with command line=0Aoptions, the corresponding variables are desc=
ribed in =0A@ref{Page layout options}.=0AFine tuning of the page layout may=
 be achieved=0Awith redefinition of other variables and function references=
 in the =0Ainitialization files.=0A=0A@menu=0A* The different pages::      =
 The different categories of pages.=0A* The page layout::           The ele=
ments of a page.=0A* Navigation panel::          How to change the navigati=
on panel.=0A* Program variables::         The available main program variab=
les and some =0A                              usefull functions from the ma=
in program.=0A* css::                       Customizing css lines.=0A* Cust=
omizing header::=0A* Customizing section::=0A* Customizing footer::=0A* Spe=
cial pages::             Customizing table of contents, top, about page.=0A=
@end menu=0A=0A@c --------------------------------------------------------=
=0A@node The different pages=0A@section The different categories of pages a=
nd sectionning elements=0A=0AThe following sectionning elements can be asso=
ciated with pages:=0A=0A@table @emph=0A@item Normal elements=0AThese are no=
rmal sections or nodes. Their association with pages is=0Adetermined by the=
 splitting of the document. @xref{Splittig output}.=0A@item Top element=0AT=
he top element is the higher element in the document structure.=0AIf there =
is a @code{@@top} section it is the element associated with=0Athat section.=
 Otherwise it is the element associated with the =0A@code{@@node Top}. If t=
here is no @code{@@node Top} the first element is the =0Atop element.=0A=0A=
The top element is formatted differently than a normal element if there=0Ai=
s a @code{@@top} section or the @code{@@node Top} isn't associated =0Awith =
a sectionning command.=0A@item Misc elements=0AThese elements are associate=
d with pages if the document is split.=0AThere are four misc elements:=0A@e=
numerate=0A@item Table of contents=0A@item Short table of contents, also ca=
lled Overview=0A@item Footnotes page=0A@item About page=0A@end enumerate=0A=
=0AThe @emph{About page} shouldn't be present for documents consisting=0Ain=
 only one sectionning element. The @emph{Footnote page} should only=0Abe pr=
esent if the footnotes appear on a separated page =0A(@pxref{Page layout op=
tions}), however a footnote element is present if=0Athe document isn't spli=
t. The @emph{Table of contents} should only=0Abe formatted if @code{@@conte=
nts} is present in the document.=0ASimilarly the @emph{Overview} should onl=
y appear if @code{@@shortcontents}=0Aor @code{@@summarycontents} is present=
.=0A@end table=0A=0A@c ----------------------------------------------------=
----=0A@node The page layout=0A@section Page layout and navigation panel ov=
erview=0A=0AA page is broken up in three parts. A page header, the sections=
 =0Aand a page footer. A common element in the page layout is a navigation=
=0Apanel with icons or text linking to other sections or pages. Another=0Ac=
ommon element is a rule, separating sections or footer. The navigation=0Apa=
nel and the rules may be part of the sections or part of headers or=0Afoote=
rs. You may use the variables @code{$SMALL_RULE}, @code{$DEFAULT_RULE}, =0A=
@code{$MIDDLE_RULE} and @code{$BIG_RULE} for rules of different sizes.=0A=
=0AIn the header some important meta data may be defined, like the=0Atitle =
or style information, and textual informations may be present=0Ain comments=
. All this doesn't appear directly in the displayed =0A@acronym{HTML}, thou=
gh.=0A=0AThe page layout is mainly controlled by functions, the precise fun=
ctions =0Acalled depending on the document splitting. The navigation panel,=
 however,=0Acan be customized with variables.=0A=0A@subheading Element labe=
ls=0A@anchor{Element labels}=0A=0AThere are 19 items associated with elemen=
ts. Each of these=0Ais associated with a name and a reference to the =0Aele=
ment they represent, when such an element exists. =0AThe element is either =
a global element or an element relative to the current=0Aelement. The relat=
ive elements are found with respect with the document=0Astructure defined b=
y the section structuring commands (@code{@@chapter}, =0A@code{@@unnumbered=
}@dots{}) or by the nodes (in that case the node =0Adirections are specifie=
d on node line or in menu organization).=0AThese items are called @dfn{elem=
ent labels}. They may be associated with =0Aa button (@pxref{Button specifi=
cations}), and used in the formatting functions =0A(@pxref{Program variable=
s}).=0A=0AHere is the list:=0A=0A@table @emph=0A@item @samp{@ }=0AAn empty =
button=0A@item Top=0ATop element. The associated name is @code{$TOP_HEADING=
} if that variable is =0Adefined.=0A@item Contents=0ATable of contents=0A@i=
tem About=0AAbout (help) page=0A@item Overview=0AOverview, short table of c=
ontents=0A@item First=0AFirst element in reading order=0A@item Last=0ALast =
element in reading order=0A@item Index=0AThe first chapter with @code{@@pri=
ntindex}. The associated name =0Ais  @code{$INDEX_CHAPTER}, if the variable=
 is set.=0A@item This=0AThe current element=0A@item Back=0APreceding elemen=
t in reading order=0A@item FastBack=0ABeginning of this chapter or previous=
 chapter if the element is a chapter=0A@item Prev=0APrevious section on the=
 same level =0A@item NodePrev=0APrevious node=0A@item Forward =0ANext eleme=
nt in reading order=0A@item FastForward=0ANext chapter=0A@item Next=0ANext =
section on the same level=0A@item NodeNext=0ANext node=0A@item Following=0A=
Next node in node reading order=0A@item Up=0AUp section=0A@item NodeUp=0AUp=
 node=0A@end table=0A=0A@c ------------------------------------------------=
--------=0A@node Navigation panel=0A@section Customization of the navigatio=
n panels buttons=0A=0AA lot of customization of the navigation panel may be=
 achieved without=0Aredefining functions, with variables redefinition. =0AI=
n case it isn't enough, it is also possible to redefine the function =0Adoi=
ng the navigation panel formatting.=0A=0A@menu =0A* General purpose variabl=
es::      Variables controlling the navigation panel=0A                    =
               at a global level=0A* Button specifications::=0A* Panel form=
atting function::=0A@end menu=0A=0A@c -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=
=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D=
=0A@node General purpose variables=0A@subsection Controlling the navigation=
 panel panel at a high level=0A=0AThe global formatting of the navigation p=
anels may be=0Achanged with the following variables:=0A=0A@vtable @code=0A@=
item $VERTICAL_HEAD_NAVIGATION=0AA vertical navigation panel will be used f=
or the header navigation =0Apanel if this variable is true.=0A@item $ICONS=
=0AIcons are used instead of=0Atextual buttons if this variable is true.=0A=
@item $SECTION_NAVIGATION=0AIf this variable is false there is no section n=
avigation, no navigation =0Apanels for the elements within the pages, only =
at =0Athe beginning and the end of the page (@pxref{Page layout options}).=
=0A@end vtable=0A=0A@c -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D=
-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D=0A@node Button=
 specifications=0A@subsection Specifying the buttons formatting=0A=0ASevera=
l arrays and hashes enable a precise control on the buttons and =0Atheir di=
splay. =0AThe following arrays determine the buttons present in navigation =
panels:=0A=0A@vtable @code=0A@item @@SECTION_BUTTONS=0AThis array is used f=
or the navigation panel buttons present at the begining=0Aof sectionning el=
ements. If split at node or section they are also used =0Aat the page foote=
r, and in the case of section navigation at the page header.=0A@item @@SECT=
ION_FOOTER_BUTTONS=0AThis array is used for the navigation panel buttons pr=
esent at the footer=0Aof pages when split at node or at section. =0A=0AIf @=
code{$WORDS_IN_PAGE} is set and the output is split at nodes, these =0Abutt=
ons are only present if there are more than @code{$WORDS_IN_PAGE}=0Awords i=
n the sectionning element text.=0A@item @@CHAPTER_BUTTONS=0AThis array is u=
sed for the buttons appearing at the page footer if split at =0Achapter, an=
d at the page header if split at chapter and there is no section=0Anavigati=
on.=0A@item @@MISC_BUTTONS=0AThese buttons appear at the beginning of speci=
al and sections  =0Aand at the end of these section pages if the output is =
split.=0A@end vtable=0A=0AThe array specify the buttons displayed in naviga=
tion panels, =0Aand how the button is displayed.=0AEach element is associat=
ed with=0Aa button of the navigation panel from left to right.=0AThe signif=
ication of the array element value is the following:=0A=0A@table @emph=0A@i=
tem reference on a function=0AThe function is called with first argument a =
filehandle reference on the=0Acurrent file and second argument a boolean tr=
ue if the navigation =0Apanel should be vertical.=0A@item reference on a sc=
alar=0AThe scalar value is printed. For some possibly=0Ausefull scalars, @r=
ef{Elements hashes}.=0A@item reference on an array=0AIn this case the first=
 array element should be a reference on text and the =0Asecond element an e=
lement label. In that case a link to the =0Aelement associated with the ele=
ment label with the scalar value=0Atext is generated.=0A=0AFor example if t=
he buttons array element is=0A@example=0A[ 'Next', \$Texi2HTML::NODE@{Next@=
} ] =0A@end example=0A=0AThe button will be a link to the next section with=
 text =0A@code{$Texi2HTML::NODE@{Next@}}.=0A@item element label=0AIf icons =
are not used, the button is a link to the corresponding=0Aelement which tex=
t is defined by the value associated with the =0Aelement label in the @code=
{%NAVIGATION_TEXT} hash, surrounded=0Aby @samp{[} and @samp{]}. If the elem=
ent label is @samp{ }, there is=0Ano @samp{[} and @samp{]}.=0A=0AIf icons a=
re used, the button is an image with file determined by=0Athe value associa=
ted with the element label in the @code{%ACTIVE_ICONS}=0Ahash if the the li=
nk really leads to an element, or in the @code{%PASSIVE_ICONS}=0Ahash if th=
ere is no element to link to. Of course if there is a link to the =0Aelemen=
t the icon links to that element.=0A@end table=0A=0A@c -=3D-=3D-=3D-=3D-=3D=
-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=
=3D-=3D-=3D-=3D-=3D=0A@node Panel formatting function=0A@subsection Changin=
g the navigation panel formatting=0A=0AIf you are not satisfied with this s=
cheme, it is possible to=0Acontrol exactly the formatting of navigation pan=
els by redefining a function =0Areference. The function controlling the dis=
play of navigation panel is =0Aassociated with the following function refer=
ence:=0A=0A@deffn {Function Reference} print_navigation $filehandle \@@butt=
ons $vertical=0A@var{$filehandle} is the opened filehandle the function sho=
uld write to.=0A@var{\@@buttons} is an array reference which should hold th=
e specification of =0Athe buttons for that navigation panel. @var{$vertical=
} is true if the =0Anavigation panel should be vertical.=0A@end deffn=0A=0A=
@c --------------------------------------------------------=0A@node Program=
 variables=0A@section Main program variables and usefull functions=0A=0AIn =
the functions =0Acontrolling the page layout some global variables set by t=
he main=0Aprogram are available, with value corresponding with the current=
=0Alayout element.=0A=0A@menu =0A* Elements hashes::             Accessing =
information related with the =0A                                different e=
lements   =0A* Global informations::         Accessing global informations,=
 like date, =0A                                title@dots{}=0A* Global func=
tions::            main program usefull functions=0A@end menu=0A=0A=0A@c -=
=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D=
-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D=0A@node Elements hashes=0A@subsection =
Accessing elements informations=0A=0AFour hashes are available, with key th=
e elements labels (as described=0Ain @ref{Element labels}) and values:=0A=
=0A@vtable @code=0A@item %Texi2HTML::NAME=0AThe formatted element name=0A@i=
tem %Texi2HTML::HREF=0AThe element hypertext reference=0A@item %Texi2HTML::=
NODE=0AThe element node name=0A@item %Texi2HTML::NO_TEXI=0AThe element name=
 after removal of texi commands=0A@end vtable=0A=0A@c -=3D-=3D-=3D-=3D-=3D-=
=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D=
-=3D-=3D-=3D-=3D=0A@node Global informations=0A@subsection Accessing global=
 informations=0A=0AThree kinds of global informations are available, miscal=
leneous global=0Astrings, flags set by @code{@@set} and special flags and s=
ection lines.=0A=0A@subsubheading Global strings=0AThe @code{%Texi2HTML::TH=
ISDOC} hash holds some global informations:=0A=0A@table @code=0A@item fullt=
itle=0Atitle set by @code{@@title}. If there is no @code{@@title} other =0A=
possibilities are tried (@code{@@settitle}, @code{@@shorttitlepage}@dots{})=
.=0A@item title=0Atitle set by @code{@@settitle}, or @code{fulltitle}.=0A@i=
tem author=0AAuthors list set by @code{@@author}.=0A@item copying=0AText ap=
pearing in @code{@@copying} with all the texinfo commands removed,=0Aput in=
 comments.=0A@item program=0AThe name and version of @emph{texi2html}.=0A@i=
tem program_homepage=0AHomepage for @emph{texi2html}.=0A@item program_autho=
rs=0AAuthors of @emph{texi2html}.=0A@item toc_file=0AThe file name of the t=
able of contents.=0A@item today=0AThe date.=0A@end table=0A=0A@subsubheadin=
g Flags=0AFlags defined by @code{@@set} may be accessed through the =0A@cod=
e{%main::value} hash. The key is the flag name, the value is the=0Aflag val=
ue at the end of the document. =0A=0ASpecial flags are set by the main prog=
ram. They correspond with a texinfo=0Acommand, like @code{@@setfilename}, o=
r @code{@@settitle}, =0A@code{@@author}@dots{} The corresponding flag is th=
e command name with =0A@samp{_} appended, for example, @code{_titlefont} co=
rresponds with =0A@code{@@titlefont}. Like other flags they are available i=
n =0A@code{%main::value}.=0A=0A=0A@subsubheading Section lines=0A=0AThe fol=
lowing array references or arrays holds formatted lines:=0A=0A@vtable @code=
=0A@item $Texi2HTML::THIS_SECTION=0ALines of the current element.=0A@item $=
Texi2HTML::THIS_HEADER=0ALines of the current element appearing before the =
element label (anchors).=0A@item $Texi2HTML::OVERVIEW=0ALines of short tabl=
e of contents. @xref{Special pages}.=0A@item $Texi2HTML::TOC_LINES=0ALines =
of table of contents. @xref{Special pages}.=0A@end vtable=0A=0A@c -=3D-=3D-=
=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D=
-=3D-=3D-=3D-=3D-=3D-=3D-=3D=0A@node Global functions=0A@subsection Functio=
n usefull in page formatting=0A=0AThe usefull function is a function used t=
o print an array of lines, which =0Aalso counts the number of words in the =
array, if needed.=0A=0A@deftypefun $words_number  main::print_lines $fileha=
ndle \@@lines_array=0A@var{$filehandle} is the opened filehandle the functi=
on should write to.=0A@var{\@@lines_array} is the array line the function s=
hould write to the file.=0AIf this argument is omitted, the function uses @=
code{$Texi2HTML::THIS_SECTION}.=0A@var{$words_number} is the number of word=
s in the array, only defined if=0Asplit at nodes and @code{$WORDS_IN_PAGE} =
is defined.=0A@end deftypefun=0A=0A@c -------------------------------------=
-------------------=0A@node css=0A@section Customizing the @emph{texi2html}=
 css lines=0A=0AIt is possible to modify the @emph{texi2html} css lines by =
modifying=0Athe entries or adding to the @code{%css_map} hash. Each key is =
a css=0Aselector, the corresponding value is a style string.=0A=0AThe whole=
 css text is in the variable @code{$CSS_LINES}. If this =0Avariable is defi=
ned the variable value is used instead of being =0Aconstructed using the @c=
ode{%css_map} entries. For example if you don't=0Awant any css entries, set=
=0A=0A@example=0A$CSS_LINES =3D '';=0A@end example=0A=0AIt is also possible=
 to change completely the way @code{$CSS_LINES} are=0Agenerated by redefini=
ng the following function reference:=0A=0A=0A@deffn {Function Reference} cs=
s_lines \@@import_lines \@@rule_lines=0AThis function should be used to con=
struct the @code{$CSS_LINES}.=0A@var{\@@import_lines} are the @code{@@impor=
t} lines of the =0Afiles specified with @option{-include-css}, =0Aand @var{=
\@@rule_lines} are the css commands lines of these files.=0A@xref{Style opt=
ions}.=0A@end deffn=0A=0A@c -----------------------------------------------=
---------=0A@node Customizing header=0A@section Customizing the page header=
 =0A=0AIt is possible to add lines to the text within the @code{<head>} =0A=
@acronym{HTML} elements, by defining the variable @code{$EXTRA_HEAD}.=0ASim=
ilarly it is possible to add text just after the @code{<body>} =0Aelement w=
ith the variable @code{$AFTER_BODY_OPEN}.=0AThe encoding of the document is=
 defined by @code{$ENCODING} if=0Ano @code{@@documentencoding} appears in t=
he document.=0A=0AThe @code{<body>} element attributes may be set by defini=
ng the=0Avariable @code{$BODYTEXT}. If you want to define that variable=0Ad=
ynamically, you could redefine the following function reference:=0A=0A@deff=
n {Function Reference} set_body_text=0AThis function should set @code{$BODY=
TEXT}.=0A@end deffn=0A=0AThe default functions call the function associated=
 with =0A@code{$print_head_navigation} to format the navigation panel for t=
he =0Apage header. Thus you can control parts of the formatting by=0Aredefi=
ning the function reference.=0A=0A@deffn {Function Reference} print_head_na=
vigation $filehandle \@@buttons=0A@var{$filehandle} is the opened filehandl=
e the function should write to.=0A@var{\@@buttons} is an array reference wh=
ich should hold the specification of =0Athe buttons for the navigation pane=
l. =0A@end deffn=0A=0AIf you want even more control, you can have full cont=
rol over the page header =0Aformatting by redefining three function referen=
ces. The function associated=0Awith @code{$print_page_head} is called for a=
ll the pages, and after that,=0Athe function associated with @code{$print_c=
hapter_header} is called=0Aif the document is split at chapters, or the fun=
ction associated with=0A@code{$print_section_header} is called if the docum=
ent is split at sections.=0A=0A@deffn {Function Reference} print_page_head =
$filehandle=0A@var{$filehandle} is the opened filehandle the function shoul=
d write to.=0AThis function should print the page head, including the @code=
{<body>}=0Aelement.=0A@end deffn=0A=0A@deffn {Function Reference} print_cha=
pter_header $filehandle=0A@var{$filehandle} is the opened filehandle the fu=
nction should write to.=0AThis function is called if the document is split =
at chapters, after =0A@code{print_page_head}.=0A@end deffn=0A=0A@deffn {Fun=
ction Reference} print_section_header $filehandle=0A@var{$filehandle} is th=
e opened filehandle the function should write to.=0AThis function is called=
 if the document is split at sections, after =0A@code{print_page_head}.=0A@=
end deffn=0A=0A@c --------------------------------------------------------=
=0A@node Customizing section=0A@section Customizing the sections=0A=0AThe f=
unctions associated with the following function references are used for =0A=
the formatting of sections:=0A=0A@deffn {Function Reference} print_section =
$filehandle $first_in_page $previous_is_top=0A@var{$filehandle} is the open=
ed filehandle the function should write to.=0A@var{$first_in_page} is true =
if this section is the first section in the page.=0A@var{$previous_is_top} =
is true if this section is the section following the =0ATop section.=0AThis=
 function should print the current section.=0A@end deffn=0A=0A@deffn {Funct=
ion Reference} end_section $filehandle $last_element_or_before_top=0A@var{$=
filehandle} is the opened filehandle the function should write to.=0A@var{$=
last_element_or_before_top} is true if this section precedes the top =0Aele=
ment or is the last one in page, or before the special elements.=0A@end def=
fn=0A=0A@c --------------------------------------------------------=0A@node=
 Customizing footer=0A@section Customizing the page footer=0A=0AIt is possi=
ble to add text just before the @code{</body>} =0Aelement with the variable=
 @code{$PRE_BODY_CLOSE}.=0A=0A@ignore=0AThe footer text may be influenced b=
y @code{$ADDRESS} which should hold=0Ainformation about who created the doc=
ument and how.=0AIf you want to define that variable=0Adynamically, you cou=
ld redefine the following function reference:=0A=0A@deftypefn {Function Ref=
erence} $address_text address $user $date=0AThis function should return the=
 address. @var{$user} is the user name=0Aof the user running texi2html, @va=
r{$date} is the date of the day.=0A@end deftypefn=0A@end ignore=0A=0AThe de=
fault functions call the function associated with =0A@code{$print_foot_navi=
gation} to format the navigation panel for the =0Apage footer. Thus you can=
 control parts of the formatting by=0Aredefining the function reference.=0A=
=0A@deffn {Function Reference} print_foot_navigation $filehandle \@@buttons=
=0A@var{$filehandle} is the opened filehandle the function should write to.=
=0A@var{\@@buttons} is an array reference which should hold the specificati=
on of =0Athe buttons for the navigation panel. =0A@end deffn=0A=0AIf you wa=
nt even more control, you can have full control the page footer =0Aformatti=
ng by redefining three function references.=0AThe function associated with =
@code{$print_chapter_footer} is called=0Aif the document is split at chapte=
rs, or the function associated with=0A@code{$print_section_footer} is calle=
d if the document is split at sections.=0AAfter that the function associate=
d with @code{$print_page_foot} is called.=0A=0A@deffn {Function Reference} =
print_page_foot $filehandle=0A@var{$filehandle} is the opened filehandle th=
e function should write to.=0AThis function should print the page foot, inc=
luding the @code{</body>}=0Aelement.=0A@end deffn=0A=0A@deffn {Function Ref=
erence} print_chapter_footer $filehandle=0A@var{$filehandle} is the opened =
filehandle the function should write to.=0AThis function is called if the d=
ocument is split at chapters, before =0A@code{print_page_foot}.=0A@end deff=
n=0A=0A@deffn {Function Reference} print_section_footer $filehandle=0A@var{=
$filehandle} is the opened filehandle the function should write to.=0AThis =
function is called if the document is split at sections, before=0A@code{pri=
nt_page_foot}.=0A@end deffn=0A=0A=0A@c ------------------------------------=
--------------------=0A@node Special pages=0A@section Special pages formatt=
ing=0A=0AFor the special elements, two things must be formatted: the conten=
t=0Aand the page layout=0A=0A@menu=0A* Special pages content::=0A* Special =
pages layout::=0A@end menu=0A=0A@c -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D=
-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D=0A=
@node Special pages content=0A@subsection Customizing the content of the sp=
ecial pages=0A=0A@menu=0A* Top element text::=0A* Contents and Overview tex=
t::=0A* Footnotes text::=0A* About text::=0A@end menu=0A=0A@c -=3D-=3D-=3D-=
=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D=
-=3D-=3D-=3D-=3D-=3D-=3D=0A@node Top element text=0A@subsubsection Top elem=
ent text formatting=0AThe top element formatting is controlled by a functio=
n which also=0Acontrols the layout of the top element page or section. The =
associated=0Afunction reference is:=0A=0A@deffn {Function Reference} print_=
Top $filehandle $has_top_heading=0A@var{$filehandle} is the opened filehand=
le the function should write to.=0A@var{$has_top_heading} is true if there =
is a @code{@@heading} command or=0A@code{@@titlefont} command appearing in =
the Top element text.=0A@end deffn=0A=0A@c -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D=
-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=
=3D-=3D=0A@node Contents and Overview text=0A@subsubsection Table of conten=
ts and Short table of contents=0ASeveral variables may be used to control t=
he formatting of table of contents =0Aand short table of contents:=0A=0A@ta=
ble @code=0A@item $BEFORE_OVERVIEW=0AThe variable value is inserted before =
the short table of contents text.=0A@item $AFTER_OVERVIEW=0AThe variable va=
lue is inserted after the short table of contents text.=0A@item $BEFORE_TOC=
_LINES=0AThe variable value is inserted before the table of contents text.=
=0A@item $AFTER_TOC_LINES=0AThe variable value is inserted after the table =
of contents text.=0A@item $TOC_LIST_STYLE=0AThis should contain a css style=
 used for the list style if the tables of=0Acontent are formatted with a li=
st.=0A@item $TOC_LIST_ATTRIBUTE=0AThis should contain an attribute text use=
d for the list element if the tables of=0Acontent are formatted with a list=
.=0A@end table=0A=0AMore control on the table of contents and short table o=
f contents formatting=0Amay be achieved by redefining a function with the f=
ollowing associated =0Afunction reference:=0A=0A@deffn {Function Reference}=
 toc_body \@@elements $has_content $has_scontent=0A@var{\@@elements} is an =
array reference contining informations about=0Aall the elements of the docu=
ment. Each of the entry of this array is an hash=0Areference which entries =
correspond with different informations=0Aabout the element. Interesting key=
s have the following meaning:=0A=0A@table @code=0A@item top=0Atrue if the e=
lement is the top element,=0A@item index_page=0Atrue if the element is an i=
ndex page added because of index splitting,=0A@item toc_level=0Alevel of th=
e element in the table of content. Highest level=0Ais 1 for the top element=
 and for chapters, appendix and so on,=0A2 for section, unnumberedsec and s=
o on...=0A@item tocid=0Alabel used for reference linking to the element in =
table of=0Acontents,=0A@item file =0Athe file containing the element, usefu=
ll to do href to that file=0Ain case the document is split,=0A@item text=0A=
text of the element, with section number,=0A@item name=0Atext of the elemen=
t, without section number.=0A@end table=0A=0A@var{$has_content} is true if =
@code{@@contents} appears in the document.=0A@var{$has_scontent} is true if=
 @code{@@shortcontents} appears in the document.=0A@end deffn=0A=0AThis fun=
ction doesn't return anything but should fill the array corresponding=0Awit=
h the =0A@code{$Texi2HTML::TOC_LINES} and=0A@code{$Texi2HTML::OVERVIEW} ref=
erences with the table of contents and short =0Atable of contents.=0A=0A@c =
-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=
=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D=0A@node Footnotes text=0A@subsubsec=
tion Formatting of footnotes text=0A=0AThe footnotes text is allready forma=
tting when @code{@@footnote} commands=0Aare expanded. @xref{Footnotes}.=0A=
=0A@c -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=
=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D=0A@node About text=0A@subsubsec=
tion Formatting of about text=0A=0AThe default about element contains an ex=
plaination of the buttons used=0Ain the document (@code{@@SECTION_BUTTONS},=
 @ref{Button specifications}) and =0Aan example locating the buttons target=
s in an example.=0AThe formatting of this text may be influenced by the fol=
lowing =0Ahashes and variables:=0A=0A@table @code=0A@item $PRE_ABOUT =0A@it=
emx $AFTER_ABOUT=0AThis variable may be a scalar or a function reference. =
=0AIf it is a scalar, the value is used.=0AIf this is a function reference =
it is expanded and the returned text is=0Aused. The text is added before or=
 after the main about text.=0A@item %BUTTONS_GOTO=0A=0AThe keys of this has=
h are element labels (@pxref{Element labels}). The value=0Ais the text asso=
ciated with the element label in the about text.=0A=0A@item %BUTTONS_EXAMPL=
E=0A=0AThe keys of this hash are  element labels (@pxref{Element labels}). =
The value=0Ais the text associated with the element label in the about exam=
ple, =0Atypically a section number.=0A=0A@end table=0A=0AIf this is not eno=
ugh and you want to control exactly the formatting of=0Athe about text, you=
 can redefine the function associated with the following =0Afunction refere=
nce:=0A=0A@deftypefn {Function Reference} $about_text print_about=0AThis fu=
nction should return the about text.=0A@end deftypefn=0A=0A@c -=3D-=3D-=3D-=
=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D=
-=3D-=3D-=3D-=3D-=3D-=3D=0A@node Special pages layout=0A@subsection Customi=
zing the layout of the special pages=0A=0AThe formatting of each of the spe=
cial pages, or section in case =0Athe document is not split, is controlled =
by a function.=0AThe associated function reference is called accordingly:=
=0A=0A@ftable @code=0A@item print_Top=0AFormatting of top element page or s=
ection. It is also used for the formatting=0Aof the top element text (@pxre=
f{Top element text}).=0A@item print_Toc=0AFormatting of table of contents p=
age or section=0A@item print_Overview=0AFormatting of short table of conten=
ts page or section=0A@item print_About=0AFormatting of about (help) page or=
 section=0A@item print_Footnotes=0AFormatting of footnotes section or page =
in case footnotes are on a =0Aseparated page or the document isn't split.=
=0A@end ftable=0A=0AIn the default case, @code{$print_Top} calls @code{$pri=
nt_Top_header} for=0Athe header and @code{$print_Top_footer} for the footer=
 of top element.=0AAll the other function call @code{$print_misc} which in =
turn calls=0A@code{$print_misc_header} for the headers and  @code{$print_mi=
sc_footer} =0Afor the footers.=0A=0A=0A
--dDRMvlgZJXvWKvBx--