texinfo/djgpp

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