Building and installing GNU Texinfo with DJGPP v2.x =================================================== This directory holds files required for building Texinfo with DJGPP tools for MS-DOS and MS-Windows. If you got this file with a binary distribution, look for the "Installation" section below. 1. Building Texinfo ---------------- a. To compile Texinfo, you will need the following tools: - basic DJGPP development environment: GCC, Binutils and djdev; - a DJGPP port of GNU Make version 3.78 or later; - a DJGPP port of Bash 2.04 or later; - a port of GNU Sed 3.02 or later; - DJGPP ports of Fileutils, Textutils, Sh-utils, Diffutils, Gawk and Grep; - etags (from the Emacs distribution) and mkid (from ID-utils) if you need the TAGS and ID targets of the Makefile's. All of the above are available from the DJGPP ftp sites on SimTel.NET mirrors, in the v2gnu directory. b. From the root of your DJGPP installation, unzip the source package: - if you are unpacking the official GNU source distribution: tar -xvzf texinfo-X.YZ.tar.gz or djtar -x texinfo-X.YZ.tar.gz where X.YZ is the version number. (Users of MS-DOS and MS-Windows 3.X, which don't support long file names, will need to rename the archive to something like texi-XYZ.tgz.) - if you are unpacking a source distribution from a DJGPP ftp site: unzip txiXYZs or pkunzip -d txiXYZs If you build Texinfo on Windows 9X, Windows ME, Windows 2000 or Windows XP, you are advised to use a version of Unzip which supports long filenames, so that the original long filenames of the source files will be preserved. Otherwise, the build procedure will most probably fail. Do NOT use an unzip program which supports long file names on Windows NT 4, as DJGPP doesn't support long names there. The program unzip32.exe, available from the SimTel.NET site, will deal correctly with long file names on any platform, so it is the recommended way of unzipping txiXYZs.zip archives. c. If the source distribution comes with a ready Makefile (this is usually the case with archives downloaded from the DJGPP sites), and all you need is to build Texinfo, you may skip the configure step below and go directly to step e. d. To build the official GNU distribution, or to configure Texinfo for any environment but stock DJGPP v2.x, run djgpp\config.bat first, like this: SRCDIR\djgpp\config SRCDIR Here SRCDIR is the directory where you unpacked the sources. If you are configuring from the source directory itself, you may omit the argument to the config.bat file. If you do supply the argument, you MUST use forward slashes in it, or else the batch file might fail. config.bat sets some environment variables, then invokes the configure script. The script will run for a few minutes and create Makefile's in all the directories, and the config.h file. e. Run `Make'. This builds the programs and the Info files. 2. Installation ------------ a. If you are installing the binary distribution, then go to your main DJGPP directory and unzip the files. For instance, if your DJGPP installation is rooted on C:\DJGPP, then type this (XYZ is the version number): cd c:\djgpp unzip txiXYZb or, if you prefer `pkunzip': pkunzip -d txiXYZb b. If you downloaded and built Texinfo from sources, install by invoking Make: make install This requires a port of Unix-like program `install.exe'. It is available from the DJGPP port of GNU Fileutils on SimTel.NET. c. Info needs a file named DIR with the top-level menu of all the Info files installed on your system. If you installed the DJGPP development environment (djdevNN.zip), then you already have this file in the info/ subdirectory of your DJGPP installation. Otherwise, you will need to create it. A minimal DIR file is available in this distribution under the name `dir-example', which you can use as a starting point. Copy it to the directory where you install the Info files from this distribution. Even if you already have a DIR file, you should review it to make sure it is consistent with the names of the Info file you are installing. Here's how your Texinfo-related entries in DIR should look like: * Info: (info). Documentation browsing system. This topic teaches you about how to use the online help information. * Info-Standalone: (info-stnd). This topic helps you use the standalone Info-Program (info.exe) * infokey: (info-stnd)Invoking infokey. Compile Info key customizations. * Makeinfo: (texinfo)Invoking makeinfo. Convert a .texinfo file (.txi) to an info file suitable for the info reader or Emacs, into plain ASCII, into HTML, into XML, or into DocBook. * Texinfo: (texinfo). With one source file, make either a printed manual (through TeX) or an on-line manual (through makeinfo). This topic includes a full description of the Texinfo language and related facilities, including Emacs commands to work with Texinfo files. * install-info: (texinfo)Invoking install-info. How to update info/dir entries when installing GNU packages. * texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation with TeX. * texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files automatically. Note that the asterisk `*' should be flushed all the way to the left, it is indented here just to make reading more convenient. If your DIR file entries differ from these, I suggest to edit them so they are as shown above. Otherwise, Info might not be able to find some of the files. You HAVE been warned! d. Optionally, set up environment variables for Info. These are: * INFO_LINES -- screen size for Info. * INFO_COLORS -- screen colors for Info. (If you have DJGPP installed on your system, the file djgpp.env which comes with it already has entries for Info, see the [info] section there.) INFO_LINES can be one of 25 (the default), 28, 35, 40, 43, or 50 (that's if you have a VGA; EGAs only support 25, 35 and 43 lines). I recommend 40 if your monitor is 17" or larger, and at least 28 lines for smaller monitors (I work with 40 lines even on 14" monitors). INFO_COLORS should have the following syntax: set INFO_COLORS=XX.YY where XX is the text attribute for text displayed in the text windows and the echo area, and YY is the text attribute for the modeline (aka the status line). Each attribute is a numeric value of a byte which describes the desired combination of foreground and background colors. The individual bits in the attribute byte are defined as follows: bBBBFFFF where `b' is the blink bit, `BBB' are the 3 bits for background color and `FFFF' are the 4 bits for the foreground color. This is the usual PC text attribute byte structure, and is further explained in any standard reference on text-mode programming for the PC. My favorite setting for INFO_COLORS is `0x1e.0x31'. This makes Info use yellow foreground on blue background for the text and blue foreground on cyan background for the modelines. After you've played with these variables and have chosen the values you like, it's a good idea to put them on the DJGPP.ENV file, in the [info] section. e. Beginning with version 3.6, GNU Info can read Unix man pages. If you have a `man' clone on your system and would like to be able to read man pages with Info, read the chapter ``Reading Man Pages'' below. One such clone is available as v2apps/manXYb.zip from the DJGPP sites (XY is the version number). f. This port supports compressed Info files, like what Info under Unix gives you. For this to work, you will need to install a DOS port of GNU `Gzip' package and to observe certain rules of file naming, so that Info will find the compressed files working around the DOS 8.3 filename restriction. The chapter ``Compressed Info Files'' below explains the details of this. g. If you need to use the `print-node' command, read the chapter ``Printing Nodes'' below. h. That's it! You are now ready to use Info, Makeinfo, and Texindex. To learn about them, type `Info' and press [Enter]. You will be presented with the top-level menu of GNU/DJGPP hypertext documentation. If you are unfamiliar with Info, press `?' to see the available commands. Pressing `h' will cause Info to take you on a guided tour through its features (recommended for first-time users). i. If you are used to Info ports of versions before 3.6, you should know that the command bindings to PC-specific keys has changed: the numeric keypad keys invoke the same commands as their extended namesakes. That is, e.g., the key `PgUp' on the numeric keypad invokes the same command as the grey `PgUp' key on the extended keypad. This was done at DJ's request, because laptop machines don't have extended keys. Commands to move between nodes (previously bound to numeric keypad) are now bound to Ctrl- varieties of numeric keypad keys (e.g., `next-node' is on `Ctrl-PgDn', `prev-node' is on `Ctrl-PgUp', etc.). You can use the `Alt-x describe-key' command to see which command is invoked by a particular key. j. There are several MSDOS-specific changes in Texinfo, relative to previous Texinfo ports (for other changes, see the file NEWS): * Full support for both forward and backslashes in all file names. Previously, Info was sensitive to the style of slashes in directories mentioned in the INFOPATH environment variable. * The default operation of the `print-node' command has been changed so that it automatically prints to the local printer device connected to the PRN port. (If your printer is connected to another port, set the INFO_PRINT_COMMAND environment variable like this: set INFO_PRINT_COMMAND=>LPT2 In other words, if the value of INFO_PRINT_COMMAND begins wih a `>' character, Info will write to the file or device whose name follows the `>' character. (Don't leave any blanks between `>' and the device name!). Note that some old versions of stock DOS shell won't let you use the `>' character in environment variables set from the DOS prompt or batch files, but you can set it in the [info] section of your DJGPP.ENV file. * The `set-screen-height' command now actually changes the screen dimensions from within Info if you specify one of the sizes supported by your video hardware. * If you don't have a `man' clone installed, and you invoke Info with a name of a document which Info cannot find, it will no longer wait for 15 seconds. * Several bugs in handling of man pages were corrected. * Info opens the dribble and input files in BINARY mode. This allows to record keystrokes and restore them in another Info session, thus using dribble files as a startup or init file which changes default behavior, binds keys, etc. * Info recognizes a new DOS-specific command-line option `-b' or `--speech-friendly'. This option causes Info to use DOS I/O functions (`printf', `puts', etc.) instead of direct screen writes, which is required to enable speech synthesizer software (used by visually-impaired people) to grab the output. When this option is given, the screen colors defined by the `INFO_COLORS' environment variable and the visible-bell feature will be disabled, because stdio functions don't support neither color text nor inverting screen colors. This improvement was suggested and originally implemented by Hans-Bernhard Broeker . * Makeinfo now generates full .info-NN filenames when long filenames are supported (e.g. on Win9x) and short .iNN filenames otherwise. When the Texinfo source or the command-line parameter -o specify an output file with no extension (like `texinfo'), and long filenames aren't supported, Makeinfo will make sure the generated names will be unique (it will create e.g. `texinf-1', `texin-10' etc.). * The texi2dvi script is now fully compatible with MS-DOS/MS-Windows and with the DJGPP port of TeX. 3. Reading Man Pages ----------------- Yes, Info can now read man pages! This port supports that feature, but for it to work, you will have to make sure your `man' clone is set up correctly: a. You should have an executable file named `man.exe', `man.com' etc. somewhere on your PATH. b. When invoked with redirected stdout, that executable should print the contents of the file it gets as its argument to stdout and exit. If your man command calls some pager, that pager should have this behavior (various ports of Unix command `more' and the DJGPP port of GNU Less behave that way). One `man' clone is available as v2apps/manNNb.zip from the DJGPP sites on SimTel.NET. 4. Compressed Info Files --------------------- Info allows you to hold your Info files in compressed form, to save disk space. When a file Info wants cannot be found, it will automatically try to find that file in compressed form. Info does this by trying to find the original file with specific extensions. Each extension tells Info which program should be called to decompress the file. This port supports compression by the GNU Gzip program. When Info cannot find a file `foo', it will first try to find `foo.z' or `foo.gz'. If this fails, and the file has an extension, the last one or two characters of the extension are replaced by `z' and `gz' respectively, and Info tries again. If it finds any of these, it will call the `GUnzip' program to decompress the file, catch its output and display it. (The original compressed file stays intact.) So, to use this feature, compress your files with Gzip and call the compressed files using the following as guidelines: foo --> foo.gz foo.inf --> foo.igz foo.i5 --> foo.i5z foo.25 --> foo.25z If you have a package whose Info docs are split into more than 9 sub-files and you need to compress those files, you will have to rename the sub-files from `foo.iNN' to `foo.NN' so that there will be place for the trailing `z' in the compressed names. Don't forget to edit the indirect file table in the main Info file and change the sub-file filenames there too! An alternative for those packages which have more than 99 Info sub-files is to generate them from the Texinfo sources and force Makeinfo to produce files without the .iNN extensions, like this: makeinfo -o foo foo.txi This causes Makeinfo to generate file names like foo-1, foo-2, etc., which leave more place for the numeric index. If necessary, Makeinfo will automatically remove characters from the end of the argument to `-o'. For example, "-o texinfo" produces files texinf-1, ..., texin-10, ..., texi-100, etc. on platforms which only support 8+3 file names. Saying "@setfilename foo" near the beginning of the Texinfo source file is another way of forcing Makeinfo to produce files without the .iNN extensions. Using Makeinfo to produce files whose names are "compression-ready" is more convenient, since you don't need to edit the the indirect file table to reflect the changes in file names. On platforms which support long filenames, the usual Info behavior of appending `.gz' or `.Z' to the original filename also works; this is done *before* Info checks the above butchered names. Special considerations apply if you are installing Info on dual DOS/Windows 9X/ME/2K/XP system, where you'd like Info to work with the same files both in plain DOS and from the Windows DOS box. In this case, you should make sure your compressed Info files follow the 8+3 DOS naming conventions outlined above, even though Info supports long file names on Windows 9X. Also, you need to turn off the generation of numeric tails in short 8+3 aliases Windows creates for long names (if you don't know how, the DJGPP FAQ list explains it). Please note: for the automatic decompression to work, Info must be able to find the file it looks for with an extension which indicates that the file is compressed. Do NOT call the compressed files as the original uncompressed files were called, or Info won't be able to find them! File names like bison-1, gcc.i10 or make.info-3 have nothing in them to suggest that they are compressed, so don't expect Info to uncompress them. 5. Printing Nodes -------------- Info has a `print-node' command. It works by piping the contents of the current node through a program which is named by the environment variable INFO_PRINT_COMMAND. That command should read its standard input and write it to your printer. Find any such program, put its name into the above environment variable, and you can print nodes from within Info. If the value of INFO_PRINT_COMMAND begins with a redirection character `>', Info will write the contents of the node to the file whose name follows the `>' character. If INFO_PRINT_COMMAND is not defined, the DJGPP port will use ">PRN" as the default, which causes it to print to the local printer device, PRN. 6. Bug Reports ----------- If you see any bugs which seem specific to this DOS port, please tell me about them. Enjoy, Eli Zaretskii