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