"Fossies" - the Fresh Open Source Software Archive

Member "texinfo-6.5/djgpp/README" (22 Apr 2014, 18830 Bytes) of package /linux/misc/texinfo-6.5.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 Building and installing GNU Texinfo with DJGPP v2.x
    2 ===================================================
    3 
    4 This directory holds files required for building Texinfo with DJGPP
    5 tools for MS-DOS and MS-Windows.  If you got this file with a binary
    6 distribution, look for the "Installation" section below.
    7 
    8 
    9 1. 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 
   87 2. 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 
  306 3. 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 
  326 4. 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 
  404 5. 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 
  422 6. 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>