1This is the README file for the texi2html distribution.
2The primary distribution point is
3http://savannah.nongnu.org/download/texi2html/
4
5Installation
6============
7
8For generic installation instructions on compiling and installing this
9Automake-based distribution, please read the file `INSTALL'.
10Installation notes specific to Texi2html:
11* Installation is fairly simple, no compilers are required.
12* You need to have perl version 5.00405, or higher installed
13 on your system to run 'texi2html'. To play nice with encodings you
14 need the Encode and Unicode::Normalize modules. It is likely that an
15 older perl 5 version also works if File::Spec is present.
16* To generate Makefile.in etc., run `./autogen.sh' or autoreconf
17
18Getting Started with texi2html
19==============================
20
21'texi2html' converts texinfo documents to HTML, Info, docbook
22and XML.
23
24Texinfo is the official documentation format of the GNU project. It
25uses a single source file to produce both on-line information and
26printed output. For more details about texinfo, see
27http://www.texinfo.org.
28
29Te HTML output of 'texi2html' is highly configurable. Among others,
30with 'texi2html' you can customize your entire page layout (like
31headers, footers, style sheets, etc), split documents at various levels
32and use 'latex2html' to convert @tex sections.
33
34Because if this configurability, texi2html is being integrated into
35the texinfo GNU project at http://www.texinfo.org. The projects
36are already being merged, and the 5.0 release is likely to be the last
37release of a separate texi2html.
38
39To create HTML of texinfo documents
40===================================
41
42Make sure that you have 'texi2html' correctly installed on your
43system. The general synopsis of 'texi2html' is
44
45 texi2html [options] texinfo-source-file
46
47Without any options, this will create the file <docname>.html where
48<docname> is the basename of your texinfo files.
49
50Run 'texi2html -h' for a short overview of the most important options,
51or have a look at the texi2html man page. For more in-depth information
52see the texi2html texinfo manual.
53
54Customizing texi2html
55=====================
56
57Initialisation options are read first from
58'/usr/local/etc/texi2html/Config' (the exact location being changeable with
59the '--sysconfdir=dir' option to the configure script), then from
60$HOME/.texi2html/Config, then any command-line options including --init-file
61options; with later settings overriding earlier ones.
62
63The default initialisation options are defined in the
64'texi2html.init' and built-in formats files in formats/*.init files
65contained in the Texi2html distribution (in fact, a script pastes
66those files into the beginning of the perl file generated by
67`./configure' from texi2html.pl and generates the actual 'texi2html'
68script this way.).
69
70To customize 'texi2html' it is best if you copy the appropriate
71sections from the 'texi2html.init' file into an appropriate local
72initialization file, make the necessary changes there, and then have
73'texi2html' read this initialisation file by one of the means described
74above.
75
76For an example on what you can produce with 'texi2html' have a look
77at the following sites:
78
79* http://www.singular.uni-kl.de/Manual/html/
80
81(Please send me your sites, if you'd like to have them listed here).
82
83Documentation of texi2html
84==========================
85
86The texi2html Texinfo manual is lagging behind the development. In
87addition, you might want to have a look at the comments in the
88'texi2html.init' file for explanations about customizable parameters
89and at the (not up-to-date) texi2html man page for an overview of
90texi2html's synopsis.
91
92More information
93================
94
95Texi2html's home page can be found at http://www.nongnu.org/texi2html/
96The home for development was at savannah at
97http://savannah.nongnu.org/projects/texi2html
98and is being merged into
99http://savannah.gnu.org/projects/texinfo
100
101The newest version of Texi2html can be obtained from
102http://savannah.nongnu.org/download/texi2html/
103or, via anonymous cvs (see
104http://savannah.gnu.org/cvs/?group=texinfo for instructions).
105The texi2html tree is in the texinfo tree, in the texi2html
106directory.
107
108Send email to help-texinfo@gnu.org for enhancement suggestions,
109authoring questions and general discussion.
110
111Send email to bug-texinfo@gnu.org for bug reports, patches,
112discussions about code.
113
114To subscribe to these mailinglists, visit
115 http://savannah.gnu.org/mail/?group=texinfo
116
117Files
118=====
119
120This distribution includes the following files, among others:
121 README This file.
122
123 NEWS Summary of new features by release.
124
125 INSTALL Generic installation instructions.
126
127 TODO Things which are yet to be done.
128
129Texi2html source files:
130
131 texi2html Actual script to run. Generated by
132 make, `buildt2h.sh' and `addformats.sh'
133 from texi2html.pl, texi2html.init,
134 MySimple.pm, T2h_i18n.pm, l2h.init,
135 translations.pl and formats/*.init.
136
137 texi2html.pl Main source file of the converter.
138
139 texi2html_configured.pl File generated by `./configure' from
140 texi2html.pl.
141
142 texi2html.init Default values of configurable
143 parameters. `buildt2h.sh' inserts this
144 file into texi2html_configured.pl when
145 it generates the actual `texi2html' script.
146
147 MySimple.pm Perl module which handles the
148 processing of command-line options.
149 `buildt2h.sh' inserts this file into
150 texi2html_configured.pl when it generates
151 the actual `texi2html' script.
152
153 T2h_i18n.pm Code used to handle strings
154 internationalization (obsolete).
155
156 translations.pl translations of strings generated by
157 the script `manage_i18n.pl' from source
158 files and files in the `i18n' directory
159 (obsolete).
160
161 l2h.init default configuration file for `latex2html'
162 used to convert maths and TeX.
163
164 po_document/ Directory containing po files used for
165 translation of strings. The primary source
166 for the file are outside of texi2html,
167 in the texinfo po_document/ directory.
168
169 po_messages/ Directory containing po files used for
170 translation of strings. The primary source
171 for the file are outside of texi2html,
172 in the texinfo po/ directory.
173
174 i18n/ Directory containing one file per language
175 with translation of strings (obsolete,
176 generated from po_document/ files).
177
178Helper scripts
179
180 gettext_to_separated.pl Helper scripts used to convert gettext po
181 separated_to_hash.pl files to the former format used by texi2html
182 up to version 1.82.
183
184 manage_i18n.pl Helper script used to regenerate translations
185 from the source files and the files in the
186 `i18n/' directory.
187
188 buildt2h.sh Helper script used to regenerate the texi2html
189 script. A simple wrapper around a sed
190 one-liner.
191
192 addformats.sh Other helper script used to regenerate the
193 texi2html script, for all the built-in formats.
194 A simple wrapper around a sed one-liner.
195
196
197Documentation files:
198
199 texi2html.texi Texinfo manual of texi2html.
200
201 texi2html.1.in Template for generation of man pages
202 of texi2html (`texi2html.1'). This man
203 page is incomplete.
204
205Installation files:
206
207 configure This file creates creates a Makefile
208 which in turn creates the other files.
209
210 configure.ac This is a template for creating
211 `configure' using Autoconf.
212
213 Makefile.in This is a template for `configure'
214 to use to make a Makefile. Created by
215 Automake.
216
217 Makefile.am This is a template for Automake
218 to use to make a Makefile.in.
219
220Reporting bugs
221==============
222
223For bug reports, please include enough information for the maintainers
224to reproduce the problem. Generally speaking, that means:
225- the version number of Texi2html and the program(s) involved (use --version).
226- the contents of any input files necessary to reproduce the bug (crucial!).
227- a description of the problem and any samples of the erroneous output.
228- anything else that you think would be helpful.
229
230Patches are most welcome; if possible, please make them against the
231source files (e.g., against texi2html.pl, or texi2html.init) with
232`diff -c' or `diff -u' and include ChangeLog entries.
233
234Good luck and enjoy !!
235