/contrib/groff/README

  1This is the GNU `groff' document formatting system.  The version
  2number is given in the file VERSION.
  3
  4Included in this release are implementations of `troff', `pic', `eqn',
  5`tbl', `grn', `refer', `-man', `-mdoc', `-mom', and `-ms' macros, and
  6drivers for `PostScript', `TeX dvi' format, `HP LaserJet 4' printers,
  7`Canon CAPSL' printers, `HTML' format (beta status), and
  8typewriter-like devices.  Also included is a modified version of the
  9Berkeley `-me' macros, the enhanced version `gxditview' of the X11
 10`xditview' previewer, and an implementation of the `-mm' macros
 11contributed by Joergen Haegg (jh@axis.se).
 12
 13See the file `INSTALL' for installation instructions.  You will
 14require a C++ compiler.
 15
 16The file `NEWS' describes recent user-visible changes to `groff'.
 17
 18`groff' is free software.  See the file `COPYING' for copying
 19permission.
 20
 21The file `PROBLEMS' describes various problems that have been
 22encountered in compiling, installing, and running `groff'.
 23
 24The most recent released version of `groff' is always available by
 25anonymous ftp from `ftp.gnu.org' in the directory `gnu/groff'.
 26
 27The current development version of `groff' is available from a `CVS'
 28repository.  You can access it by first selecting a parent directory
 29in which to create a working copy (call it, say, `~/cvswork'), and
 30then executing the commands
 31
 32  cd ~/cvswork
 33  CVS_RSH=ssh; export CVS_RSH
 34  cvs -d:ext:anoncvs@savannah.gnu.org/cvsroot/groff -z5 co groff
 35
 36(Note that you need an `ssh' client for security reasons.)
 37
 38This will create a subdirectory, `~/cvswork/groff', with a "checked
 39out" copy of the `CVS' repository.  An update of this working copy may
 40be achieved, at any later time by invoking the commands
 41
 42  cd ~/cvswork/groff
 43  CVS_RSH=ssh cvs -z5 update -dP
 44
 45Please read the `CVS' info pages for further details.
 46
 47Finally, it is possible to access the `CVS' with a web browser by
 48pointing it to
 49
 50  http://savannah.gnu.org/cvs/?group=groff
 51
 52Alternatively, you can download snapshots (which are updated twice a day).
 53The complete `groff' source as a single file is available at
 54
 55  http://groff.ffii.org/groff/devel/groff-current.tar.gz
 56
 57A diff file relative to `groff-<version>', the latest official `groff'
 58release is available at
 59
 60  http://groff.ffii.org/groff/devel/groff-<version>-current.diff.gz
 61
 62Assuming that `groff-<version>.tar.gz' and
 63`groff-<version>-current.diff.gz' are in the same directory, do the
 64following to apply the diff file:
 65
 66  tar xzvf groff-<version>.tar.gz
 67  cd groff-<version>
 68  gunzip -c ../groff-<version>-current.diff.gz | patch -p1
 69
 70Depending on your requirements, you may need at least some of the
 71following tools to build `groff' directly from its source:
 72
 73  ghostscript
 74  the psutils package
 75  the netpbm package
 76  texinfo 4.8
 77  bison >= 1.875b or byacc
 78
 79Note that `texinfo' and `bison' or `byacc' are required only for
 80building from `CVS' sources (either a checked out working copy, or a
 81daily snapshot).  They are not required for building from a stable
 82release tarball.  Also note that the version numbers stated are the
 83minimum supported.  No version of `texinfo' < 4.8 will work, and the
 84original release of `bison' 1.875 is known not to work; you *may* find
 85that `bison' releases < 1.875 will work, but in case of difficulty,
 86please update to a later version *before* posting a bug report.
 87
 88For *all* sources, you need ghostscript for creation of either `PDF' or
 89`HTML' output; the `netpbm' and `psutils' packages are required only for
 90`HTML' output.  If you don't intend to produce output in either of these
 91formats, then these packages are unnecessary.
 92
 93In Linux Debian, the installation of `texinfo' is dangerous.  For it
 94creates a file `install-info' that will block the system installation.
 95So the created `/usr/local/bin/install-info' must be renamed.
 96
 97The `groff' configure script searches for the X11 headers and
 98libraries `Xaw' and `Xmu'.  So the corresponding developer packages of
 99your system must be installed, otherwise `groff' does not install
100`gxditview' and the `-TX*' devices.  In Debian, the developer packages
101are `libxaw7-dev' and `libxmu-dev'.
102
103Please report bugs using the form in the file `BUG-REPORT'; the idea of
104this is to make sure that FSF has all the information it needs to fix
105the bug.  At the very least, read the `BUG-REPORT' form and make sure
106that you supply all the information that it asks for.  Even if you are
107not sure that something is a bug, report it using `BUG-REPORT': this will
108enable us to determine whether it really is a bug or not.
109
110Three mailing lists are available:
111
112  bug-groff@gnu.org          for reporting bugs
113  groff@gnu.org              for general discussion of groff
114  groff-commit@gnu.org       a read-only list showing commitments
115                             to the CVS repository
116
117You can post mails directly to the `bug-groff' list, without subscribing;
118to post mails to the `groff' list you must subscribe to it.
119
120To subscribe, send a mail to <list>-request@<domain> (example:
121groff-request@gnu.org for the `groff' list) with the word `subscribe'
122in either the subject or body of the email (don't include the quotes).
123Alternatively, you may subscribe by visiting the web pages at
124
125  http://lists.gnu.org/mailman/listinfo/bug-groff
126  http://lists.gnu.org/mailman/listinfo/groff
127  http://lists.gnu.org/mailman/listinfo/groff-commit
128
129Each of these web pages also provides a link to a browseable archive of
130postings to the corresponding mailing list.
131
132GNU `groff' was written by James Clark <jjc@jclark.com>.  It is now
133maintained by Ted Harding <ted.harding@nessie.mcc.ac.uk> and Werner
134Lemberg <wl@gnu.org>.