Texinfo, Version 3.9 for MS-DOS/DJGPP v2.1 ========================================== This is the README.djgpp file. It discusses issues specific to the port of GNU Texinfo 3.9 to the DJGPP environment under MS-DOS. See the other docs (README, NEWS, Changelog, INTRODUCTION, TODO) for more general issues concerning this package. Many thanks to Hans-Bernhard Broeker who did all the mundane work of applying DJGPP-specific DIFFS from the Texinfo 3.6 distribution to v3.7, and also suggested many improvements to the code. This made my work of porting Texinfo 3.9 really easy and pleasant. 1. Installation ------------ a. Go to your main DJGPP directory. For instance, if your DJGPP installation is rooted on C:\DJGPP, then type this: cd c:\djgpp b. Unzip the binary package: pkunzip -d txi39b or, if you prefer `unzip': unzip txi39b c. Optionally, set up environment variables for Info. These are: * INFO_LINES -- screen size for Info. * INFO_COLORS -- screen colors for Info. 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 PC. My favorite setting for INFO_COLORS is `0x1e.0x31'. 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. d. 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. e. 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. f. If you need to use the `print-node' command, read the chapter ``Printing Nodes'' below. g. 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). h. If you are used to Info ports of versions before 3.6, you should know that the command binding 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 `M-x describe-key' command to see which command is invoked by a particular key. i. There are 3 MSDOS-specific changes in Texinfo 3.9, relative to previous Texinfo ports: * 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 will be disabled, because stdio functions don't support color text. This improvement was suggested and 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.). 2. Building Texinfo ---------------- a. To recompile Texinfo, you will need the following tools: - `update' and `redir' from the DJGPP djdev distribution - `ar' and `ranlib' (e.g. from GNU Binutils) - `sed' (the DJGPP port of GNU Sed recommended) - `etags' (only if you need to generate the Emacs TAGS files) - `rm' (for the `clean' targets only) - `emacs' (to byte-compile the files in emacs/ directory); only required if your Emacs version is older than 19.31, because the .el files in Texinfo 3.9 are never newer than those which come with Emacs 19.31 and later b. From the root of your DJGPP installation, unzip the source package: unzip txi39s or pkunzip -d txi39s If you build Texinfo on Windows 9x, 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. c. Go to the topmost directory of Texinfo distribution: cd gnu\texinfo3.9 d. Run `CONFIGUR.BAT'. This creates `config.h' file in the topmost directory and Makefiles in all the directories. It does so by running the `configdj.sed' and `confsub.sed' Sed scripts. e. Run `Make'. This builds the programs and the Info files. f. If you need the Emacs support files from the emacs/ directory, go into that directory and type: make elisp g. Install the programs and the other products as appropriate. The various `install:' targets will only work if you have a Unix-like shell installed anywhere on your PATH under the name `sh' with any executable extensions, like `sh.exe', `sh.com', `sh.bat' etc. h. The `DIFFS' file in the topmost Texinfo directory (the one where you run Make) describes the patches applied to the official GNU distribution for this port, so you can see what I've broken. Note that some of the patches correct what I think are genuine bugs in the original sources (I've reported those to FSF; most of them merely pacify gcc when invoked with -Wall switch). 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). In the extreme case, you can create a `man.bat' batch file which just prints the contents of the file given as its argument, like this: @echo off type d:\yourpath\%1.1 (this assumes that you hold formatted man pages in d:\yourpath). 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! 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. 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. 6. Bug Reports ----------- If you see any bugs which seem specific to this DOS port, please tell me about them. Enjoy, Eli Zaretskii