diff options
Diffstat (limited to '')
| -rw-r--r-- | README | 130 | ||||
| -rw-r--r-- | README.MinGW | 326 |
2 files changed, 456 insertions, 0 deletions
@@ -0,0 +1,130 @@ + Copyright (C) 1989-2023 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 the 'groff' document formatting system, a reimplementation and +extension of the AT&T Unix 'troff' system. The version number is given +in the file '.tarball-version' if you are building from a distribution +archive; otherwise, building from its Git repository will store it in +the file '.version'. + +This release includes original implementations (not derived from AT&T +Unix code) of the 'troff', 'nroff', 'pic', 'eqn', 'tbl', 'refer', and +'soelim' programs; the 'man' and 'ms' macro packages; and output drivers +for PostScript, PDF, and TeX DVI file formats, HP LaserJet 4- and Canon +CaPSL-compatible printers, HTML and XHTML (in beta status), and +typewriter/terminal devices. + +It also provides modified versions of BSD Unix additions to Unix troff: +the 'grn' preprocessor, and the 'mdoc' and 'me' macro packages. +'gxditview', an enhanced version of the X11 'xditview' previewer for +'troff' device-independent output, originates from X11R5. + +Contributed components feature a reimplementation and extension of the +DWB 'troff' 'mm' macro package by Joergen Haegg, Peter Schaffter's 'mom' +macro package, and Bernd Warken's reimplementation of the 'chem' +preprocessor in Perl. + +See the file 'INSTALL.extra' for instructions on how to install from a +distribution archive, such as a release, beta, or release candidate. + +The file 'INSTALL.REPO' contains supplementary instructions for building +directly from a clone of the Git repository. + +The file 'NEWS' contains a history of user-visible changes to 'groff'. + +'groff' is free software. See the file 'COPYING' for copying +permissions, and 'LICENSES' for further detail. + +The file 'PROBLEMS' describes various issues that users have encountered +in compiling, installing, and running 'groff'. + +The file 'MORE.STUFF' describes some third-party programming and +documentary resources useful with 'groff'. + +Current and historical releases of 'groff' are available via HTTPS and +anonymous FTP from the host 'ftp.gnu.org' in the directory 'gnu/groff'. + +'groff' has a home page at the GNU Project. + +https://www.gnu.org/software/groff/ + +Administration of the project is done through GNU Savannah. + + https://savannah.gnu.org/git/?group=groff + +'groff' is developed at its Git repository, which has a web interface. + + https://git.savannah.gnu.org/cgit/groff.git + +You can view any commit in isolation, and browse the entire source tree +corresponding to its state as of that commit. Click the summary line of +the commit message to expose these options. + +Build requirements are discussed in the 'INSTALL.extra' and +'INSTALL.REPO' files noted above. 'groff' also has runtime +dependencies. + +Ghostscript is required for creation of PDF and (X)HTML output. +Production of (X)HTML furthermore demands tools from the 'netpbm' and +'psutils' packages. + +Perl is required for production of PDF output using the 'gropdf' output +driver. (You can alternatively produce PostScript with 'grops' and +convert that to PDF using Ghostscipt.) The 'chem', 'gperl', and +'gpinyin' preprocessors and several utilities, such as 'grog', are also +written in Perl. + +If 'groff' is configured with 'lp' or 'lpr' support, the corresponding +program must remain available on the system for the 'groff' command's +'-l' option to work. Similarly, build-time detection of development +headers for the 'uchardet', 'Xaw', and 'Xmu' libraries (and their +dependencies) assumes that their runtime counterparts will remain +installed to support the 'groff' that is built. + +You can view or add to to groff's bug database via its issue tracker on +the Savannah site (also linked from the groff home page). + + http://savannah.gnu.org/bugs/?group=groff + +To report a problem, you may use the form in the file 'BUG-REPORT'; its +purpose is to make sure that FSF has all the information it needs to fix +the bug. At the very least, read the 'BUG-REPORT' form and make sure +that you supply all the information that it asks for. Even if you are +not sure that something is a bug, please report it so we can determine +whether it is a software defect, or an omission from our documentation. + +If you'd like to modify 'groff' or participate in its development, files +'HACKING' and 'MANIFEST' will familiarize you with the structure of the +code and the project's conventions for maintaining it. + +Three mailing lists are available. + + bug-groff@gnu.org a read-only list for following bug reports + groff@gnu.org for general discussion of groff + groff-commit@gnu.org a read-only list for following commits + to the Git repository + +To subscribe, send a mail to <list>-request@<domain> (example: +groff-request@gnu.org for the 'groff' list) with the word 'subscribe' +in either the subject or body of the email (don't include the quotes). +Alternatively, subscribe via our web pages by completing an HTML form. + + https://lists.gnu.org/mailman/listinfo/bug-groff + https://lists.gnu.org/mailman/listinfo/groff + https://lists.gnu.org/mailman/listinfo/groff-commit + +Each of these web pages also provides a link to a browseable archive of +postings to the corresponding mailing list. + +'groff' was primarily written by James Clark <jjc@jclark.com>. + + +##### Editor settings +Local Variables: +fill-column: 72 +mode: text +End: +vim: set textwidth=72: diff --git a/README.MinGW b/README.MinGW new file mode 100644 index 0000000..412597a --- /dev/null +++ b/README.MinGW @@ -0,0 +1,326 @@ + Copyright (C) 2003-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. + + README.MinGW + ============ + + Contributed by Keith Marshall (keith.d.marshall@ntlworld.com) + + + INTRODUCTION + ------------ + + This file provides recommendations for building a Win32 implementation + of GNU Groff, using the MinGW port of GCC for Microsoft (TM) + Windows-32 platforms. It is intended to supplement the standard + installation instructions (see file INSTALL); it does not replace + them. + + You require both the MinGW implementation of GCC and its supporting + MSYS toolkit, which provides a Win-32 implementation of the GNU bash + shell, and a few other essential utilities; these may be obtained from + + http://sourceforge.net/projects/mingw + + by following the appropriate download links, where they are available + as self-extracting executable installation packages. If installing + both from scratch, it is recommended that MinGW is installed first, as + the MSYS installer can then automatically set up the proper + environment for running MinGW. + + Additionally, if you wish to compile groff with support for its HTML + (and XHTML) output capability, some additional tools are required as + described in the section PREREQUISITES FOR HTML OUTPUT later in this + file. + + + BUILDING GROFF WITH MINGW + ------------------------- + + *** WARNING *** + + Before commencing this procedure, you should ensure that you are + running the MSYS shell in a *native* Win32 console window, and not in + any window managed by the rxvt emulator provided with MSYS; (this + emulator suffers from various known defects, which will prevent + successful completion of a groff build). + + ****** + + Assuming that you have obtained the appropriate groff distribution, + and that you are already running an MSYS shell, then the + configuration, compilation, and installation of groff, using MinGW, is + performed in much the same way as it is described in the INSTALL file, + which is provided with the groff distribution. The installation steps + are summarised below: + + 1. Change working directory to any suitable location where you may + unpack the groff distribution; you must be authorized for write + access. Approximately 30MB of free disk space are needed. + + 2. Unpack the groff distribution: + + tar xzf <download-path>/groff-<version>.tar.gz + + This creates a new sub-directory, groff-<version>, containing an + image of the groff source tree. You should now change directory, + to make this ./groff-<version> your working directory. + + 3. If you are intending to build groff with support for HTML (and + XHTML) output, then you must now ensure that the prerequisites + described in the later section PREREQUISITES FOR HTML OUTPUT are + satisfied, before proceeding to build groff; in particular, please + ensure that all required support programs are installed in the + current PATH. + + 4. You are now ready to configure, build, and install groff. This is + accomplished using the conventional procedure, as described in the + file INSTALL, i.e. + + ./configure --prefix=<win32-install-path> ... + make + make install + + Please observe the syntax for the configure command, indicated + above; the default value for --prefix is not suitable for use with + MinGW, so the --prefix=<win32-install-path> option must be + specified, where <win32-install-path> is the chosen MS-Windows + directory in which the groff application files are to be installed + (see the later section entitled CHOOSING AN INSTALLATION PATH). + Any other desired configuration options may also be specified, as + described in the standard groff installation instructions. + + 5. After completing the above, groff should be successfully installed; + the build directory is no longer required; it may be simply deleted + in its entirety. Alternatively, you may choose to keep it, but to + remove all files which can be reproduced later, by repeating the + configure, make and make install steps; this is readily + accomplished by the command + + make distclean + + + This completes the installation of groff; please read the final + sections of this file, GROFF RUNTIME ENVIRONMENT and CAVEATS AND BUGS, + for advice on setting up the runtime environment, and avoiding known + runtime problems, before running groff. + + + CHOOSING AN INSTALLATION PATH + ----------------------------- + + It may be noted that the above instructions indicate that the + ./configure command must be invoked with an argument specifying a + preference for --prefix=<win32-install-path>, whereas the standard + groff installation instructions indicate that this may be omitted, in + which case it defaults to --prefix=/usr/local. + + In the case of building with MinGW, the default behaviour of configure + is not appropriate for the following reasons. + + o The MSYS environment creates a virtual Unix-like file system, with + its root mapped to the actual MS-Windows directory where MSYS itself + is installed; /usr is also mapped to this MSYS installation + directory. + + o All of the MSYS tools, and the MinGW implementation of GCC, refer to + files via this virtual file system representation; thus, if the + --prefix=<win32-install-path> is not specified when groff is + configured, `make install' causes groff to be installed in + <MSYS-install-path>/local. + + o groff needs to know its own installation path, so that it can locate + its own installed components. This information is compiled in, + using the exact form specified with the + --prefix=<win32-install-path> option to configure. + + o Knowledge of the MSYS virtual file system is not imparted to groff; + it expects the compiled-in path to its components to be a fully + qualified MS-Windows path name (although Unix-style slashes are + permitted, and preferred to the MS-Windows style backslashes, to + demarcate the directory hierarchy). Thus, when configuring groff, + if --prefix=<win32-install-path> is not correctly specified, then + the installed groff application looks for its components in + /usr/local, and most likely doesn't find them, because they are + actually installed in <MSYS-install-path>/local. + + It is actually convenient, but by no means a requirement, to have + groff installed in the /usr/local directory of the MSYS virtual file + system; this makes it easy to invoke groff from the MSYS shell, since + the virtual /usr/local/bin is normally added automatically to the PATH + (the default PATH, as set in MSYS's /etc/profile), when MSYS is + started. + + In order to install groff into MSYS's /usr/local directory, it is + necessary to specify the fully qualified absolute MS-Windows path to + this directory, when configuring groff, i.e. + + ./configure --prefix=<MSYS-install-path>/local ... + + For example, on a system where MSYS is installed in the MS-Windows + directory D:\MSYS\1.0, the MSYS virtual path /usr/local resolves to + the absolute MS-Windows native path D:\MSYS\1.0\local (the /usr + component of the MSYS virtual path does not appear in the resolved + absolute native path name since MSYS maps this directly to the root of + the MSYS virtual file system). Thus, the --prefix option should be + specified to configure as + + ./configure --prefix=D:/MSYS/1.0/local ... + + Note that the backslash characters, which appear in the native + MS-Windows form of the path name, are replaced by Unix-style slashes + in the argument to configure; this is the preferred syntax. + + Also note that the MS-Windows device designator (D: in this instance) + is prepended to the specified path, in the normal MS-Windows format, + and that, since upper and lower case distinctions are ignored in + MS-Windows path names, any combination of upper and lower case is + acceptable. + + + PREREQUISITES FOR HTML OUTPUT + ----------------------------- + + If you intend to use groff for production of HTML or XHTML output, + then there are a few dependencies which must be satisfied. Ideally, + these should be resolved before attempting to configure and build + groff, since the configuration script does check them. + + In order to produce HTML or XHTML output, you first require a working + implementation of Ghostscript; either the AFPL Ghostscript or the GNU + Ghostscript implementation for MS-Windows should be suitable, + depending on your licensing preference. It is highly recommended to + use version 8.11 or higher due to bugs in older versions. These may + be obtained, in the form of self-installing binary packages, by + following the download links for the chosen licensing option, from + http://sourceforge.net/projects/ghostscript. + + Please note that these packages install the Ghostscript interpreter + required by groff in the ./bin subdirectory of the Ghostscript + installation directory, with the name gswin32c.exe. However, groff + expects this interpreter to be located in the system PATH, with the + name gs.exe. Thus, to ensure that groff can correctly locate the + Ghostscript interpreter, it is recommended that the file gswin32c.exe + should be copied from the Ghostscript installation directory to the + MSYS /usr/local/bin directory, where it should be renamed to gs.exe. + + In addition to a working Ghostscript interpreter, you also require + several image manipulation utilities, all of which may be scavenged + from various packages available from + http://sourceforge.net/projects/gnuwin32, and which should be + installed in the MSYS /usr/local/bin directory, or any other suitable + directory which is specified in the PATH. These additional + prerequisites are + + 1. from the netpbm-<version>-bin.zip package: + + netpbm.dll + pnmcrop.exe + pnmcut.exe + pnmtopng.exe + pnmtops.exe + + 2. from the libpng-<version>-bin.zip package: + + libpng.dll + + 3. from the zlib-<version>-bin.zip package: + + zlib-1.dll, which must be renamed to zlib.dll + + 4. from the psutils-<version>-bin.zip package: + + psselect.exe + + Note that it is not necessary to install the above four packages in + their entirety; of course, you may do so if you wish. + + Further note that you are advised to avoid the netpbm-10.27 release + from the GnuWin32 download repository, as its pnmtopng.exe has been + reported to fail on even simple conversions, resulting in failure of + the groff build process; the earlier netpbm-10.18.4 has been found to + work successfully. Also, you may find it necessary to use + libpng-1.2.7, rather than libpng-1.2.8, in conjunction with this + earlier release of netpbm. + + + GROFF RUNTIME ENVIRONMENT + ------------------------- + + The runtime environment, provided to groff by MSYS, is essentially the + same as would be provided under a Unix or GNU/Linux operating system; + thus, any environment variables which may be used to customize the + groff runtime environment have similar effects under MSYS, as they + would in Unix or GNU/Linux, with the exception that any variable + specifying a path should adopt the same syntax as a native MS-Windows + PATH specification. + + There is, however, one known problem which is associated with the + implementation of the MS-Windows file system, and the manner in which + the Microsoft runtime library (which is used by the MinGW + implementation of GCC) generates names for temporary files. This + known problem arises when groff is invoked with a current working + directory which refers to a network share, for which the user does not + have write access in the root directory, and there is no environment + variable set to define a writeable location for creating temporary + files. When these conditions arise, groff fails with a `permission + denied' error, as soon as it tries to create any temporary file. + + To specify the location for creating temporary files, the standard + Unix or GNU/Linux implementation of groff provides the GROFF_TMPDIR or + TMPDIR environment variables, whereas MS-Windows applications + generally use TMP or TEMP; furthermore, the MS-Windows implementations + of Ghostscript apparently support the use of only TEMP or TMPDIR. + + To avoid problems with creation of temporary files, it is recommended + that you ensure that both TMP and TEMP are defined, with identical + values, to point to a suitable location for creating temporary files; + many MS-Windows boxes have them set already, and groff has been + adapted to honour them, when built in accordance with the preceding + instructions, using MinGW. + + + CAVEATS AND BUGS + ---------------- + + There are two known issues, observed when running groff in the + MinGW/MSYS environment, which would not affect groff in its native + Unix environment: + + o Running groff with the working directory set to a subdirectory of a + network share, where the user does not have write permission in the + root directory of the share, causes groff to fail with a `permission + denied' exception, if the TMP environment variable is not + appropriately defined; it may also be necessary to define the TEMP + environment variable, to avoid a similar failure mode, when using + the -Thtml or -Txhtml output mode of groff. This problem is more + fully discussed in the preceding section, GROFF RUNTIME ENVIRONMENT. + + o When running groff (or nroff) to process standard input, where the + standard input stream is obtained directly from the RXVT console + provided with MSYS, groff cannot detect the end-of-file condition + for the standard input stream, and hangs. This appears to be caused + by a fault in the MSYS implementation of RXVT; it may be worked + around by either starting MSYS without RXVT (see the comments in the + MSYS.BAT startup script); in this case standard input is terminated + by typing <Ctrl-Z> followed by <RETURN>, on a new input line. + Alternatively, if you prefer to use MSYS with RXVT, you can enter + the interactive groff command in the form + + cat | groff ... + + in which case <Ctrl-D> terminates the standard input stream, in just + the same way it does on a Unix system; the cat executable provided + with MSYS does seem to trap the end-of-file condition, and properly + signals groff that the input stream has terminated. + + +##### Editor settings +Local Variables: +fill-column: 72 +mode: text +End: +vim: set textwidth=72: |