MANIFEST

   1     Copyright 2001-2014 Free Software Foundation, Inc.
   2
   3     Copying and distribution of this file, with or without modification,
   4     are permitted in any medium without royalty provided the copyright
   5     notice and this notice are preserved.
   6
   7 This file gives an overview of the directories and the main files of
   8 the groff source distribution.
   9
  10
  11 1) The top directory.
  12
  13   BUG-REPORT    A template for bug-reports.
  14   ChangeLog     Log of the changes in the different groff versions.
  15   COPYING       The GNU General Public License (GPL).
  16   FDL           The Free Documentation License (FDL).
  17   INSTALL       Information on compiling and installing groff.
  18   INSTALL.gen   Generic information on configuration and compiling.
  19   LICENSES      Licensing information.
  20   MANIFEST      The file you are reading.
  21   MORE.STUFF    Useful stuff in other packages.
  22   NEWS          Recent user-visible changes in groff.
  23   PROBLEMS      Tips to handle known critical situations.
  24   PROJECTS      Long-term additions to groff.
  25   README        Availability and contact information for groff.
  26   README.MinGW  Build information for MinGW.
  27   TODO          Things planned for future groff versions.
  28
  29   All other files in the top directory are related to the configuration,
  30   compilation, and install processes.
  31
  32
  33 2) The directory structure
  34
  35 ./arch          Data that is special for different architectures.
  36   djgpp         Data special for the 32-bit DOS compiler djgpp.
  37   misc          Data needed for various platforms.
  38
  39 ./contrib       Part of groff, but maintained by other people.
  40   chem          A preprocessor (for pic) to produce chemical structure
  41                 diagrams.
  42   eqn2graph     Convert equations created with EQN into different
  43                 graphical formats.
  44   gdiffmk       An improved implementation of the diffmk command to mark
  45                 differences between groff/nroff/troff files.
  46   glilypond     A preprocessor that handles `lilypond' parts in a `roff'
  47                 file.
  48   gperl         A preprocessor that handles `perl' parts in a `roff'
  49                 file.
  50   gpinyin       A preprocessor providing simpler Pinyin input.
  51   grap2graph    Convert grap diagraps into different graphical formats.
  52   groffer       A wrapper to conveniently view roff files.
  53   hdtbl         A sophisticated table macro package.
  54   mm            The groff mm macro package.
  55   mom           The groff mom macro package.
  56   pdfmark       A package to add PDF marks to groff documents, together
  57                 with a shell script (pdfroff) for easy creation of PDF
  58                 documents.
  59   pic2graph     Convert PIC diagrams into different graphical formats.
  60
  61 ./doc           Manuals and tutorials to groff aspects.
  62
  63 ./font          Device information and fonts.
  64   devX100       100dpi device for X Window System.
  65   devX100-12    100dpi device with narrower font (for 12pt base font).
  66   devX75        75dpi device for X Window System.
  67   devX75-12     75dpi device with narrower font (for 12pt base font).
  68   devascii      Text device for ASCII output.
  69   devcp1047     EBCDIC device.
  70   devdvi        TeX DVI device.
  71   devhtml       HTML device.
  72   devlatin1     Text device for latin-1 (ISO 8859-1) output.
  73   devlbp        Device for Canon CAPSL laser printers.
  74   devlj4        Device for HP Laserjet 4, PCL 5, and compatible printers.
  75   devps         PostScript device.
  76   devpdf        PDF device.
  77   devutf8       Text device for Unicode output.
  78   util          Utility programs.
  79
  80 ./m4            M4 macro files used creating the configure script.
  81
  82 ./man           Some groff manual pages of more general character.
  83
  84 ./src           Everything written in programming languages.
  85
  86 ./src/devices   The postprocessors.
  87   grodvi        TeX DVI output.
  88   grohtml       HTML output.
  89   grolbp        Canon printers.
  90   grolj4        HP Laserjet 4, PCL 5, and compatible printers.
  91   grops         PostScript output.
  92   gropdf        PDF output.
  93   grotty        Text output.
  94   xditview      A groff (pre)viewer for the X Window system.
  95
  96 ./src/include   The *.h C/C++ include files.
  97
  98 ./src/libs      C++ code common to several parts of the groff sources.
  99   gnulib        Auxiliary functions copied from the `gnulib' repository.
 100   libbib        Library of bibliographic functions.
 101   libdriver     Parser for intermediate output and postprocessor code.
 102   libgroff      Library for general support functions used everywhere.
 103   libxutil      Utility functions for xditview and xtotroff.
 104   snprintf      An implementation of snprintf() and friends.
 105
 106 ./src/preproc   Preprocessors.
 107   eqn           Mathematical formulae.
 108   grn           Gremlin pictures.
 109   html          The preprocessor part of grohtml.
 110   pic           Diagram drawer.
 111   preconv       Input encoding conversion.
 112   refer         Bibliographic references.
 113   soelim        File inclusion using tmac path.
 114   tbl           Tables.
 115
 116 ./src/roff      Front-end programs.
 117   groff         Wrapper around troff.  This is the main user program.
 118   grog          Guess groff command line options.
 119   nroff         Emulate classical nroff text formatter.
 120   troff         Main roff formatter program.
 121
 122 ./src/utils     Utility programs around groff.
 123   addftinfo     Add information to old troff font files for use with groff.
 124   afmtodit      Create font description files for the PostScript device.
 125   hpftodit      Create font description files for the LJ4 device.
 126   indxbib       Make inverted index for bibliographic databases.
 127   lkbib         Search bibliographic databases.
 128   lookbib       Interactively search bibliographic databases.
 129   pfbtops       Translate a PostScript font in PFB format to PFA.
 130   tfmtodit      Create font description files for TeX DVI device.
 131   xtotroff      Create font description files for xditview.
 132
 133 ./tmac          Macro files.
 134
 135
 136 3) Documentation
 137
 138 The groff documentation is scattered upon several places.
 139
 140 - The main directory contains documents related to the groff source.
 141   The README file contains the information needed to get the groff
 142   package, report bugs, and contact the developers.
 143
 144 - The man-page of each program (section 1) is kept in the source
 145   directory of the program.
 146
 147 - The man-pages for the other sections are found in `src/man'.
 148
 149 - Documentation in other formats are located in the `doc' directory,
 150   including the groff info file, tutorials, and manuals.
 151
 152 Man-pages have source files ending in `.man'.  Running `make' processes
 153 the files and uses `.n' as the new file extension.  In both cases it is
 154 difficult to quickly decide into which section the man-page shall go.
 155 Here is a shell command (to be called from the top directory of the
 156 groff source tree) that finds all man-pages and writes the section
 157 number after each file name:
 158
 159   find -type f \
 160   | grep '[.]man$' \
 161   | sort \
 162   | xargs grep -e '^[.]TH ' \
 163   | sed -e 's/^\(.\+\): *\.TH.*@MAN\(.*\)EXT@.*$/\1 \2/'
 164
 165
 166 4) The roff parser
 167
 168 The parsing of the roff language is done by troff.  The input is converted
 169 to tokens in `src/roff/troff/input.cpp' and transformed into `nodes' by
 170 `src/roff/troff/env.cpp' and `src/roff/troff/node.cpp'.  From these, the
 171 intermediate output is generated (also in `node.cpp').
 172
 173
 174 5) Postprocessing
 175
 176 The parser for the intermediate output and the postprocessing is in
 177 `src/libs/libdriver/input.cpp'.  This is used by all postprocessors.
 178
 179
 180 ##### Emacs settings
 181 Local Variables:
 182 mode: text
 183 End: