[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 10/10: Reflow or fix long lines in top-level docs.
|
From: |
G. Branden Robinson |
|
Subject: |
[groff] 10/10: Reflow or fix long lines in top-level docs. |
|
Date: |
Tue, 28 Apr 2020 11:59:27 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit 1dfbbf0b56964f75c589174680d02422d5328017
Author: G. Branden Robinson <address@hidden>
AuthorDate: Wed Apr 29 01:00:28 2020 +1000
Reflow or fix long lines in top-level docs.
This did not produce much churn except in README.MinGW, which seems to
have been deliberately wrapped at 76 columns instead of 72--sorry.
Also update (in INSTALL.REPO's case, add) editor settings.
---
INSTALL.REPO | 13 +-
MANIFEST | 18 +--
MORE.STUFF | 110 +++++++++--------
PROBLEMS | 8 +-
PROJECTS | 8 +-
README | 6 +-
README.MinGW | 394 +++++++++++++++++++++++++++++++----------------------------
7 files changed, 299 insertions(+), 258 deletions(-)
diff --git a/INSTALL.REPO b/INSTALL.REPO
index 490f9d7..cc1c520 100644
--- a/INSTALL.REPO
+++ b/INSTALL.REPO
@@ -33,7 +33,7 @@ First invoke the bootstrap script:
$ ./bootstrap
This will:
-
+
- clone the gnulib repository as a git submodule in 'gnulib', add
the needed gnulib sources files in 'lib', add the needed gnulib m4
macros in 'gnulib_m4'
@@ -46,13 +46,13 @@ This will:
-- Makefile.in
-- aclocal.m4
-- autom4te.cache/
- -- build-aux/ (that contains all the helper scripts)
+ -- build-aux/ (that contains all the helper scripts)
-- configure
-- src/include/config.hin
Note that aclocal.m4 is generated and the groff m4 macros are included
via the acinclude.m4 file.
-
+
At this point you can invoke the `configure' script (that generates
the `config.status' script; it is the `config.status' script generates
the Makefile) and call 'make' to build the groff project. You can do
@@ -139,3 +139,10 @@ groff is available in doc/automake.mom. It is currently not
automatically generated, to build it:
pdfmom automake.mom > automake.pdf
+
+##### Editor settings
+Local Variables:
+fill-column: 72
+mode: text
+End:
+# vim: set textwidth=72:
diff --git a/MANIFEST b/MANIFEST
index 53ec28d..5d7b016 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -27,7 +27,7 @@ the groff source distribution.
TODO Things planned for future groff versions.
All other files in the top directory are related to the configuration,
- compilation, and install processes.
+ compilation, and install processes.
2) The directory structure
@@ -70,7 +70,7 @@ the groff source distribution.
devhtml HTML device.
devlatin1 Text device for latin-1 (ISO 8859-1) output.
devlbp Device for Canon CAPSL laser printers.
- devlj4 Device for HP Laserjet 4, PCL 5, and compatible printers.
+ devlj4 Device for HP LaserJet 4/PCL 5 and compatible printers.
devps PostScript device.
devpdf PDF device.
devutf8 Text device for Unicode output.
@@ -118,7 +118,7 @@ the groff source distribution.
troff Main roff formatter program.
./src/utils Utility programs around groff.
- addftinfo Add information to old troff font files for use with groff.
+ addftinfo Add font metrics to troff fonts for use with groff.
afmtodit Create font description files for the PostScript device.
hpftodit Create font description files for the LJ4 device.
indxbib Make inverted index for bibliographic databases.
@@ -149,7 +149,7 @@ The groff documentation is scattered upon several places.
Man-pages have source files ending in `.man'. Running `make' processes
the files and uses `.n' as the new file extension. In both cases it is
-difficult to quickly decide into which section the man-page shall go.
+difficult to quickly decide into which section the man-page shall go.
Here is a shell command (to be called from the top directory of the
groff source tree) that finds all man-pages and writes the section
number after each file name:
@@ -163,10 +163,10 @@ number after each file name:
4) The roff parser
-The parsing of the roff language is done by troff. The input is converted
-to tokens in `src/roff/troff/input.cpp' and transformed into `nodes' by
-`src/roff/troff/env.cpp' and `src/roff/troff/node.cpp'. From these, the
-intermediate output is generated (also in `node.cpp').
+The parsing of the roff language is done by troff. The input is
+converted to tokens in `src/roff/troff/input.cpp' and transformed into
+`nodes' by `src/roff/troff/env.cpp' and `src/roff/troff/node.cpp'. From
+these, the intermediate output is generated (also in `node.cpp').
5) Postprocessing
@@ -177,5 +177,7 @@ The parser for the intermediate output and the
postprocessing is in
##### Editor settings
Local Variables:
+fill-column: 72
mode: text
End:
+vim: set textwidth=72:
diff --git a/MORE.STUFF b/MORE.STUFF
index 1811977..d861cc9 100644
--- a/MORE.STUFF
+++ b/MORE.STUFF
@@ -38,15 +38,16 @@ from
ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2gnu/gro*b.zip
-and its mirrors; for installation details please read `arch/djgpp/README'.
-This port also runs on Windows 32 systems, except Windows 2000.
+and its mirrors; for installation details please read
+`arch/djgpp/README'. This port also runs on Windows 32 systems, except
+Windows 2000.
grap
----
An implementation of Kernighan & Bentley's grap language for typesetting
-graphs. Written by Ted Faber <address@hidden>. The actual version
+graphs. Written by Ted Faber <address@hidden>. The current version
can be found at
http://www.lunabase.org/~faber/Vault/software/grap/
@@ -68,9 +69,9 @@ plot2dev
--------
This utility program can convert plot graphics to either pic or gremlin
-files. It has been written by Richard Murphey <address@hidden>
-and Daniel Senderowicz <address@hidden> (who has added the gremlin
-driver). The actual version can be found as
+files. It has been written by Richard Murphey
+<address@hidden> and Daniel Senderowicz <address@hidden>
+(who has added the gremlin driver). The current version can be found as
ftp://ftp.ffii.org/pub/groff/plot2dev-x.x.tar.gz
@@ -80,11 +81,11 @@ troffcvt
From the web page:
- troffcvt is a translator that turns troff input into a form that can be
- more easily processed. The troffcvt distribution comes with
- postprocessors that turn troffcvt into various destination formats such
- as HTML (Hypertext Markup Language), RTF (Rich Text Format) or plain
- text.
+ troffcvt is a translator that turns troff input into a form that can
+ be more easily processed. The troffcvt distribution comes with
+ postprocessors that turn troffcvt into various destination formats
+ such as HTML (Hypertext Markup Language), RTF (Rich Text Format) or
+ plain text.
Note that you need a lot of additional packages to compile troffcvt;
everything is available from
@@ -97,13 +98,14 @@ unroff
From the README file:
- Unroff is a Scheme-based, programmable, extensible troff translator with
- a back-end for the Hypertext Markup Language. Unroff is free software
- and is distributed both as source and as precompiled binaries.
+ Unroff is a Scheme-based, programmable, extensible troff translator
+ with a back-end for the Hypertext Markup Language. Unroff is free
+ software and is distributed both as source and as precompiled
+ binaries.
http://www.informatik.uni-bremen.de/~net/unroff/unroff.html
-You need als Elk, the Scheme based Extension Language Kit, which is
+You also need Elk, the Scheme based Extension Language Kit, which is
available from
http://www.informatik.uni-bremen.de/~net/elk
@@ -112,14 +114,14 @@ available from
deroff
------
-Deroff removes roff constructs from documents for the purpose of indexing,
-spell checking etc.
+Deroff removes roff constructs from documents for the purpose of
+indexing, spell checking etc.
Michael Haardt's <address@hidden> implementation is a little smarter
-than traditional implementations, because it knows about certain -man and
--mm macros. It is able to generate a word list for spell checking tools
-or omit headers for sentence analysis tools. It can further generate
-cpp-style #line lines.
+than traditional implementations, because it knows about certain -man
+and -mm macros. It is able to generate a word list for spell checking
+tools or omit headers for sentence analysis tools. It can further
+generate cpp-style #line lines.
http://www.moria.de/~michael/deroff/
@@ -156,15 +158,15 @@ URL:
doclifter
---------
-doclifter lifts troff macro markup to XML-Docbook. It doesn't do raw troff
-at all well (raw troff has insufficient structural information) but it
-handles manual pages, ms, mm, and me markup, producing clean lifts
-to valid XML more than 96% of the time. pic markup is translated to SVG,
-eqn markup to Presentation MathML.
+doclifter lifts troff macro markup to XML-Docbook. It doesn't do raw
+troff at all well (raw troff has insufficient structural information)
+but it handles manual pages, ms, mm, and me markup, producing clean
+lifts to valid XML more than 96% of the time. pic markup is translated
+to SVG, eqn markup to Presentation MathML.
-doclifter with the -w option behaves as a portability checker and validator,
-warning about constructs that aren't portable across *roff implementations
-and viewers.
+doclifter with the -w option behaves as a portability checker and
+validator, warning about constructs that aren't portable across *roff
+implementations and viewers.
It is available from
@@ -198,7 +200,8 @@ miscellaneous
o creating business cards
o using groff to make large format posters for presentations
-. Robert Marks's collection of useful macros and scripts is available from
+. Robert Marks's collection of useful macros and scripts is available
+ from
http://www.agsm.edu.au/~bobm/odds+ends/scripts.html
@@ -207,40 +210,41 @@ miscellaneous
o `polish': Is a sed (= the Unix stream editor) script that does many
things to ASCII text. Amongst other things, it breaks lines at new
sentences, reduces upper-case acronyms by one point size, adds
- diacriticals, changes simple quotes into smart quotes, and makes a few
- simple grammar checks. The best way to see what it does is to run it
- as a sed script file (or files) on a text file and then compare the
- output file with the original.
+ diacriticals, changes simple quotes into smart quotes, and makes a
+ few simple grammar checks. The best way to see what it does is to
+ run it as a sed script file (or files) on a text file and then
+ compare the output file with the original.
o `DropCaps' is a troff script which replaces the initial letters of
- paragraphs immediately after H1 and H2 headings with drop-capitals of
- specified point size, and automatically flows the text around the new
- drop cap.
+ paragraphs immediately after H1 and H2 headings with drop-capitals
+ of specified point size, and automatically flows the text around the
+ new drop cap.
o `AJM Header' is a set of troff macros used in production of the
- Australian Journal of Management. They use the Memorandum Macros (mm)
- of AT&T, and so should be invoked with the Unix troff -mm flag; they
- should also work with the GNU troff -mm flag.
+ Australian Journal of Management. They use the Memorandum Macros
+ (mm) of AT&T, and so should be invoked with the Unix troff -mm flag;
+ they should also work with the GNU troff -mm flag.
-. Various contributed stuff like additional font files, macro packages, and
- documentation can be found at
+. Various contributed stuff like additional font files, macro packages,
+ and documentation can be found at
http://groff.ffii.org/groff/contrib/
-. Thomas Baruchel <address@hidden> has developed Meta-tbl, a tbl
- postprocessor to manipulate table cells (like adding gray shades). The
- latest version can be found at
+. Thomas Baruchel <address@hidden> has developed Meta-tbl, a
+ tbl postprocessor to manipulate table cells (like adding gray shades).
+ The latest version can be found at
http://perso.libertysurf.fr/baruchel/
-. gpresent, written by Bob Diertens <address@hidden>. From the README
- file:
+. gpresent, written by Bob Diertens <address@hidden>. From the
+ README file:
+
+ gpresent is a package for making presentation with groff and
+ acroread. It consist of a set of macros to be used with groff and a
+ post-processor for manipulating the PostScript output of groff.
+ Without the use of the PAUSE macro, it can also be used for making
+ slides.
- gpresent is a package for making presentation with groff and acroread.
- It consist of a set of macros to be used with groff and a post-processor
- for manipulating the PostScript output of groff. Without the use of the
- PAUSE macro, it can also be used for making slides.
-
It is available from
www.science.uva.nl/~bobd/useful/gpresent/
@@ -258,5 +262,7 @@ and others can be accessed from the following web pages:
##### Editor settings
Local Variables:
+fill-column: 72
mode: text
End:
+vim: set textwidth=72:
diff --git a/PROBLEMS b/PROBLEMS
index 3a33533..9ed0df0 100644
--- a/PROBLEMS
+++ b/PROBLEMS
@@ -45,8 +45,8 @@ and pager to versions which can handle SGR.
.
. \" The following code sets a top-of-page trap to disable grotty's TTY
. \" mode. Since neither \X nor .output can be used before the first
-. \" page has started, we must use a trap. To make it work with troff's
-. \" -o option, we wait until the first printed page.
+. \" page has started, we must use a trap. To make it work with
+. \" troff's -o option, we wait until the first printed page.
.
. de sgr@dummy
. .
@@ -56,7 +56,7 @@ and pager to versions which can handle SGR.
. \" The stand-alone version. If no other trap is set, we can safely
. \" insert the truncated vertical space caused by the trap (if any).
. \" Otherwise we assume that the document's main macro package takes
-. \" care of that. As soon as the trap has been executed, it is removed.
+. \" care of that. The trap is removed once it has been executed.
. de1 no@sgr
. if \\n[.P] \{\
. if (\\n[.t] == \\n[.p]) \{\
@@ -1014,5 +1014,7 @@ systems.
##### Editor settings
Local Variables:
+fill-column: 72
mode: text
End:
+vim: set textwidth=72:
diff --git a/PROJECTS b/PROJECTS
index c2078eb..190c94b 100644
--- a/PROJECTS
+++ b/PROJECTS
@@ -24,10 +24,10 @@ Here are some things that would be useful additions to
groff:
distribution.
refer: `refer' database directory under /usr/local/share.
- There maybe create a default database `Ind' or others for
- storing books and documents for `groff' man pages.
+ There maybe create a default database `Ind' or others for
+ storing books and documents for `groff' man pages.
Write the following `groff' programs from Heirloom and
- `refer' history:
+ `refer' history:
- addbib
- roffbib
- sortbib
@@ -46,5 +46,7 @@ has gotten there first.
##### Editor settings
Local Variables:
+fill-column: 72
mode: text
End:
+vim: set filetype= textwidth=72:
diff --git a/README b/README
index c80ee3a..3db100e 100644
--- a/README
+++ b/README
@@ -76,8 +76,8 @@ only for `HTML' output (and for compilation from the
repository). If
you don't intend to produce output in either of these formats, then
these packages are unnecessary.
-Additionally, producing `PDF' output directly with the `gropdf' device needs
-a working installation of `perl'. The same is true for some other
+Additionally, producing `PDF' output directly with the `gropdf' device
+needs a working installation of `perl'. The same is true for some other
preprocessors like `chem'.
The `groff' configure script searches for the X11 headers and
@@ -122,5 +122,7 @@ GNU `groff' was written by James Clark <address@hidden>.
##### Editor settings
Local Variables:
+fill-column: 72
mode: text
End:
+vim: set textwidth=72:
diff --git a/README.MinGW b/README.MinGW
index b50cdf1..ae0eedd 100644
--- a/README.MinGW
+++ b/README.MinGW
@@ -13,194 +13,206 @@
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.
+ 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
+ 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.
+ 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.
+ 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).
+
+ 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:
+ 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.
+ 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.
+ 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.
+ 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.
+ 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
+ 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.
+ 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 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.
- 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.
+ 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.
- 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.
+ 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
+ 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.
+ 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.
+ 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.
+ 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
+ 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
+ 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:
@@ -223,84 +235,92 @@
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.
+ 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.
+ 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.
+ 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.
+ 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:
+ 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.
+ 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
+ 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.
+ 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:
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 10/10: Reflow or fix long lines in top-level docs.,
G. Branden Robinson <=