summaryrefslogtreecommitdiffstats
path: root/arch/djgpp/README
diff options
context:
space:
mode:
Diffstat (limited to 'arch/djgpp/README')
-rw-r--r--arch/djgpp/README361
1 files changed, 361 insertions, 0 deletions
diff --git a/arch/djgpp/README b/arch/djgpp/README
new file mode 100644
index 0000000..90a5a6d
--- /dev/null
+++ b/arch/djgpp/README
@@ -0,0 +1,361 @@
+ Copyright (C) 2000-2020 Free Software Foundation, Inc.
+
+ Copying and distribution of this file, with or without
+ modification, are permitted in any medium without royalty provided
+ the copyright notice and this notice are preserved.
+
+This is a port of GNU Groff to DJGPP v2.03 or later.
+Groff is the GNU version of document formatting tools related to
+'troff'.
+
+This README file describes how to build and install Groff on MS-DOS or
+MS-Windows systems using the DJGPP port of GNU C/C++ compiler and
+development tools.
+
+
+I. Installing the pre-compiled binary package
+ ------------------------------------------
+
+ 1. Unzip the file groNNNb.zip (where NNN is the version number)
+ preserving the directory structure (-d switch to PKUNZIP) from
+ the main DJGPP installation directory. If you will use Groff
+ on Windows 9x, Windows 2000, or later, use an unzip program
+ which supports long filenames.
+
+ 2. Groff binaries were configured so that they will look for their
+ standard directories under the directory pointed to by the
+ DJDIR environment variable, so it should work automatically if
+ you have DJGPP installed. If you don't have a standard DJGPP
+ installation, set the variable DJDIR to point to the directory
+ where you unzip Groff. In this latter case, you will need to
+ set additional environment variables:
+
+ GROFF_TMAC_PATH=%DJDIR%/share/groff/<version>/tmac:%DJDIR%/share/groff/site-tmac
+ GROFF_TYPESETTER=ascii
+ GROFF_FONT_PATH=%DJDIR%/share/groff/<version>/font
+
+ <version> is something like '1.16.1' or '1.17'.
+
+ In addition, you can set the variable GROFF_TMPDIR to point to
+ a directory where you want Groff to create temporary files it
+ needs for running its jobs (these files are automatically
+ deleted when Groff exits).
+
+ All of those variables are automatically set in the file
+ DJGPP.ENV that is part of the standard DJGPP distribution
+ djdevNNN.zip (where NNN is the DJGPP version number), so you
+ only need to set them manually if you don't have DJGPP
+ installed.
+
+ Note that the GROFF_TYPESETTER variable sets the default Groff
+ device to be 'ascii', which is suitable for formatting man
+ pages to be viewed on the terminal. Use the -T switch to
+ generate output for other devices (e.g., -Tps for PostScript).
+
+ 3. If your TMPDIR environment variable points to a RAM drive, you
+ might consider changing GROFF_TMPDIR to point to a directory on
+ a real disk drive, especially if you intend to generate
+ PostScript output, because RAM disks are typically small (2-3
+ MBytes) which might be not enough for formatting large
+ documents.
+
+ 4. Read the docs. It comes as formatted manual pages called *.1,
+ *.5 and *.7 which unzip into your man/ subdirectory. You
+ can read them with a pager such as GNU Less (recommended, as
+ Less will use colors for bold and underlined text) or with
+ Info (which will remove the bold/underline attributes).
+ Another alternative is to use Emacs built-in man page reader;
+ the DJGPP FAQ lists other possibilities.
+
+ Beginning with version 1.15, Groff comes with an Info manual;
+ type "info -f groff" to read it. The Info manual is still
+ under construction, so some sections are empty.
+
+ If you want to add a Groff entry to the main Info menu in the
+ file DIR, chdir to the 'info' subdirectory of the main Groff
+ installation directory and run this command:
+
+ install-info --dir-file=dir groff.info
+
+ After you do that, "info groff" will also work.
+
+ 5. For those who only need Groff to format man pages and don't
+ like reading the docs, here's a minimal cookbook:
+
+ groff -man -s foo.1 > foo.man
+
+ where 'foo.1' is the troff source of the man page and 'foo.man'
+ is the formatted page. If you need to view the man page, say
+ this:
+
+ groff -man -s foo.1 | less
+
+ You can also use the DJGPP clone of the Unix 'man' command, in
+ which case 'man' runs the above command for you automatically.
+
+ Here's how you print man pages on a PostScript printer:
+
+ groff -man -s -Tps foo.1 > prn
+
+ And this is for a LaserJet4 printer:
+
+ groff -man -s -Tlj4 foo.1 > prn
+
+ Printing the documents produced by Groff is possible either by
+ redirecting Groff's standard output to the local printer
+ device, like shown above, or by using the '-l' switch to Groff.
+ The latter possibility causes Groff to pipe its output to a
+ program whose name and arguments appear in the files named
+ 'DESC' in each of the 'devFOO' subdirectories of the
+ %DJDIR%/share/groff/<version>/font directory; for example, the
+ file devps/DESC is used by "groff -Tps". The relevant line in
+ these files begins with the word "print".
+
+ As configured, when invoked with the '-l' switch, Groff will
+ call 'cat' (from GNU Textutils) to pipe its output to the
+ default printer device for -Tps, -Tlbp and -Tlj4 options, and
+ it will call 'dvilj4' (from the dvljNNNb.zip package) for -Tdvi
+ option. If you don't have these programs installed, you can
+ edit the respective 'DESC' files to replace these commands with
+ something else. The replacement program must be able to read
+ its standard input and send its output to whatever printer you
+ want. The "print" entry is assumed to be a shell command, so
+ it can use redirection, pipes, and other shell features.
+
+ Beginning with version 1.15, Groff can create HTML output, like
+ this:
+
+ groff -man -s -Thtml foo.1 > foo.html
+
+ Producing HTML files sometimes requires Ghostscript to be
+ installed, and, for gif images, ppmquant and ppmtogif as well.
+ If you do not have these programs installed, Groff will print
+ an error message, and the produced file will have links which
+ will fail to resolve when you view it with a Web browser.
+
+ 6. Some programs in the package are supplied as Unix shell
+ scripts. While it is relatively easy to write a DOS batch file
+ which will do the same, DOS doesn't allow to redirect input and
+ output of a batch file. Since Groff tools are meant to be
+ invoked in a pipe, the batch files are not very useful. The
+ batch files are included in the binary distribution
+ nonetheless.
+
+ These scripts need the following utilities to run (in addition
+ to the Groff programs they invoke):
+
+ - bash
+ - gawk
+ - egrep
+ - sed
+
+ The 'afmtodit' and 'mmroff' utilities are Perl scripts, so you
+ will need a Perl port to run them.
+
+ All of these ports should be available from the DJGPP sites.
+
+ If you need to run these scripts and batch files, you have to
+ install the port of bash (or another Unix-like shell) and the
+ above-mentioned utilities called by the script. Alternatively,
+ just look inside the shell script and invoke the programs it
+ calls manually.
+
+ To run the scripts with redirection, invoke them via the shell,
+ like this: "sh mmroff > foo".
+
+ 7. Note that Groff programs use floating point, so you will need
+ an FP emulator if your machine doesn't have an FPU. The binary
+ distribution includes the emulator, in case you don't have the
+ DJGPP development environment installed. Please refer to the
+ DJGPP FAQ list in case you have any problems with the emulator.
+
+ 8. The package does not include the directories under
+ share/groff/<version>/font whose names begin with "devX": these
+ are needed on the X Window System for running the gxditview
+ program, which is not supported by this port.
+
+ 9. Due to 8+3 limitations of DOS filesystems, several files were
+ renamed:
+
+ - groff_mdoc.samples.7 was renamed to groff-mdoc_samples.7
+ and groff_mmse.7 to groff-mmse.7. The latter was also
+ converted from Latin-1 encoding to codepage 437.
+
+
+
+II. Building Groff from sources
+ ---------------------------
+
+ 1. To build Groff, you will need the following tools (the file
+ name in parentheses is what you need to download from one of
+ the DJGPP sites):
+
+ - Standard DJGPP development environment (djdev203.zip)
+ - GNU C compiler (gcc2721b.zip)
+ - GNU C++ compiler (gpp2721b.zip)
+ - GNU Make 3.79 (mak379b.zip)
+ - Bash v2.03 (bsh203b.zip)
+ - Fileutils 3.16 (fil316b.zip)
+ - Textutils 2.0 (txt20b.zip)
+ - Sh-utils 1.12 (shl112b.zip)
+ - Sed 3.02 (sed302b.zip)
+ - Gawk 3.04 (gwk304b.zip)
+ - Grep 2.4 (grep24b.zip)
+ - Bison (only if you change one of the *.y files)
+
+ Note that you don't need to install libg++ (lgpNNNb.zip) since
+ Groff doesn't use any C++ classes except its own.
+
+ Any versions of the utilities later than what's mentioned above
+ should also do; in particular, GCC 2.95.2 was tested and Groff
+ built okay with it. Versions older than in the above list
+ might also work, but I don't guarantee that; you are on your
+ own.
+
+ Special considerations apply if you have GCC 2.8.1 installed,
+ and cannot upgrade to a later version. See paragraph 4 below.
+
+ After you install these tools, make sure you have a "symlink"
+ to bash.exe called sh.exe and a "symlink" to gawk.exe called
+ awk.exe. If not, go to the DJGPP bin/ subdirectory and type
+ the following words of wisdom from the DOS prompt:
+
+ ln -s bash.exe sh.exe
+ ln -s gawk.exe awk.exe
+
+ ('ln' is part of GNU Fileutils, see above.)
+
+ 2. Unzip the source distribution groXYZs.zip (where XYZ is the
+ version number) preserving the directory structure (-d switch
+ to PKUNZIP) from the main DJGPP installation directory. (If
+ you are building Groff on Windows 9x, Windows 2000, or later,
+ use an unzip program which supports long filenames.) This
+ creates directory gnu/groff-X.YZ and unzips the sources there.
+
+ If you are building from the official GNU distribution, unpack
+ the .tar.gz archive like this:
+
+ djtar -x groff-X.YZ.tar.gz
+
+ (DJTAR is part of the standard DJGPP development distribution.)
+
+ 3. Groff sources on DJGPP sites are already configured for the
+ current version of DJGPP. If that is the version you have,
+ then you can just chdir to gnu/groff-X.YZ and say "make" to
+ build the entire package (if you have GCC 2.8.1, see the next
+ paragraph).
+
+ If you have version of DJGPP other than the current one, or if
+ you build the official GNU distribution, or if you prefer to
+ configure the package so that it defaults to the directory
+ structure on your machine, or need to change some options
+ (e.g., compile with different optimization options), you will
+ have to reconfigure Groff. To this end, use the CONFIG.BAT
+ batch file in the DJGPP subdirectory:
+
+ arch\djgpp\config
+
+ You can configure and build Groff from outside its source
+ directory. In that case, you need to pass the full path to the
+ source directory as an argument to CONFIG.BAT, like this:
+
+ d:\gnu\groff-1.16\arch\djgpp\config d:/gnu/groff-1.16
+
+ Note that you MUST use forward slashes in the path you pass to
+ CONFIG.BAT, or else it may fail. (For versions of Groff other
+ than 1.16, change the above command accordingly.)
+
+ 4. If your version of GCC is 2.8.1, you cannot build the
+ preconfigured package without some tinkering. The DJGPP port
+ of GCC 2.8.1 had a bug in its C++ configuration, whereby the
+ file _G_config.h erroneously indicated that the header
+ <sys/socket.h> is available, and also undefined the symbol
+ NULL. This causes several files in the Groff distribution to
+ fail to compile.
+
+ The easiest way to solve this is to upgrade to a later version
+ of GCC; then you can simply say "make" to build the
+ preconfigured package. If this is not an option, you will have
+ to edit the file lang/cxx/_G_config.h and change this line:
+
+ #define _G_HAVE_SYS_SOCKET 1
+
+ to say this instead:
+
+ #define _G_HAVE_SYS_SOCKET 0
+
+ The problem with redefining NULL should not happen with DJGPP
+ v2.03 or later. But if you still see compilation errors which
+ say "'NULL' undeclared", comment out the line in _G_config.h
+ that says this:
+
+ #undef NULL
+
+ Alternatively, you can reconfigure the package as described in
+ the previous paragraph, before building it.
+
+ 5. After the configure script exits, say "make" to build Groff.
+ Groff is a large package, and it might take a few minutes to
+ build, depending on your CPU, so you might as well go for a
+ coffee while it grinds away.
+
+ 6. Test the package that you have built. A batch file T-GROFF.BAT
+ in the DJGPP subdirectory is supplied for that purpose. Most
+ of the commands there are commented out, since I cannot
+ possibly know what kind of printer do you have and which
+ additional programs, such as Less, do you have installed. The
+ only command that runs by default will format a large document
+ and print it to the screen. Read the comments in the batch
+ file, uncomment additional lines as you see fit and run the
+ batch file to see that you get the document printed as you'd
+ expect. (Btw, the document that the batch file prints is an
+ introduction to the entire Groff package, so you might as well
+ read it to make yourself familiar with the programs.)
+
+ Note that the batch file sets a lot of environment variables;
+ if you get "Out of environment space" messages, launch a
+ subsidiary COMMAND.COM with plenty of environment space, like
+ so:
+
+ command.com /e:3000
+
+ then invoke T-GROFF.BAT from that COMMAND.COM.
+
+ 7. Install the package by typing "make install". This will copy
+ all the binaries, the auxiliary files (fonts, macros, etc.) and
+ the docs into their places. If you configured the package for
+ your system, these are precisely the directories where the
+ files should remain (with the exception of the man pages, see
+ below). If you use the default configuration, the files will
+ be installed under the top DJGPP installation directory.
+
+ Alternatively, you could instruct Make explicitly where to
+ install the package by setting the 'prefix' variable. For
+ example:
+
+ make install prefix=c:/groff
+
+ "make install" doesn't format the man pages, it just copies
+ them into subdirectories of the %DJDIR%\MAN directory. If you
+ need to keep formatted pages in your man/ subdirectory, you
+ will need to format them. Use the commands shown in chapter I,
+ section 5 above to do that, and redirect its output to the
+ appropriate catN subdirectory. Alternatively, you could format
+ the pages when you need to view them (the DJGPP clone of 'man'
+ will automatically format them).
+
+ Consult the installation instructions for pre-compiled binaries
+ above, for more info about installing and using Groff.
+
+ 8. You can safely delete the directories under
+ share/groff/<version>/font whose names begin with "devX": these
+ are used by the X Window System client 'gxditview', which is
+ not supported by this port.
+
+
+##### Editor settings
+Local Variables:
+mode: text
+fill-column: 70
+End:
+vim: set autoindent textwidth=70: