contrib/groff/README

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