40 Commits

Author SHA1 Message Date
G. Branden Robinson
48b8854972 HACKING: Add tips on clean *.am file composition. 2026-01-21 11:36:13 -06:00
G. Branden Robinson
45c6536764 HACKING: Add guidance re: a failure scenario. 2026-01-21 11:36:12 -06:00
G. Branden Robinson
8d698e479a HACKING: Update array counting advice. 2025-12-19 16:26:05 -06:00
G. Branden Robinson
e7e381820d HACKING: Make minor updates.
* Bump "as of this writing"-style claim.
* Recast to avoid excess use of "this" and "that".
2025-12-06 08:11:51 -06:00
G. Branden Robinson
288b810299 HACKING: Revise copyright notice.
Identify myself as the copyright holder.  I've never executed copyright
assignment paperwork with the FSF, so my "legally significant"[1]
origination of this file in 2022 can't be under the FSF's copyright.

[1] "A change of just a few lines (less than 15 or so) is not legally
significant for copyright."  Conversely, >= 15 lines would be.

https://www.gnu.org/prep/maintain/html_node/Legally-Significant.html
2025-10-29 06:35:01 -05:00
G. Branden Robinson
bf42533d6f HACKING: Clarify item.
When justifying "original work", we want not only the (abbreviated) Git
hashes, but the human-intelligible change summaries.
2025-09-04 06:32:09 -05:00
G. Branden Robinson
62c223ead2 HACKING: Clarify a pain point. 2025-05-17 11:43:37 -05:00
G. Branden Robinson
964f9dcff0 HACKING: Update and correct list of operations. 2025-01-02 07:37:14 -06:00
G. Branden Robinson
c34c6cc58c [nroff]: Improve shell behavior check.
...and fix goof in test script.

* src/roff/nroff/nroff.sh: Replace proxy `unset`-based test with an
  actual measurement of parameter expansion.

* src/roff/nroff/tests/verbose_option_works.sh: Fix spurious failure of
  test for grep(1) supporting `-q` and `-x` options.  Continues commit
  e05cf6d3b3, 4 December.

Every time I have to deal with Solaris, it's like gazing into the Abyss.

A test failure of "src/roff/nroff/tests/verbose_option_works.sh" is
expected on Solaris 10, because 2 of the checks in that script verify
that option clustering works, and with Solaris 10 /bin/sh, it doesn't.
The test failure is therefore not spurious.  One can edit the installed
nroff script in place to use "/usr/xpg4/bin" in its shebang line.
2024-12-10 09:27:02 -06:00
G. Branden Robinson
2514dc63e0 Adapt tests to feeble systems.
...lacking a shell or grep conforming to POSIX Issue 4 (1994).

* src/roff/groff/tests/msoquiet-request-works.sh:
* src/roff/groff/tests/soquiet-request-works.sh:
* tmac/tests/an_UR-works.sh: Do it.

* tmac/tests/an_UR-works.sh: Also cope with versions of pdftotext(1)
  that transcribe "fi" as a ligature.

* HACKING:
* PROBLEMS: Update advice.
2024-12-04 06:44:29 -06:00
G. Branden Robinson
92fa8c7f64 [hdbtl]: Guard against Solaris tr(1) brain damage.
* contrib/hdtbl/examples/fonts_n.in:
* contrib/hdtbl/examples/fonts_x.in: Guard against substandard tr(1)
  implementation on Solaris 10 by forcing locale to "C" when using a
  POSIX regular expression character class.

* HACKING: Document this land mine.
2024-12-02 21:46:18 -06:00
G. Branden Robinson
4caf704985 HACKING: Correct my bad advice regarding wc. 2024-12-02 21:46:18 -06:00
G. Branden Robinson
8c97bb993c Fix Savannah #66479 (2/2).
* HACKING: Document another macOS od(1) irritation.

* src/roff/groff/tests/dvi-device-smoke-test.sh: Work around macOS
  od(1)'s injection of extra spaces into its "-tx1" output.

Fixes <https://savannah.gnu.org/bugs/?66479>.  Thanks to Sven Schober
for the report, analysis, and for proposing fixes.
2024-11-28 15:20:00 -06:00
G. Branden Robinson
9bf4595fcc [tmac]: Fix Savannah #66479 (1a/2).
* HACKING: Document macOS wc(1) irritation.

* tmac/tests/an_vertical-margins-are-correct.sh:
* tmac/tests/doc-old_vertical-margins-are-correct.sh:
* tmac/tests/doc_vertical-margins-are-correct.sh: Work around macOS
  wc(1)'s right-alignment of its integer output field.
2024-11-28 15:20:00 -06:00
G. Branden Robinson
256eef0bc0 HACKING: Add guidance regarding \] in regexes. 2024-11-24 21:59:58 -06:00
G. Branden Robinson
75faa2d487 HACKING: Fix terminological and grammar nits.
Use the term "expression", which is of import in U.S. Code Title 17,
§501(a)-(b).

Also fix noun/verb agreement.  (I have them separated by about 52 words.
Maybe I should recast...)
2024-10-03 06:15:51 -05:00
G. Branden Robinson
0df4bc2bc5 HACKING: Fix omitted commands in examples. 2024-08-28 20:08:00 -05:00
G. Branden Robinson
4ba2923fce HACKING: Add note about C++ value initializers. 2024-08-20 10:02:47 -05:00
G. Branden Robinson
e1d7ccd4fd HACKING: Fix missing capitalization. 2024-08-19 12:29:49 -05:00
G. Branden Robinson
6ef1c37cac {HACKING,MANIFEST}: Relocate material. 2024-08-15 11:37:40 -05:00
G. Branden Robinson
a931d3845e HACKING: Add gnulib update procedure.
FOR-RELEASE: Cross-reference new material.
2024-07-18 16:19:16 -05:00
G. Branden Robinson
28dfa1ec58 HACKING: Bump copyright year.
...to reflect substanial addition of material discussing...

...copyright, and when to bump the year in the copyright notice.

:-|

Continues commit 90b15242d0, 6 July.

Also fix wordo and tighten language.
2024-07-10 09:22:10 -05:00
G. Branden Robinson
90b15242d0 HACKING, FOR-RELEASE: Update copyright advice. 2024-07-09 12:30:43 -05:00
G. Branden Robinson
e0cb0910cb Rename array_size to array_length.
* src/include/lib.h (array_size): Rename to...
  (array_length): ...this.

* src/preproc/eqn/box.cpp (set_param, reset_param, get_param)
  (init_param_table, free_param_table): Migrate call sites.

Thanks to Alex Colomar for the discussion.

See <https://lists.gnu.org/archive/html/groff/2023-08/msg00140.html>.

Acked-by: Alejandro Colomar <alx@kernel.org>
2023-08-28 15:21:40 -05:00
G. Branden Robinson
ba556e7beb HACKING: Fix bad sed mnemonic.
"Branch" is the mnemonic for the 'b' command; 't' is "test".  (The
latter _conditionally_ branches.)
2023-07-28 04:49:31 -05:00
G. Branden Robinson
9aeb25f4f7 HACKING: Add section about C++ dialect used.
Also add editor aid "comments", like other top-level plain text files.
2023-06-10 22:43:56 -05:00
G. Branden Robinson
47d5846631 HACKING: Tighten example of seq replacement. 2023-05-25 03:34:59 -05:00
G. Branden Robinson
65b44e7a45 HACKING: Stop saying automake.pdf isn't installed.
...because it is.
2023-04-01 10:33:39 -05:00
G. Branden Robinson
d015cb475e [man]: Improve portability of a test.
* tmac/tests/an_TS-do-not-keep-tables-when-cR-set.sh: Improve
  portability of script by using shell constructs instead of the
  nonstandard GNU coreutils 'seq' utility.  Resolves test failure on
  Solaris 10.

* HACKING: Document this problem.
2023-02-20 14:01:14 -06:00
G. Branden Robinson
b2201256d1 [ms]: Port a test to Solaris 11 sed.
* tmac/tests/s_TC-works-with-percent-in-custom-titles.sh: Put newlines
  after opening braces in sed scripts.  macOS and GNU sed tolerate their
  absence, but this sed does not.

* HACKING: Document this problem.
2023-02-17 06:12:11 -06:00
G. Branden Robinson
507088b101 HACKING: Clarify item. 2023-02-15 09:22:14 -06:00
G. Branden Robinson
4392979e9d [tmac]: Work around macOS od (mis-)behavior.
* tmac/tests/latin2_works.sh:
* tmac/tests/latin5_works.sh:
* tmac/tests/latin9_works.sh: Port to work around macOS's apparently
  POSIX non-conforming 'od' command.  Use single-byte octal output
  format instead of "character", and update test expectations
  accordingly.  Apparently gratuitously, macOS also puts more spaces
  after the octal address field when using this output format.

* HACKING: Document, and elaborate upon, this problem.

Also distinguish identical test failure diagnostics.

ANNOUNCE: Remove caveat about automated test failures on macOS.
2023-02-13 20:22:48 -06:00
G. Branden Robinson
27057ea197 HACKING: Offer advice, resource for POSIX Issue 4. 2023-02-13 18:17:34 -06:00
G. Branden Robinson
dd4511bfb0 [mdoc]: Port a test to work with macOS sed.
* tmac/tests/doc_heading-font-remapping-works.sh: Put semicolons between
  commands and closing braces in sed script.  Put each of multiple
  closing braces on a separate input line, because macOS doesn't accept
  them otherwise.  Resolves test failure observed on macOS.

* HACKING: Document the closing brace sequence problem.

* ANNOUNCE: Drop notice of failing test case, now resolved.
2023-02-13 12:07:04 -06:00
G. Branden Robinson
a47e898520 [man]: Port a test to work with macOS sed.
* tmac/tests/an_TS-adds-no-vertical-space.sh: Put semicolons between
  commands and closing braces in sed script.  Separate command stream
  into multiple '-e' expressions, breaking them after branch and label
  commands.  Resolves test failure observed on macOS.

* HACKING: Document the above problems.

* ANNOUNCE: Drop notice of failing test case, now resolved.
2023-02-13 12:06:09 -06:00
G. Branden Robinson
57e13c40ea [groff]: Accommodate macOS od behavior in test.
* src/roff/groff/tests/some_escapes_accept_newline_delimiters.sh: Weaken
  regexes in two test cases to accommodate excessive output from macOS's
  'od' command.  Resolves test failure seen on macOS.

* HACKING: Add section "Writing Tests" and document the above since this
  is the second time I've cracked my shin on this.

* ANNOUNCE: Drop notice of failing test case, now resolved.
2023-02-13 12:05:10 -06:00
G. Branden Robinson
eceb2d85dc HACKING: Drop extraneous word. 2022-10-06 07:23:27 -05:00
G. Branden Robinson
85ed2440b0 HACKING: Point reader to "MANIFEST". 2022-09-02 18:22:51 -05:00
G. Branden Robinson
c893202d20 FOR-RELEASE, HACKING, INSTALL.REPO, README: Tweak.
* FOR-RELEASE: Split-off ChangeLog files need to be added to the
  distribution archive.

* HACKING: Clarify non-ChangeLoggable items.  Generally, an item that
  resolves a Savannah ticket should be ChangeLogged even if it would not
  normally meet that threshold.  Also clarify a point in an example; we
  certainly expect table entries containing the word "FOOBAR" to show up
  that way when formatted.

* INSTALL.REPO: Correct prose description of what to do with unpacked
  "gnulib" snapshot.

* README: Clarify that the '.version' file is produced by the build
  process.  Clarify origins and provenance of various groff components.
  Use a more appropriate URL for the Savannah issue tracker.  Lightly
  recast.
2022-05-26 09:29:16 -05:00
G. Branden Robinson
bd43408faa HACKING: Add developer-facing advice document.
This scoops up the 'automake.mom' material just dropped from
'INSTALL.REPO', and summarizes a couple of discussions from the mailing
list over the past 2 years or so.
2022-05-24 11:25:09 -05:00