README

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