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
|
Copyright 2022-2023 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 contains advice on developing and contributing to groff. It
assumes that developers will install the 'git' revision control
system and build groff using the instructions in 'INSTALL.repo'.
Familiarize yourself with the structure of the source tree by studying
its 'MANIFEST' file at the top level.
Automake
--------
A document explaining the basics of GNU Automake and its usage in groff
is available in 'doc/automake.mom'; peruse a PDF rendering in
'doc/automake.pdf' in your build tree.
Testing
-------
Running the test suite with 'make check' after building any substantive
change to groff logic is encouraged. You should certainly do so, and
confirm that the tests pass, before submitting patches to the groff
mailing list <groff@gnu.org> or Savannah issue tracker.
If you find a defect in a test script, that can be reported via Savannah
like any other bug.
Documenting changes
-------------------
The groff project has a long history and a large, varied audience.
Changes may need to be documented in up to three places depending on
their impact.
1. Changes should of course be documented in the Git commit message.
If a change alters only comments or formatting of source code, or
makes editorial changes to documentation, and does not resolve a
Savannah ticket, you can stop at that.
2. The 'ChangeLog' file follows the format and practices documented in
the GNU Coding Standards.
https://www.gnu.org/prep/standards/html_node/Change-Logs.html
The sub-projects in the 'contrib' directory each have their own
dedicated ChangeLog files. The file specifications documented there
are relative to the sub-project, not the root of the groff source
tree. When converted to a commit message, add 'contrib/$SUBPROJECT'
to the entries.
Apart from 'contrib', groff uses a single (current) 'ChangeLog' file
for the rest of its source tree.
It is convenient to write the ChangeLog entry or entries first, then
construct a commit message from it (or them).
3. The 'NEWS' file documents changes to groff that a user, not just a
developer, would notice, not including the resolution of defects.
As a hypothetical example, correcting a rendering error in tbl(1)
such that any table with more than 20 rows no longer had the text
"FOOBAR" spuriously added to some entries would not be a 'NEWS'
item, because the appearance of such text in the first place is a
surprising deviation from tbl's ideal and historical behavior. In
contrast, adding a command-line option to tbl, or changing the
meaning of its "expand" region option such that it no longer
horizontally compresses tables as well, _would_ be 'NEWS'-worthy.
Writing Tests
-------------
Here are some portability notes on writing automated tests.
* Write to the POSIX standard for the shell and utilities where
possible. Issue 4 from 1994 is old enough that no contemporary system
has a good reason for not conforming. A copy of the standard is
available at the Open Group's web site.
https://pubs.opengroup.org/onlinepubs/009656399/toc.pdf
* The GNU coreutils "seq" command is handy but not standardized by
POSIX. Replace it with a while loop.
seq 53
n=1; while [ $n -le 53 ]; do echo $n; n=$(( n + 1 )); done
"unset" is supported by POSIX-conformant shell; use it to remove
temporary shell variables after use.
* The "od" command on macOS can put extra space characters (i.e., spaces
that don't correspond to the input) at the ends of lines when using
the "od -t c" format; GNU od does not.
So a regex like this that works with GNU od:
grep -Eqx '0000000 +A +\\b +B +\\b +C D +\\n'
might need to be weakened to the following on macOS.
grep -Eqx '0000000 +A +\\b +B +\\b +C D +\\n *'
* The "od" command on macOS does not respect the environment variable
assignment "LC_ALL=C" when processing byte values 127<x<256 decimal
and using the "character" output format (option "-t c"). An
alternative output must be used, like bytewise octal (option "-t o1").
(macOS od may be non-conforming here, despite the claim of its man
page. POSIX Issue 4 od's description says "The type specifier
character c specifies that bytes will be interpreted as characters
specified by the current setting of the LC_CTYPE locale category. ...
Other non-printable characters will be written as one three-digit
octal number for each byte in the character." (p. 538) The language
in Issue 7 (2018) appears unchanged.
https://pubs.opengroup.org/onlinepubs/9699919799/utilities/od.html )
* macOS sed requires semicolons after commands even if they are followed
immediately by a closing brace.
Rewrite
sed -n '/Foo\./{n;s/^$/FAILURE/;p}'
as follows.
sed -n '/Foo\./{n;s/^$/FAILURE/;p;}'
But see below regarding the opening braces.
* POSIX doesn't say that sed has to accept semicolons as command
separators after label (':') and branch ('t') commands, or after brace
commands, so macOS sed doesn't. GNU sed does.
So rewrite tidy, compact sed scripts like this:
sed -n '/Foo\./{n;s/^$/FAILURE/;tA;s/.*/SUCCESS/;:A;p}'
as this more cumbersome alternative.
sed -n \
-e '/Foo\./{n;s/^$/FAILURE/;tA;' \
-e 's/.*/SUCCESS/;:A;' \
-e 'p;}')
But see below regarding the opening braces.
Similarly, a brace sequence like that in this partial sed script:
/f1/p}}}}}}
must be rewritten as follows (or with '-e' expressions).
/f1/p;}
}
}
}
}
}
* macOS and GNU sed don't require newlines (or '-e' expression endings)
after _opening_ braces, but Solaris 11 sed does.
So the sed script
/i/{N;/Table of Contents/{N;/Foo[. ][. ]*1/p;};}
must be rewritten as follows (or with '-e' expressions).
/i/{
N;/Table of Contents/{
N;/Foo[. ][. ]*1/p;
};
}
|
