texinfo/texi2html/test/texi2html_manual/texi2html.texi

\input texinfo @c -*-texinfo-*-
@c
@c This is the ``Texinfo to HTML Converter'' manual which
@c which is part of the ``texi2html'' distribution.
@c
@c License:
@c    Copyright (C) 1999, 2000  Free Software Foundation, Inc.
@c
@c    This program is free software; you can redistribute it
@c    and/or modify it under the terms of the GNU General Public
@c    License as published by the Free Software Foundation;
@c    either version 2 of the License, or (at your option) any
@c    later version.
@c
@c    This program is distributed in the hope that it will be
@c    useful, but WITHOUT ANY WARRANTY; without even the implied
@c    warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
@c    PURPOSE.  See the GNU General Public License for more
@c    details.
@c
@c    You should have received a copy of the GNU General
@c    Public License along with this program; if not, write to
@c    the Free Software Foundation, Inc., 59 Temple Place, Suite
@c    330, Boston, MA  02111-1307  USA
@c
@c
@c Revisions:
@c 
@c
@c Author:
@c   Karl Heinz Marbaise <khmarbaise@gmx.de>
@c
@c --------------------------------------------------------
@c
@c Currently most of the material is copied out of
@c texi2html.init file. It's just a start point.
@c In other words this is a draft manual ;-)
@c
@setfilename texi2html.info
@c --------------------------------------------------------
@c Edition and last update date of the manual which might
@c differ to the scripts last update date etc.
@set MANUAL_UPD 14. August 2000
@set MANUAL_ED 0.21
@c
@set MANUAL_AUTHOR Karl Heinz Marbaise
@set MANUAL_AUTHOR_EMAIL khmarbaise@@gmx.de
@c
@c Get the version of the script itself through
@c configure/autoconf etc.
@c version.texi is automatically generated through
@c configure/autoconf.
@include version.texi
@c --------------------------------------------------------
@c Index for command line options
@defcodeindex op
@c --------------------------------------------------------
@settitle Texinfo to HTML
@c @setchapternewpage on
@setchapternewpage odd
@footnotestyle separate
@ifset shorttitlepage-enabled
@shorttitlepage Texinfo to HTML
@end ifset
@c --------------------------------------------------------
@c support old style Info Dir entries.
@ifset OLDSTYLE-INFO-DIR
@ifinfo
@format
START-INFO-DIR-ENTRY
* Texi2html: (texi2html).  Texinfo 2 HTML Converter (texi2html).
END-INFO-DIR-ENTRY
@end format
@end ifinfo
@end ifset
@c --------------------------------------------------------
@c Informations for install-info.
@c I think the conversion script should be found
@c where the documentation system lives.
@c What do you think?
@dircategory Texinfo documentation system
@direntry
* Texi2html: (texi2html).  Texinfo to HTML Converter.
@end direntry
@c --------------------------------------------------------
@ifinfo
This file documents the texi2html script which converts
Texinfo into HTML.

Copyright (C) 1999, 2000  Free Software Foundation, Inc.

This edition is for texi2html version @value{VERSION},
@value{UPDATED}.

Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
this permission notice are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and
print the results, provided the printed document carries
copying permission notice identical to this one except for
the removal of this paragraph (this paragraph not being
relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified
versions of this manual under the conditions for verbatim
copying, provided that the entire resulting derived work is
distributed under the terms of a permission notice
identical to this one.

Permission is granted to copy and distribute translations
of this manual into another language, under the above
conditions for modified versions, except that this
permission notice may be stated in a translation approved
by the Free Software Foundation.
@end ifinfo
@c --------------------------------------------------------
@titlepage
@title Texinfo to HTML Converter
@subtitle Manual Edition @value{MANUAL_ED}
@subtitle Last Update: @value{MANUAL_UPD}
@subtitle for Version @value{VERSION} of @command{texi2html} script.
@author Lionel Cons
@author Karl Berry
@author Olaf Bachmann
@author and many others.
@author Karl Heinz Marbaise (manual)
@page
@vskip 0pt plus 1filll
Copyright @copyright{} Lionel Cons@*
Copyright @copyright{} Karl Berry@*
Copyright @copyright{} Olaf Bachmann@*
Copyright @copyright{} and many others.@*
Copyright @copyright{} Karl Heinz Marbaise (manual)@*

Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified
versions of this manual under the conditions for verbatim
copying, provided that the entire resulting derived work is
distributed under the terms of a permission notice
identical to this one.

Permission is granted to copy and distribute translations
of this manual into another language, under the above
conditions for modified versions, except that this
permission notice may be stated in a translation approved
by the Free Software Foundation.
@sp 2
Cover art by Etienne Suvasa.
@end titlepage
@c ========================================================
@summarycontents
@contents
@c
@ifnottex
@node Top, Overview, (dir), (dir)
@top Texi2html
@c @page
@c ========================================================
@c @node Top, Overview, (dir), (dir)
@c @top
@c @chapter About

This Manual (Edition @value{MANUAL_ED}, last updated at
@value{MANUAL_UPD}) describes the @command{texi2html} Perl
script which converters
@c The following construct allows me to get
@c real URL link in HTML and working refs in
@c info.
@ifhtml
@uref{http://www.texinfo.org,Texinfo}
@end ifhtml
@ifnothtml
Texinfo (@pxref{Top,,Texinfo,Texinfo})
@end ifnothtml
into @acronym{HTML}.

@c @inforef{Top, Top, Texinfo} does not work yet ;-)
@c here we should paste a @inforef or @xref on the
@c Texinfo manual.

Please send bug reports about this manual to Karl Heinz
Marbaise @email{khmarbaise@@gmx.de}. Please state exact
version/edition of the manual (can be found at start of
Texinfo source file; use the entry Id under Revisions).

Please note:
@example
This manual is currently under
construction and of course incomplete ;-)
@end example

@c The following line within a menu does not work!
@c * Why texi2html and not Makeinfo?:whytexi2html.      Why texi2html and not makeinfo?.
@ifinfo
@menu
@c * MenuName:NodeName.       Description.
* Overview::                  Overview about @command{texi2html}.
* Installation::              Installation process.
* Customizing::               Customizing.
* CustomizingExpand::         Customizing what gets expanded.
* CustomizingPage::           Customizing page layout.
* CustHTML::                  Customizing HTML.
* InitFile::                  Initialization files.
@c * ExtFile::                   Extension file.
* IFOs::                      Initialization file options
* Options::                   Command Line Options.

* Reference::                 Reference Manual of functions.

@detailmenu

/// The Detailed Node Listing ///

--- Overview ---

* whytexi2html::              Why @file{texi2html} and
                                not @file{makeinfo}?.


--- Installation process ---

* Installation::             Installation process.


--- Initialization file options ---

* IFOnumber::                 Number sectioning.
* IFOmenu::                   Avoid menu redundancy.
* IFOCenterImage::            Center Image.
* IFOExampleIndentCell::      Example Indent Cell.
* IFOSampleIndentCell::       Sample Indent Cell.
* IFOSmallFontSize::          Small Font Size.
* IFOTopHeading::             Top Heading.
* IFOIndexChapter::           Index Chapter.
* IFOSplitIndex::             Split Index.
* IFOhrefDirInsteadFile::     HREF Dir Instead file.


--- Command Line Options ---

* OptionDebug::               Debugging.
* OptionDocType::             DocType (HTML)
* OptionCheck::               Checking files.
* OptionExpand::              Expanding info, tex areas etc.
* OptionGlossary::            Glossary.
* OptionInvisible::           Invisible.
* OptionIso::                 Iso.
* OptionInclude::             Include directories.
* OptionTopFile::             Top File.
* OptionTocFile::             Table of content File.
* OptionFrames::              Frames.
* OptionMenu::                Menus.
* OptionNumber::              Number sections.
* OptionSplit::               Splitting.
* OptionSectionNavigation::   Navigation.
* OptionSubDir::              Subdirectory.
* OptionShortExt::            Short extension.
* OptionPrefix::              Prefix.
* OptionOutput::              Output.
* OptionShortRef::            Short Ref.
* OptionIndexSummary::        Index Summary.
* OptionVerbose::             Verbose.
* OptionLanguage::            Language.
* OptionL2H::                 La@TeX{}2HTML.


--- La@TeX{}2HTML for @code{@@math} and @code{@@tex} ---

* OptionL2HL2H::              Where to find La@TeX{}2HTML.
* OptionL2HSkip::             Skip calling La@TeX{}2HTML.
* OptionL2Htmp::              Temporary files for La@TeX{}2HTML.


--- Indices ---

* Indexop::                   Command Line Option Index.
* Indexvr::                   Variable Index.
* Indexcp::                   Concept Index.
@end detailmenu
@end menu
@end ifinfo
@end ifnottex
@c ========================================================
@node Overview, HowToGetHTML, Top, Top
@chapter Overview about @command{texi2html}
@uref{http://www.texinfo.org,Texinfo} is the official
documentation format of the @uref{http://www.gnu.org,GNU}
project. It uses a single source file to produce both
online information and printed output.

@c much thinking about ...
It is often proposed to have a way to produce
@acronym{HTML} from Texinfo sources, like the GNU-Info
format. It is much simpler to create one converter instead
of writing all documentation new in @acronym{HTML}, cause
there is so much documentation in Texinfo all over
the world.

A few time ago @command{makeinfo} wasn't able to produce
@acronym{HTML} output format, but there are needth to have
@acronym{HTML}. This was the borning hour for
@command{texi2html}. The basic purpose of @file{texi2html}
is to convert Texinfo documents into HTML.


@menu
* HowToGetHTML::       Ways to get HTML files.
* whytexi2html::       Why texi2html and not makeinfo?.
@end menu
@c --------------------------------------------------------
@node HowToGetHTML, whytexi2html, Overview, Overview
@section Ways to get HTML
You would like to @acronym{HTML} files out of your Texinfo
files? There exist two ways which you can go.
This first is to use @command{makeinfo} itself to produce
@acronym{HTML} output. The second is to use
@command{texi2html}.

@c --------------------------------------------------------
@node whytexi2html, Installation, HowToGetHTML, Overview
@section Why @file{texi2html} and not @file{makeinfo}?
The basic idea of @command{makeinfo}'s @acronym{HTML}
output was to get an readable @acronym{HTML} output.
Nothing sophisticated nor good styling just readable.

The current development of texi2html is going into
different direction.

The main purpose is to get better styling, better design
etc. of the created @acronym{HTML} pages. This way is
supported using differnt command line options and of course
possible changings of the initialization file to fit your
own needs.

The main disadvantage of @acronym{makeinfo}'s
@acronym{HTML} output is your getting only one big file.
This is of course readable but not very usable. The problem
of this is, while you like to have splitted chapters or
nodes the Texinfo source has to be read at minimum twice
times. This makes it impossible to implement this in
@command{makeinfo}. This would result in complete new
implementation of @command{makeinfo}'s source.

@c think more about this????
In contrast to the HTML produced by @command{makeinfo
--html} (the @command{makeinfo} program is part of the
Texinfo distribution), the HTML output of @file{texi2html}
is highly configurable. Among other differences, with
@command{texi2html} allows you to customize your entire
page layout (like headers, footers, style sheets, etc),
split documents at various levels, and use
@command{latex2html} to convert @code{@@tex} sections.

@command{texi2html} should reasonably convert all Texinfo
4.0 constructs. If not, please send a bug report to
@email{texi2html@@mathematik.uni-kl.de}.

@c ========================================================
@node Installation, Customizing, whytexi2html, Top
@chapter Installation of @command{texi2html}
@cindex Installation
description of the installation process.
What do you need?
How?

@c ========================================================
@node Customizing, CustomizingExpand, Installation, Top
@chapter Customizing files
@cindex Installation
@opindex frames
@c 4.) Customizing files to output
@c   ==> -out_file, -prefix, -subdir, -split, -frames etc
Result based on using @option{-frames}

@example
texi2html -V -frames texi2html.texi
@end example
Explanation of the output differences against default,
whatever this is ;-)


@c ========================================================
@node CustomizingExpand, CustomizingPage, Customizing, Top
@chapter Customizing what gets expanded
@c 5.) Customizing what gets expanded
@c   ==> -expand, and latex2html
Test starting.

@option{-expand info}
@option{-expand tex}
Take a look at optionexpand.

@c ========================================================
@node CustomizingPage, CustHTML, CustomizingExpand, Top
@include custpage.texi
@c ========================================================
@node CustHTML, InitFile, CustomizingPage, Top
@include custhtml.texi
@c ========================================================
@node InitFile, IFOs, CustHTML, Top
@include initfile.texi
@c --------------------------------------------------------
@node IFOs, Options, InitFile, Top
@include ifo.texi
@c ========================================================
@c @include extfile.texi obsolete now, is not documented!
@c ========================================================
@node Options, Reference, IFOs, Top
@include options.texi
@c ========================================================
@node Reference, Indexop, Options, Top
@include reference.texi
@c ========================================================
@c commandline option index.
@node Indexop, Indexvr, Reference, Top
@appendix Indices
@appendixsec Command Line Option Index
@printindex op
@c --------------------------------------------------------
@node Indexvr, Indexcp, Indexop, Top
@appendixsec Variable Index
@printindex vr
@c --------------------------------------------------------
@node Indexcp, , Indexvr, Top
@appendixsec Concept Index
@printindex cp
@c printindex init file options dito.
@c concept index.
@bye