MANIFEST

   1     Copyright 2001-2022 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 summarizes the structure of the groff source distribution.
   8
   9
  10 1) Top-level directory contents
  11
  12   BUG-REPORT    A template for bug reports.
  13   ChangeLog     Log of changes since last groff minor version release.
  14   ChangeLog.*   Logs of changes in past groff versions.
  15   COPYING       The GNU General Public License (GPL).
  16   FDL           The GNU Free Documentation License (FDL).
  17   FOR-RELEASE   Release procedures for groff maintainer(s) to follow.
  18   HACKING       Advice for contributors to groff.
  19   INSTALL       Generic information on configuration and compiling.
  20   INSTALL.extra How to install groff from a distribution archive.
  21   INSTALL.REPO  How to install groff from a Git repository checkout.
  22   LICENSES      Copyright and licensing information.
  23   MANIFEST      The file you are reading.
  24   MORE.STUFF    Useful stuff in other packages.
  25   NEWS          Log of feature changes in groff.
  26   PROBLEMS      Tips to handle known situations of concern.
  27   PROJECTS      Long-term additions to groff.
  28   README        Introduction to and contact information for groff.
  29   README.MinGW  Build information for MinGW.
  30   TODO          Things planned for future groff versions.
  31
  32   All other files in the top-level directory are related to
  33   configuration, compilation, and installation procedures.
  34
  35
  36 2) Directory structure
  37
  38 ./arch          Resources to facilitate building on non-POSIX systems.
  39   djgpp         Resources for the 32-bit MS-DOS compiler djgpp.
  40   mingw         Resources for the MinGW environment.
  41   misc          Resources for various other platforms.
  42
  43 ./contrib       Resources provided with groff, but maintained by others.
  44   chem          Embed chemical structure diagrams in groff documents.
  45   eqn2graph     Convert eqn(1) equations into graphical images.
  46   gdiffmk       An improved implementation of the diffmk command to mark
  47                 differences between groff/nroff/troff files.
  48   glilypond     Embed LilyPond sheet music in groff documents.
  49   gperl         Populate groff registers and strings using perl(1).
  50   gpinyin       Use Hanyu Pinyin input to compose groff documents.
  51   grap2graph    Convert grap(1) diagrams into graphical images.
  52   hdtbl         A sophisticated table macro package.
  53   mm            The groff memorandum macro package.
  54   mom           Peter Schaffter's "mom", a friendly groff macro package.
  55   pdfmark       Add PDF marks to groff documents; includes "pdfroff",
  56                 which eases creation of PDF documents.
  57   pic2graph     Convert pic(1) diagrams into graphical images.
  58   rfc1345       Use RFC 1345 mnemonics as groff special characters.
  59   sboxes        Use bordered, shaded background boxes with ms and PDF.
  60
  61 ./doc           Manuals for various components of groff.
  62
  63 ./font          Device and font description files.
  64   devX100       100dpi X11 device (10 point base type size).
  65   devX100-12    100dpi X11 device (12 point base type size).
  66   devX75        75dpi X11 device (10 point base type size).
  67   devX75-12     75dpi X11 device (12 point base type size).
  68   devascii      Terminal device with ASCII (ISO 646) encoding.
  69   devcp1047     Terminal device with EBCDIC (code page 1047) encoding.
  70   devdvi        TeX DVI device.
  71   devhtml       HTML device.
  72   devlatin1     Terminal device with ISO Latin-1 (8859-1) encoding.
  73   devlbp        Canon CaPSL laser printers.
  74   devlj4        HP LaserJet 4/PCL 5 and compatible printers.
  75   devps         PostScript device.
  76   devpdf        PDF device.
  77   devutf8       Terminal device with UTF-8 encoding.
  78   scripts       Scripts used in generation of device/font descriptions.
  79   util          Tools to aid groff developers with new device support.
  80
  81 ./m4            M4 macro files used to create the "configure" script.
  82
  83 ./man           groff manual pages of general applicability.
  84
  85 ./src           groff programs and libraries.
  86
  87 ./src/devices   Output drivers for devices and file formats.
  88   grodvi        TeX DVI.
  89   grohtml       HTML.
  90   grolbp        Canon CaPSL laser printers.
  91   grolj4        HP LaserJet 4/PCL 5 and compatible printers.
  92   grops         PostScript.
  93   gropdf        PDF.
  94   grotty        Terminal output.
  95   xditview      A troff output (pre)viewer for the X Window System.
  96
  97 ./src/include   C/C++ header files.
  98
  99 ./src/libs      C++ code shared among several groff components.
 100   libbib        Manage bibliographic database.
 101   libdriver     Parse troff output; also output utility functions.
 102   libgroff      General support functions used everywhere.
 103   libxutil      Utility functions for gxditview and xtotroff.
 104
 105 ./src/preproc   Preprocessors.
 106   eqn           Typeset mathematical formulae.
 107   grn           Draw Gremlin pictures.
 108   html          Prepare tbl and eqn input for grohtml.
 109   pic           Draw diagrams.
 110   preconv       Convert document input encoding for input to troff.
 111   refer         Generate bibliographic references.
 112   soelim        Expose 'so' (sourced) documents to preprocessing.
 113   tbl           Lay out tables.
 114
 115 ./src/roff      Programs that run the formatter.
 116   groff         troff wrapper.  This is the main user program.
 117   nroff         groff wrapper convenient for terminal users.
 118   troff         Formatter.
 119
 120 ./src/utils     Utility programs relevant to groff.
 121   addftinfo     Supplement AT&T troff font descriptions with metrics
 122                 groff requires.
 123   afmtodit      Create font description files for the PostScript device.
 124   grog          Guess groff command-line options required by a document.
 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 Type 1 font in PFB format to PFA.
 130   tfmtodit      Create font description files for TeX DVI device.
 131   xtotroff      Create font description files for gxditview.
 132
 133 ./tmac          Macro files.
 134   mdoc          Modules for the mdoc package.
 135
 136 Various directories contain a "tests" subdirectory.  These are automated
 137 tests performed when groff's Makefile is run with the "check" target.
 138
 139
 140 3) Documentation
 141
 142 groff documentation is spread throughout the tree; where possible, it is
 143 close to the source code it describes.
 144
 145 - The top-level directory contains text files presenting groff as a
 146   software project, with its focus on organization of the code,
 147   development procedures, and project administration.
 148
 149   If you don't know where to begin, start with "README"; it contains the
 150   information you will require to obtain the groff distribution archive,
 151   report bugs, and contact the developers.
 152
 153 - A man page for each program (for section 1 of the manual) is
 154   maintained in the source directory of the program itself.
 155
 156 - Extensive man pages documenting GNU roff's input language, special
 157   character repertoire, differences from AT&T troff, device and font
 158   description file formats, macro files, and historical and conceptual
 159   background are maintained in the "man" directory.
 160
 161 - Documentation in other formats is located in the "doc" directory,
 162   including groff's Texinfo manual, and tutorial and/or reference
 163   manuals written using groff macro packages.
 164
 165 - Documentation for contributed components is kept in the relevant
 166   subdirectory of "contrib".
 167
 168
 169 4) groff language parser
 170
 171 The "troff" program in "src/roff/troff" parses the groff input language.
 172 There, "input.cpp" implements the main loop and tokenizes input.  Input
 173 tokens are transformed into nodes (a GNU troff internal data structure)
 174 by "env.cpp" and "node.cpp".  Routines in the latter file generate the
 175 page description language from lists of nodes.
 176
 177
 178 5) page description language parser
 179
 180 The parser for the page description language produced by troff is
 181 implemented in "src/libs/libdriver/input.cpp".  This is used by all
 182 groff output drivers written in C++.  ("gropdf", written in Perl,
 183 performs its own parsing.)
 184
 185
 186 ##### Editor settings
 187 Local Variables:
 188 fill-column: 72
 189 mode: text
 190 End:
 191 vim: set expandtab textwidth=72: