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