1Building and installing GNU Texinfo with DJGPP v2.x
2===================================================
3
4This directory holds files required for building Texinfo with DJGPP
5tools for MS-DOS and MS-Windows. If you got this file with a binary
6distribution, look for the "Installation" section below.
7
8
91. Building Texinfo
10 ----------------
11
12 a. To compile Texinfo, you will need the following tools:
13
14 - basic DJGPP development environment: GCC, Binutils and djdev;
15 - a DJGPP port of GNU Make version 3.78 or later;
16 - a DJGPP port of Bash 2.04 or later;
17 - a port of GNU Sed 3.02 or later;
18 - DJGPP ports of Fileutils, Textutils, Sh-utils, Diffutils,
19 Gawk and Grep;
20 - etags (from the Emacs distribution) and mkid (from ID-utils)
21 if you need the TAGS and ID targets of the Makefile's.
22
23 All of the above are available from the DJGPP ftp sites on
24 SimTel.NET mirrors, in the v2gnu directory.
25
26 b. From the root of your DJGPP installation, unzip the source package:
27
28 - if you are unpacking the official GNU source distribution:
29
30 tar -xvzf texinfo-X.YZ.tar.gz
31
32 or
33
34 djtar -x texinfo-X.YZ.tar.gz
35
36 where X.YZ is the version number. (Users of MS-DOS and
37 MS-Windows 3.X, which don't support long file names, will need
38 to rename the archive to something like texi-XYZ.tgz.)
39
40 - if you are unpacking a source distribution from a DJGPP ftp
41 site:
42
43 unzip txiXYZs
44
45 or
46
47 pkunzip -d txiXYZs
48
49 If you build Texinfo on Windows 9X, Windows ME, Windows 2000 or
50 Windows XP, you are advised to use a version of Unzip which
51 supports long filenames, so that the original long filenames of
52 the source files will be preserved. Otherwise, the build
53 procedure will most probably fail.
54
55 Do NOT use an unzip program which supports long file names on
56 Windows NT 4, as DJGPP doesn't support long names there.
57
58 The program unzip32.exe, available from the SimTel.NET site,
59 will deal correctly with long file names on any platform, so it
60 is the recommended way of unzipping txiXYZs.zip archives.
61
62 c. If the source distribution comes with a ready Makefile (this is
63 usually the case with archives downloaded from the DJGPP sites),
64 and all you need is to build Texinfo, you may skip the configure
65 step below and go directly to step e.
66
67 d. To build the official GNU distribution, or to configure Texinfo
68 for any environment but stock DJGPP v2.x, run djgpp\config.bat
69 first, like this:
70
71 SRCDIR\djgpp\config SRCDIR
72
73 Here SRCDIR is the directory where you unpacked the sources. If
74 you are configuring from the source directory itself, you may
75 omit the argument to the config.bat file. If you do supply the
76 argument, you MUST use forward slashes in it, or else the batch
77 file might fail.
78
79 config.bat sets some environment variables, then invokes the
80 configure script. The script will run for a few minutes and
81 create Makefile's in all the directories, and the config.h file.
82
83 e. Run `Make'. This builds the programs and the Info files.
84
85
86
872. Installation
88 ------------
89
90 a. If you are installing the binary distribution, then go to your
91 main DJGPP directory and unzip the files. For instance, if your
92 DJGPP installation is rooted on C:\DJGPP, then type this (XYZ is
93 the version number):
94
95 cd c:\djgpp
96 unzip txiXYZb
97
98 or, if you prefer `pkunzip':
99
100 pkunzip -d txiXYZb
101
102 b. If you downloaded and built Texinfo from sources, install by
103 invoking Make:
104
105 make install
106
107 This requires a port of Unix-like program `install.exe'. It is
108 available from the DJGPP port of GNU Fileutils on SimTel.NET.
109
110 c. Info needs a file named DIR with the top-level menu of all the
111 Info files installed on your system. If you installed the DJGPP
112 development environment (djdevNN.zip), then you already have
113 this file in the info/ subdirectory of your DJGPP installation.
114 Otherwise, you will need to create it. A minimal DIR file is
115 available in this distribution under the name `dir-example',
116 which you can use as a starting point. Copy it to the directory
117 where you install the Info files from this distribution.
118
119 Even if you already have a DIR file, you should review it to
120 make sure it is consistent with the names of the Info file you
121 are installing. Here's how your Texinfo-related entries in DIR
122 should look like:
123
124 * Info: (info).
125 Documentation browsing system. This topic teaches you about
126 how to use the online help information.
127
128 * Info-Standalone: (info-stnd).
129 This topic helps you use the standalone Info-Program (info.exe)
130
131 * infokey: (info-stnd)Invoking infokey.
132 Compile Info key customizations.
133
134 * Makeinfo: (texinfo)Invoking makeinfo.
135 Convert a .texinfo file (.txi) to an info file suitable for the
136 info reader or Emacs, into plain ASCII, into HTML, into XML,
137 or into DocBook.
138
139 * Texinfo: (texinfo).
140 With one source file, make either a printed manual (through TeX)
141 or an on-line manual (through makeinfo). This topic includes
142 a full description of the Texinfo language and related
143 facilities, including Emacs commands to work with Texinfo files.
144
145 * install-info: (texinfo)Invoking install-info.
146 How to update info/dir entries when installing GNU packages.
147
148 * texi2dvi: (texinfo)Format with texi2dvi.
149 Printing Texinfo documentation with TeX.
150
151 * texindex: (texinfo)Format with tex/texindex.
152 Sorting Texinfo index files automatically.
153
154
155 Note that the asterisk `*' should be flushed all the way to the
156 left, it is indented here just to make reading more convenient.
157
158 If your DIR file entries differ from these, I suggest to edit them
159 so they are as shown above. Otherwise, Info might not be able to
160 find some of the files. You HAVE been warned!
161
162 d. Optionally, set up environment variables for Info. These are:
163
164 * INFO_LINES -- screen size for Info.
165 * INFO_COLORS -- screen colors for Info.
166
167 (If you have DJGPP installed on your system, the file djgpp.env
168 which comes with it already has entries for Info, see the [info]
169 section there.)
170
171 INFO_LINES can be one of 25 (the default), 28, 35, 40, 43, or 50
172 (that's if you have a VGA; EGAs only support 25, 35 and 43 lines).
173 I recommend 40 if your monitor is 17" or larger, and at least 28
174 lines for smaller monitors (I work with 40 lines even on 14"
175 monitors).
176
177 INFO_COLORS should have the following syntax:
178
179 set INFO_COLORS=XX.YY
180
181 where XX is the text attribute for text displayed in the text
182 windows and the echo area, and YY is the text attribute for the
183 modeline (aka the status line). Each attribute is a numeric
184 value of a byte which describes the desired combination of
185 foreground and background colors. The individual bits in the
186 attribute byte are defined as follows:
187
188 bBBBFFFF
189
190 where `b' is the blink bit, `BBB' are the 3 bits for background
191 color and `FFFF' are the 4 bits for the foreground color. This is
192 the usual PC text attribute byte structure, and is further explained
193 in any standard reference on text-mode programming for the PC.
194
195 My favorite setting for INFO_COLORS is `0x1e.0x31'. This makes
196 Info use yellow foreground on blue background for the text and
197 blue foreground on cyan background for the modelines.
198
199 After you've played with these variables and have chosen the values
200 you like, it's a good idea to put them on the DJGPP.ENV file, in the
201 [info] section.
202
203 e. Beginning with version 3.6, GNU Info can read Unix man pages. If
204 you have a `man' clone on your system and would like to be able to
205 read man pages with Info, read the chapter ``Reading Man Pages''
206 below. One such clone is available as v2apps/manXYb.zip from
207 the DJGPP sites (XY is the version number).
208
209 f. This port supports compressed Info files, like what Info under Unix
210 gives you. For this to work, you will need to install a DOS port of
211 GNU `Gzip' package and to observe certain rules of file naming, so
212 that Info will find the compressed files working around the DOS 8.3
213 filename restriction. The chapter ``Compressed Info Files'' below
214 explains the details of this.
215
216 g. If you need to use the `print-node' command, read the chapter
217 ``Printing Nodes'' below.
218
219 h. That's it! You are now ready to use Info, Makeinfo, and Texindex.
220 To learn about them, type `Info' and press [Enter]. You will be
221 presented with the top-level menu of GNU/DJGPP hypertext
222 documentation. If you are unfamiliar with Info, press `?' to see
223 the available commands. Pressing `h' will cause Info to take you on
224 a guided tour through its features (recommended for first-time
225 users).
226
227 i. If you are used to Info ports of versions before 3.6, you should
228 know that the command bindings to PC-specific keys has changed: the
229 numeric keypad keys invoke the same commands as their extended
230 namesakes. That is, e.g., the key `PgUp' on the numeric keypad
231 invokes the same command as the grey `PgUp' key on the extended
232 keypad. This was done at DJ's request, because laptop machines
233 don't have extended keys. Commands to move between nodes
234 (previously bound to numeric keypad) are now bound to Ctrl-
235 varieties of numeric keypad keys (e.g., `next-node' is on
236 `Ctrl-PgDn', `prev-node' is on `Ctrl-PgUp', etc.). You can use
237 the `Alt-x describe-key' command to see which command is invoked
238 by a particular key.
239
240 j. There are several MSDOS-specific changes in Texinfo, relative to
241 previous Texinfo ports (for other changes, see the file NEWS):
242
243 * Full support for both forward and backslashes in all file
244 names. Previously, Info was sensitive to the style of
245 slashes in directories mentioned in the INFOPATH environment
246 variable.
247
248 * The default operation of the `print-node' command has been
249 changed so that it automatically prints to the local printer
250 device connected to the PRN port. (If your printer is
251 connected to another port, set the INFO_PRINT_COMMAND
252 environment variable like this:
253
254 set INFO_PRINT_COMMAND=>LPT2
255
256 In other words, if the value of INFO_PRINT_COMMAND begins
257 wih a `>' character, Info will write to the file or device
258 whose name follows the `>' character. (Don't leave any
259 blanks between `>' and the device name!).
260
261 Note that some old versions of stock DOS shell won't let you
262 use the `>' character in environment variables set from the
263 DOS prompt or batch files, but you can set it in the [info]
264 section of your DJGPP.ENV file.
265
266 * The `set-screen-height' command now actually changes the
267 screen dimensions from within Info if you specify one of the
268 sizes supported by your video hardware.
269
270 * If you don't have a `man' clone installed, and you invoke
271 Info with a name of a document which Info cannot find, it
272 will no longer wait for 15 seconds.
273
274 * Several bugs in handling of man pages were corrected.
275
276 * Info opens the dribble and input files in BINARY mode. This
277 allows to record keystrokes and restore them in another Info
278 session, thus using dribble files as a startup or init file
279 which changes default behavior, binds keys, etc.
280
281 * Info recognizes a new DOS-specific command-line option `-b'
282 or `--speech-friendly'. This option causes Info to use DOS
283 I/O functions (`printf', `puts', etc.) instead of direct
284 screen writes, which is required to enable speech
285 synthesizer software (used by visually-impaired people) to
286 grab the output. When this option is given, the screen
287 colors defined by the `INFO_COLORS' environment variable and
288 the visible-bell feature will be disabled, because stdio
289 functions don't support neither color text nor inverting
290 screen colors. This improvement was suggested and
291 originally implemented by Hans-Bernhard Broeker
292 <Broeker@physik.rwth-aachen.de>.
293
294 * Makeinfo now generates full .info-NN filenames when long
295 filenames are supported (e.g. on Win9x) and short .iNN
296 filenames otherwise. When the Texinfo source or the
297 command-line parameter -o specify an output file with no
298 extension (like `texinfo'), and long filenames aren't
299 supported, Makeinfo will make sure the generated names will
300 be unique (it will create e.g. `texinf-1', `texin-10' etc.).
301
302 * The texi2dvi script is now fully compatible with
303 MS-DOS/MS-Windows and with the DJGPP port of TeX.
304
305
3063. Reading Man Pages
307 -----------------
308
309 Yes, Info can now read man pages! This port supports that feature,
310 but for it to work, you will have to make sure your `man' clone is
311 set up correctly:
312
313 a. You should have an executable file named `man.exe', `man.com'
314 etc. somewhere on your PATH.
315
316 b. When invoked with redirected stdout, that executable should
317 print the contents of the file it gets as its argument to stdout
318 and exit. If your man command calls some pager, that pager
319 should have this behavior (various ports of Unix command `more'
320 and the DJGPP port of GNU Less behave that way).
321
322 One `man' clone is available as v2apps/manNNb.zip from the DJGPP
323 sites on SimTel.NET.
324
325
3264. Compressed Info Files
327 ---------------------
328
329 Info allows you to hold your Info files in compressed form, to save
330 disk space. When a file Info wants cannot be found, it will
331 automatically try to find that file in compressed form. Info does
332 this by trying to find the original file with specific extensions.
333 Each extension tells Info which program should be called to
334 decompress the file.
335
336 This port supports compression by the GNU Gzip program. When Info
337 cannot find a file `foo', it will first try to find `foo.z' or
338 `foo.gz'. If this fails, and the file has an extension, the last
339 one or two characters of the extension are replaced by `z' and `gz'
340 respectively, and Info tries again. If it finds any of these, it
341 will call the `GUnzip' program to decompress the file, catch its
342 output and display it. (The original compressed file stays
343 intact.)
344
345 So, to use this feature, compress your files with Gzip and call the
346 compressed files using the following as guidelines:
347
348 foo --> foo.gz
349 foo.inf --> foo.igz
350 foo.i5 --> foo.i5z
351 foo.25 --> foo.25z
352
353 If you have a package whose Info docs are split into more than 9
354 sub-files and you need to compress those files, you will have to
355 rename the sub-files from `foo.iNN' to `foo.NN' so that there will
356 be place for the trailing `z' in the compressed names. Don't
357 forget to edit the indirect file table in the main Info file and
358 change the sub-file filenames there too!
359
360 An alternative for those packages which have more than 99 Info
361 sub-files is to generate them from the Texinfo sources and force
362 Makeinfo to produce files without the .iNN extensions, like this:
363
364 makeinfo -o foo foo.txi
365
366 This causes Makeinfo to generate file names like foo-1, foo-2,
367 etc., which leave more place for the numeric index. If necessary,
368 Makeinfo will automatically remove characters from the end of the
369 argument to `-o'. For example, "-o texinfo" produces files
370 texinf-1, ..., texin-10, ..., texi-100, etc. on platforms which
371 only support 8+3 file names.
372
373 Saying "@setfilename foo" near the beginning of the Texinfo source
374 file is another way of forcing Makeinfo to produce files without
375 the .iNN extensions.
376
377 Using Makeinfo to produce files whose names are "compression-ready"
378 is more convenient, since you don't need to edit the the indirect
379 file table to reflect the changes in file names.
380
381 On platforms which support long filenames, the usual Info behavior
382 of appending `.gz' or `.Z' to the original filename also works;
383 this is done *before* Info checks the above butchered names.
384
385 Special considerations apply if you are installing Info on dual
386 DOS/Windows 9X/ME/2K/XP system, where you'd like Info to work with
387 the same files both in plain DOS and from the Windows DOS box. In
388 this case, you should make sure your compressed Info files follow
389 the 8+3 DOS naming conventions outlined above, even though Info
390 supports long file names on Windows 9X. Also, you need to turn off
391 the generation of numeric tails in short 8+3 aliases Windows
392 creates for long names (if you don't know how, the DJGPP FAQ list
393 explains it).
394
395 Please note: for the automatic decompression to work, Info must be
396 able to find the file it looks for with an extension which
397 indicates that the file is compressed. Do NOT call the compressed
398 files as the original uncompressed files were called, or Info
399 won't be able to find them! File names like bison-1, gcc.i10 or
400 make.info-3 have nothing in them to suggest that they are
401 compressed, so don't expect Info to uncompress them.
402
403
4045. Printing Nodes
405 --------------
406
407 Info has a `print-node' command. It works by piping the contents of
408 the current node through a program which is named by the environment
409 variable INFO_PRINT_COMMAND. That command should read its standard
410 input and write it to your printer. Find any such program, put its
411 name into the above environment variable, and you can print nodes from
412 within Info.
413
414 If the value of INFO_PRINT_COMMAND begins with a redirection
415 character `>', Info will write the contents of the node to the file
416 whose name follows the `>' character.
417
418 If INFO_PRINT_COMMAND is not defined, the DJGPP port will use
419 ">PRN" as the default, which causes it to print to the local printer
420 device, PRN.
421
4226. Bug Reports
423 -----------
424
425 If you see any bugs which seem specific to this DOS port, please tell
426 me about them.
427
428
429 Enjoy,
430
431 Eli Zaretskii <eliz@is.elta.co.il>
432