GSP/Panel
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Added Cyg-Win

Browse source
This commit is contained in:
Frank Harris 2026-06-06 18:46:40 -04:00
parent 82cbc206eb
commit 413c315806
10586 changed files with 3806249 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

574
Agent-Windows/OGP64/usr/share/doc/groff/HACKING Normal file
View file

@ -0,0 +1,574 @@
Copyright 2022-2026 G. Branden Robinson
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.
Implementation languages
------------------------
Beyond what is said under "Dependencies" in 'INSTALL.extra',
contributors should note that due to the age of the code base, much of
the C++ dialect employed by groff components, while standard, is older
than C++98--closer to Annotated Reference Manual C++ (Ellis, Stroustrup;
Addison-Wesley, 1990). groff implements its own string class and the
Standard Template Library is little used. A modest effort is underway
to update the code to more idiomatic C++98. Where a C++11 feature
promises to be advantageous, it may be annotated in a code comment.
Portability notes:
* `std::size` is not available in C++98. Use `countof()`, which is
provided by the gnulib module `stdcountof-h` and expected to be
standardized in C2y, instead of `sizeof` and dividing.
* C++98 lacks value initialization for array types.
https://cplusplus.github.io/CWG/issues/178.html
Use `memset()` after allocating an array from the stack or the heap
unless you are sure that every path through subsequent logic
determines the contents of every array element.
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.
Tips:
* Don't define macros, including those ending in `_srcdir` or
`_builddir`, unless Automake itself demands them or you need to
interpolate them elsewhere in the *.am file.
* If you need to define a `_builddir` macro, give it a plain literal
value; do _not_ lead it with an interpolation of `top_builddir` or
anything else. Failure to heed this advice leads to out-of-tree build
failures with BSD Make.
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 or a test script, 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.
Incorporating changes by others
-------------------------------
When committing a change largely authored by someone else, and that
person has not elected to remain anonymous, we want to credit their work
appropriately.
1. Report their name and email address in the ChangeLog entry alongside
the date they submitted the change.
2. Use the `--author` and `--date` command-line options to `git commit`
to record the same information.
3. If the contributor also proposed a ChangeLog entry or commit
message, editorially revise it if necessary to fit our conventions.
If you feel that substanial additional commentary is warranted, add
it between square brackets and mark it with your initials. For
example, "[I added a parallel change to foobar(). -- JRH]".
4. In a separate (and likely immediately subsequent) commit,
acknowledge the contributor in the "ANNOUNCE" file if they're not
already listed there.
Updating copyright notices
--------------------------
Background
..........
* A lay person's views and opinion follow; they are not legal advice.
If you require legal advice, consult a licensed attorney competent in
copyright law in your jurisdiction. The following discussion attempts
to establish a coherent basis from which to make consistent decisions
about the inclusion and maintenance of copyright notices in groff.
* Copyright notices in groff generally look as follows...
Copyright YYYY-ZZZZ Umbrella Organization, Inc.
QQQQ J. Random Hacker
WWWW-XXXX S. O. Gui
...where the repeated sequences of a capital letter are replaced by
(an) applicable Gregorian calendar year(s).
An exception is made for copyright notices applicable to "foreign"
code and files incorporated from other projects, which generally
retain the forms extant at their time of incorporation. Where these
files are supplemented with contributions by groff developers and meet
the originality and significance criteria discussed below, we add
copyright notices in the form shown above.
In files not encoded in UTF-8, we avoid use of the copyright sign
(Unicode U+00A9). See below regarding "ersatz" copyright symbols.
* The purpose of a copyright notice is to record legal facts about a
work. It is not to express acknowledgement of, gratitude about, or
appreciation for the efforts of contributors, past or present, which
is better done in documentation--and with explicit expression!
* Copyright protection is a legal monopoly of limited duration and an
economic policy scheme for the purpose of promoting, as the U.S.
Constitution puts it, "science and the useful arts". Over decades,
the scope of copyright (the nature of the works to which it can be
applied), the ease of its attachment, and the measure of its limited
duration, have all increased dramatically. (An economist might
observe that this is a progression characteristic of rentierism.)
* In U.S. statutory law, copyright protection extends to portions of a
work that constitute "original expression" (see below) and that are
"fixed in a tangible medium" (such as paper or a non-volatile memory
device) at some point in time. The copyright notice records the year
corresponding to that point in time. A notice should declare a list
of one or more such years reflecting the initial "fixation" and
further alterations to the work constituting original expression in
later years. An exception can be made for portions of the work whose
copyright durations have elapsed. But these durations are so lengthy
that, in the United States as of 2025, no work of computer software or
documentation has ever yet even _partially_ aged into the public
domain. (Some has been placed into the public domain deliberately,
and some never enjoyed copyright protection at all.)
Historically--decades ago, and before digital computing was commonly
undertaken in the home or even in small- to medium-scale business--a
copyright notice also asserted a legal claim. (It remains useful to
establish a basis for recovery of damages in U.S. civil copyright
infringement cases.) But copyright notices have not constituted
"assertions" of copyright for factual or criminal infringement
purposes (in the United States) for around 50 years as of 2026.
Removing a party's name from a copyright notice (as might happen
consequent to code deletion or wholesale rewriting of documentation)
is not a challenge or insult to an affected person or organization,
and does not deprive them of legitimate legal rights, when and where
doing so _makes the copyright notice more accurate_.
Software developers relying upon copyright protection are responsible
for maintaining accurate copyright notices. In the U.S., making a
claim of copyright fraudulently can be a criminal offense (17 USC
§506(c)). Making an overbroad claim of copyright, by naming parties
who don't legitimately have copyright in a work or by deliberately
overstating the recency of their efforts is, in the lay opinion of the
maintainer as of this writing, neglectful of responsibility.
* For a deeper treatment of the subject from a domain expert, please see
Jessica D. Litman's monograph, _Digital Copyright_, freely available
on the Web at <https://repository.law.umich.edu/books/1/>.
What To Do
..........
* Update the overall copyright notice for groff as a work of software
at release time. See the 'FOR-RELEASE' file in the Git repository.
* Update a _file_'s copyright notice in a year when committing a change
to it that is "original expression" and would thus merit copyright
protection. This is a subjective and arguable matter, so it's not
necessarily offensive to apply an expansive interpretation, but
"bumping" the copyright notice when _no_ change has been made, or when
the alterations are trivial by another standard (code style changes
that don't require regression testing; editorial changes to text that
are _invisible_ to the lay reader without technological assistance--
like trailing tab/space removal) abuses the principle, as noted above.
The GNU Maintainers' Guide's threshold for a "legally significant"
change is 15 lines.
"A change of just a few lines (less than 15 or so) is not legally
significant for copyright."
https://www.gnu.org/prep/maintain/html_node/Legally-Significant.html
Conversely, >= 15 lines would be. This guidance is vague, as it makes
no claim of an expected, typical, or mean line length, and different
file formats and stylistic practices in code and documentation
production exhibit different typical line lengths. Bearing in mind
that the 15 lines must constitute "original expression", and lacking
further guidance from that manual, in groff we ignore the issue of
line length and interpret "15 lines" as requiring a _net increase_ in
a file's line count of at least that magnitude, as calculated by
taking the output of "git diff --stat" on the file (or "git log
--stat" on a relevant commit to it) and subtracting lines removed from
lines added, a procedure that can result in a nonpositive number.
This rule has the advantage that it tends to exclude voluminous but
robotic changes, as one might make with "sed -i", which seldom
constitute "original expression".
Where a change produces a net increase of 15 lines or more but _still_
seems robotic or unoriginal, consider (1) applying the annotation
"Copyright-paperwork-exempt: yes" to the Git commit log message, and
(2) recording, in the corresponding commit log message, the robotic
procedure that produced the change.
If a change contains what would otherwise be legally significant
original expression that gets "swamped" by removal of other material--
falsely appearing to fall below the significance threshold using the
simple computation above--consider splitting the commit into two: one
that removes material and another that adds the new material.
Regarding "original expression", see section 308 of
<https://www.copyright.gov/comp3/chap300/
ch300-copyrightable-authorship.pdf>.
* If you forget the foregoing step, or contributions to a file seem to
accrete original status and legal significance over time or a series
of commits, it's fine to later update the notice to include the
relevant (hopefully current) year in a stand-alone commit. Use "git
log --oneline" on a file to gather commit IDs and change summaries
that justify the update and put them in the commit message so that
other people understand the basis of your claim.
* Similarly, it is also virtuous to correct existing copyright notices
that apply overbroad principles of update as described above. Doing
so demands careful study of a file's history, and one must be mindful
of file renames and relocations of content, neither of which have any
impact on copyright. When revising a copyright notice thus, document
your research procedure (for example, by recording in the commit log
the exact Git commands you used) so that anyone can reproduce it.
* It's okay to simply report a range of years in the copyright notice
instead of a comma-separated list. As far as the current maintainer
knows, there is no hard rule that such ranges are interpreted
exhaustively, and unless someone has a chronological record of changes
to the file--which is present in groff's Git commit repository going
back to about 2014, but absent from distribution archives--a broken
sequence of copyright coverage years makes little difference.
Prior to 2014, groff's Git history is coarser, being reconstructed
from CVS, and prior to February 2000, each commit is a snapshot of a
distribution archive.
https://lists.gnu.org/archive/html/groff/2013-12/msg00033.html
https://lists.gnu.org/archive/html/groff/2013-12/msg00005.html
* When adding a new file to groff, include a copyright notice only if it
is "legally significant" per the 15-line threshold. But even a new
file of legally significant size does not merit a copyright notice if
it does not constitute original, non-robotic expression as discussed
above. In that case, include "Copyright-paperwork-exempt: yes" in the
Git commit log message. To summarize, the same rules apply to new
files as to changes to existing ones.
* In UTF-8-encoded files, it is fine to use a true copyright sign
(Unicode U+00A9). Place it in the notice between the word "Copyright"
and the year (or year range) with one space on each side of it.
In other files, avoid use of the ersatz copyright sign "(C)".
Software developers have long labored under the no-longer-correct
misconception that omitting a copyright symbol from one's notice was a
fatal defect that effectively placed the work in the public domain.
That stopped being true as of 1 March 1989. Further, prior to
guidance issued by the U.S. Copyright Office in the decades since, the
use of "(C)" as a substitute for a copyright sign _may not have
sufficed_ to prevent the copyright notice from being regarded as
defective. The Copyright Office, then and now, prefers the
abbreviation "copr." when a true copyright sign is typographically
unavailable. Nowadays, its advice is that "c" (note lowercase) is an
"acceptable variant", that _may_ retain the efficacy of the copyright
notice. The word "copyright", spelled out in full, also suffices per
that resource.
See <https://www.copyright.gov/circs/circ03.pdf>.
Adding or removing components
-----------------------------
Changing the set of discrete modules that comprises groff requires
updates in multiple places.
* Update "Makefile.am" to add or remove the inclusion of the
component's "*.am" Automake file.
* Update the "MANIFEST" file.
* Update the "NEWS" file.
Adding a component in the "contrib" directory demands further change.
* Add a "COPYRIGHT" file in its directory. If that file makes reference
to a separate license text that is _not_ the GPLv3 under which all
files in groff are distributed (sometimes in conjuction with other
licenses), such as GPLv2, also include a copy of that license in the
same directory.
* Add the aforementioned "COPYRIGHT" file and any separate license
text files it mentions to the `EXTRA_DIST` macro in the component's
"*.am" file.
Writing tests
-------------
Here is some advice on writing portable automated test scripts.
* 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.
# emulate "seq 53"
n=1; while [ $n -le 53 ]; do echo $n; n=$(( n + 1 )); done; unset n
* The "wc" command on macOS can prefix the numeric count in its output
with spaces, which can be undesirable when storing that output to
variable that is later expanded within double quotes in the shell.
Here is a workaround.
res=$(whatever | wc -l)
res=$(( res + 0 )) || exit 99
If for some reason we get unacceptable non-integer garbage from "wc",
we exit the test script with the code reserved for "hard errors".
Shell arithmetic is unfortunately one of the many POSIX shell features
that Solaris 10's /bin/sh does not implement; see the "PROBLEMS" file.
* 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 "-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 to work on macOS.
grep -Eqx '0000000 +A +\\b +B +\\b +C D +\\n *'
* The "od" command on macOS, NetBSD, and OpenBSD puts extra space
characters between the hexadecimal values when using the "-t x1"
format; GNU od does not.
So a regex like this that works with GNU od:
grep -q '81 30 55 81 30 56 81 6c e2'
might need to be weakened to the following to work on macOS/[NO]*BSD.
grep -q '81 *30 *55 *81 *30 *56 *81 *6c *e2'
* The "od" command on FreeBSD 14.0 and 15.0, NetBSD 10.0, and OpenBSD
7.8 (at least) pad out the line length with spaces to 73 columns; GNU
od does not.
So a regex like this that works with GNU od:
grep -q '0000040 .* *e2 *94 *a4 *0.$'
likely must be weakened to the following.
grep -q '0000040 .* *e2 *94 *a4 *0. *$'
* 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 )
* Prior to POSIX.1-2024, the meaning of the sequence `\]` in a basic or
extended regular expression is undefined. Spell it as `]` instead.
* 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 test ('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 as shown 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;
};
}
* Solaris 10's /usr/bin/cksum output is non-conforming with XPG4. It
uses tabs as field delimiters instead of spaces.
* Solaris 10's /usr/bin/grep is non-conforming with XPG4; it lacks
support for the `-E`, `-F`, `-q`, and `-x` options.
* Solaris 10's /bin/sh is non-conforming with XPG4; it does not support
POSIX parameter expansion syntax.
* Solaris 10's /usr/bin/tr exits with an error if you try to use a POSIX
character class (such as "[:cntrl:]") in any locale but "C".
* Solaris 10's /usr/xpg4/bin/sh is non-conforming with XPG4.
(Good job, guys!)
Its "unset" builtin is buggy. (The /usr/bin/sh in Solaris 11 does not
have this problem.)
We sometimes must use the "unset" shell builtin command to prevent
environment variables from confounding test results.
POSIX says "[u]nsetting a variable ... that was not previously set is
not considered an error and will not cause the shell to abort."
Nevertheless this builtin returns an error exit status in this
circumstance.
$ /usr/xpg4/bin/sh -c 'unset _NON_EXISTENT_XYZ; echo $?'
1
You may want to check for this misbehavior and skip the test if
running under an afflicted shell.
if ! unset VARIABLE_OF_INTEREST
then
echo "unable to clear environment; skipping" >&2
exit 77 # skip
fi
Updating gnulib
---------------
Here's how to update the submodule, using that project's "stable-202501"
branch as an example. Run the commands below from the root directory
of your working copy.
$ cd gnulib
$ git pull
$ git checkout -b stable-202501 --track origin/stable-202501
$ cd ..
$ git add gnulib
$ editor ChangeLog # log it
$ git add ChangeLog
$ git commit
It's likely a good idea to update the "bootstrap" script at the same
time (not necessarily in the same commit, however).
$ ./bootstrap --bootstrap-sync
$ git add bootstrap
$ editor ChangeLog # log it
$ git add ChangeLog
$ git commit
Theory of operation
-------------------
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.
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 autoindent textwidth=72: