source: trunk/essentials/sys-apps/texinfo/djgpp/README

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
          <Broeker@physik.rwth-aachen.de>.

        * 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 <eliz@is.elta.co.il>