gbranden pushed a commit to branch master
in repository groff.
commit 6c597c5b877a7f703c5dbf8d93892b7916a9574e
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sat Feb 14 10:25:51 2026 -0600
tmac/: Improve comment headers.
* Supply missing descriptions of each macro file's purpose, where
missing. (A recapitulation of the file name is not a description.)
* Improve existing descriptions.
* Add cross references to man pages.
* Drop old-style Emacs file-local variable.
* Refill comment lines at 72 columns.
---
tmac/62bit.tmac | 2 +-
tmac/X.tmac | 3 ++-
tmac/Xps.tmac | 3 ++-
tmac/an.tmac | 2 ++
tmac/composite.tmac | 2 +-
tmac/doc-old.tmac | 7 +++++++
tmac/doc.tmac | 2 ++
tmac/dvi.tmac | 2 +-
tmac/e.tmac | 4 ++++
tmac/ec.tmac | 3 ++-
tmac/europs.tmac | 7 ++++---
tmac/fallbacks.tmac | 2 +-
tmac/html-end.tmac | 3 ++-
tmac/html.tmac | 2 +-
tmac/koi8-r.tmac | 3 ++-
tmac/latin1.tmac | 3 ++-
tmac/latin2.tmac | 3 ++-
tmac/latin5.tmac | 3 ++-
tmac/latin9.tmac | 3 ++-
tmac/lbp.tmac | 2 +-
tmac/lj4.tmac | 2 +-
tmac/man.tmac | 5 +----
tmac/mandoc.tmac | 5 +----
tmac/mdoc.tmac | 5 +----
tmac/me.tmac | 5 +----
tmac/ms.tmac | 5 +----
tmac/papersize.tmac | 2 +-
tmac/pic.tmac | 4 +++-
tmac/ps.tmac | 4 ++--
tmac/psatk.tmac | 8 +++-----
tmac/psfig.tmac | 13 +++++++++----
tmac/psold.tmac | 13 +++++--------
tmac/pspic.tmac | 2 +-
tmac/ptx.tmac | 6 ++----
tmac/refer.tmac | 2 +-
tmac/tty.tmac | 3 ++-
36 files changed, 78 insertions(+), 67 deletions(-)
diff --git a/tmac/62bit.tmac b/tmac/62bit.tmac
index b1f689799..a4638f608 100644
--- a/tmac/62bit.tmac
+++ b/tmac/62bit.tmac
@@ -1,4 +1,4 @@
-.\" macro package supporting 62-bit arithmetic in GNU troff
+.\" Support 62-bit arithmetic in GNU troff(1).
.
.\" Copyright 2006 Free Software Foundation, Inc.
.\"
diff --git a/tmac/X.tmac b/tmac/X.tmac
index c51d593c8..b95d9b4cd 100644
--- a/tmac/X.tmac
+++ b/tmac/X.tmac
@@ -1,4 +1,5 @@
-.\" X.tmac
+.\" Configure groff output devices "X75", "X75-12", "X100", and
+.\" "X100-12". See gxditview(1).
.
.do nr *groff_X_tmac_C \n[.cp]
.cp 0
diff --git a/tmac/Xps.tmac b/tmac/Xps.tmac
index 76db673d7..54bcb0f05 100644
--- a/tmac/Xps.tmac
+++ b/tmac/Xps.tmac
@@ -1,4 +1,5 @@
-.\" Xps.tmac
+.\" Configure groff output devices "X75", "X75-12", "X100", and
+.\" "X100-12" for use with groff's "-T ps" option. See gxditview(1).
.
.do nr *groff_Xps_tmac_C \n[.cp]
.cp 0
diff --git a/tmac/an.tmac b/tmac/an.tmac
index f325eb479..9a885b120 100644
--- a/tmac/an.tmac
+++ b/tmac/an.tmac
@@ -1,4 +1,6 @@
.\" groff implementation of man(7) package
+.\"
+.\" See groff_man(7).
.
.\" Copyright 1989-2024 Free Software Foundation, Inc.
.\" 2020-2025 G. Branden Robinson
diff --git a/tmac/composite.tmac b/tmac/composite.tmac
index 87ffe50a2..105506b9a 100644
--- a/tmac/composite.tmac
+++ b/tmac/composite.tmac
@@ -1,4 +1,4 @@
-.\" composite.tmac
+.\" Set up composite character mappings; see groff_char(7).
.
.do composite ga u0300
.do composite ` u0300
diff --git a/tmac/doc-old.tmac b/tmac/doc-old.tmac
index f98a02095..b58c1f39b 100644
--- a/tmac/doc-old.tmac
+++ b/tmac/doc-old.tmac
@@ -1,3 +1,10 @@
+.\" Support defunct second version of mdoc macros from 4.3BSD-Reno
+.\" (1990); for use with historical documents only. Any mdoc documents
+.\" written since BSD's "Net/2" release in 1991 should (and likely do)
+.\" use the third version of the mdoc macros. See groff_mdoc(7).
+.\"
+.\" The first version of the mdoc macros is thought to be lost.
+.
.\" Copyright (c) 1990 The Regents of the University of California.
.\" All rights reserved.
.\"
diff --git a/tmac/doc.tmac b/tmac/doc.tmac
index 87d8012e0..881ee2381 100644
--- a/tmac/doc.tmac
+++ b/tmac/doc.tmac
@@ -1,5 +1,7 @@
.\" groff implementation of mdoc(7) package
.\"
+.\" See groff_mdoc(7).
+.
.\" Copyright (c) 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
diff --git a/tmac/dvi.tmac b/tmac/dvi.tmac
index 931e99e6c..3faf8f9a3 100644
--- a/tmac/dvi.tmac
+++ b/tmac/dvi.tmac
@@ -1,4 +1,4 @@
-.\" dvi.tmac
+.\" Configure groff output device "dvi". See grodvi(1).
.
.do nr *groff_dvi_tmac_C \n[.cp]
.cp 0
diff --git a/tmac/e.tmac b/tmac/e.tmac
index fae5a218f..9402c1174 100644
--- a/tmac/e.tmac
+++ b/tmac/e.tmac
@@ -1,3 +1,7 @@
+.\" groff implementation of me(7) package
+.\"
+.\" See groff_me(7).
+.
.\" Copyright (c) 1988, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
diff --git a/tmac/ec.tmac b/tmac/ec.tmac
index 894300cf4..a8f1857f0 100644
--- a/tmac/ec.tmac
+++ b/tmac/ec.tmac
@@ -1,4 +1,5 @@
-.\" Switch to EC fonts.
+.\" Configure groff output device "dvi" for use with TeX's EC fonts.
+.\" See grodvi(1).
.\"
.\" Load this file before any language-specific stuff.
.\"
diff --git a/tmac/europs.tmac b/tmac/europs.tmac
index c9236ac1d..91215fdeb 100644
--- a/tmac/europs.tmac
+++ b/tmac/europs.tmac
@@ -1,6 +1,7 @@
-.\" -*- nroff -*-
-.\"
-.\" europs.tmac
+.\" Configure groff output device "ps" to use groff's "EURO" font
+.\" description file (and supporting "freeeuro" Type 1 font). Early
+.\" versions of the PostScript standard, and devices/software conforming
+.\" to it, andedate the Euro currency. See grops(1).
.
.do char \[eu] \f[EURO]\N'0'
.
diff --git a/tmac/fallbacks.tmac b/tmac/fallbacks.tmac
index 7c641215f..847dc183f 100644
--- a/tmac/fallbacks.tmac
+++ b/tmac/fallbacks.tmac
@@ -1,4 +1,4 @@
-.\" Define fallbacks for unavailable glyphs.
+.\" Define fallbacks for glyphs unavailable to GNU troff(1).
.\"
.\" These are designed such that "troffrc" loads them early, after
.\" composite glyph setup but before any device-specific fallbacks.
diff --git a/tmac/html-end.tmac b/tmac/html-end.tmac
index 2b6b01f43..1029055c4 100644
--- a/tmac/html-end.tmac
+++ b/tmac/html-end.tmac
@@ -1,4 +1,5 @@
-.\" Configure groff output device "html".
+.\" Finish configuring groff output devices "html" and "xhtml". See
+.\" grohtml(1).
.
.do nr *groff_html-end_tmac_C \n[.cp]
.cp 0
diff --git a/tmac/html.tmac b/tmac/html.tmac
index 00ae81e08..bf8dc9329 100644
--- a/tmac/html.tmac
+++ b/tmac/html.tmac
@@ -1,4 +1,4 @@
-.\" Configure grohtml(1) output devices: "html" and "xhtml".
+.\" Configure groff output devices "html" and "xhtml". See grohtml(1).
.
.do nr *groff_html_tmac_C \n[.cp]
.cp 0
diff --git a/tmac/koi8-r.tmac b/tmac/koi8-r.tmac
index 5747c15a0..f58796fba 100644
--- a/tmac/koi8-r.tmac
+++ b/tmac/koi8-r.tmac
@@ -1,4 +1,5 @@
-.\" koi8-r.tmac
+.\" Support KOI8-R character encoding used by groff's Russian locale.
+.\" See groff_tmac(5).
.
.do nr *groff_koi8-r_tmac_C \n[.cp]
.cp 0
diff --git a/tmac/latin1.tmac b/tmac/latin1.tmac
index c006c06a8..c5d8cb90c 100644
--- a/tmac/latin1.tmac
+++ b/tmac/latin1.tmac
@@ -1,4 +1,5 @@
-.\" latin1.tmac
+.\" Support Latin-1 character encoding used by some groff locales. See
+.\" groff_tmac(5).
.
.do nr *groff_latin1_tmac_C \n[.cp]
.cp 0
diff --git a/tmac/latin2.tmac b/tmac/latin2.tmac
index 36adfb575..10269dd1f 100644
--- a/tmac/latin2.tmac
+++ b/tmac/latin2.tmac
@@ -1,4 +1,5 @@
-.\" latin2.tmac
+.\" Support Latin-2 character encoding used by some groff locales. See
+.\" groff_tmac(5).
.
.do nr *groff_latin2_tmac_C \n[.cp]
.cp 0
diff --git a/tmac/latin5.tmac b/tmac/latin5.tmac
index c0b9ab0a2..0cfa19506 100644
--- a/tmac/latin5.tmac
+++ b/tmac/latin5.tmac
@@ -1,4 +1,5 @@
-.\" latin5.tmac
+.\" Support Latin-5 character encoding used by some groff locales. See
+.\" groff_tmac(5).
.
.do nr *groff_latin5_tmac_C \n[.cp]
.cp 0
diff --git a/tmac/latin9.tmac b/tmac/latin9.tmac
index 72785cc3d..0069458af 100644
--- a/tmac/latin9.tmac
+++ b/tmac/latin9.tmac
@@ -1,4 +1,5 @@
-.\" latin9.tmac
+.\" Support Latin-9 character encoding used by some groff locales. See
+.\" groff_tmac(5).
.
.do nr *groff_latin9_tmac_C \n[.cp]
.cp 0
diff --git a/tmac/lbp.tmac b/tmac/lbp.tmac
index 536eb9bbf..24c3c84ab 100644
--- a/tmac/lbp.tmac
+++ b/tmac/lbp.tmac
@@ -1,4 +1,4 @@
-.\" lbp.tmac
+.\" Configure groff output device "lbp". See grolbp(1).
.
.do nr *groff_lbp_tmac_C \n[.cp]
.cp 0
diff --git a/tmac/lj4.tmac b/tmac/lj4.tmac
index 230201951..0251f452a 100644
--- a/tmac/lj4.tmac
+++ b/tmac/lj4.tmac
@@ -1,4 +1,4 @@
-.\" lj4.tmac
+.\" Configure groff output device "lj4". See grolj4(1).
.
.do nr *groff_lj4_tmac_C \n[.cp]
.cp 0
diff --git a/tmac/man.tmac b/tmac/man.tmac
index b017e5afd..4f120021c 100644
--- a/tmac/man.tmac
+++ b/tmac/man.tmac
@@ -1,5 +1,2 @@
-.\" -*- nroff -*-
-.\"
-.\" man.tmac
-.\"
+.\" wrapper supporting groff options `-m man` and `-mman`
.do mso an.tmac
diff --git a/tmac/mandoc.tmac b/tmac/mandoc.tmac
index e0a1502f1..3e3752c3c 100644
--- a/tmac/mandoc.tmac
+++ b/tmac/mandoc.tmac
@@ -1,5 +1,2 @@
-.\" -*- nroff -*-
-.\"
-.\" mandoc.tmac
-.\"
+.\" wrapper supporting groff options `-m mandoc` and `-mmandoc`
.do mso andoc.tmac
diff --git a/tmac/mdoc.tmac b/tmac/mdoc.tmac
index 2f18a0dc5..a065b70ab 100644
--- a/tmac/mdoc.tmac
+++ b/tmac/mdoc.tmac
@@ -1,5 +1,2 @@
-.\" -*- nroff -*-
-.\"
-.\" mdoc.tmac
-.\"
+.\" wrapper supporting groff options `-m mdoc` and `-mmdoc`
.do mso doc.tmac
diff --git a/tmac/me.tmac b/tmac/me.tmac
index 639ed6634..8f56fcb26 100644
--- a/tmac/me.tmac
+++ b/tmac/me.tmac
@@ -1,5 +1,2 @@
-.\" -*- nroff -*-
-.\"
-.\" me.tmac
-.\"
+.\" wrapper supporting groff options `-m me` and `-mme`
.do mso e.tmac
diff --git a/tmac/ms.tmac b/tmac/ms.tmac
index 6d49fdff1..11aacbb01 100644
--- a/tmac/ms.tmac
+++ b/tmac/ms.tmac
@@ -1,5 +1,2 @@
-.\" -*- nroff -*-
-.\"
-.\" ms.tmac
-.\"
+.\" wrapper supporting groff options `-m ms` and `-mms`
.do mso s.tmac
diff --git a/tmac/papersize.tmac b/tmac/papersize.tmac
index e10219ad5..8b33b354f 100644
--- a/tmac/papersize.tmac
+++ b/tmac/papersize.tmac
@@ -1,4 +1,4 @@
-.\" Set up GNU troff for various paper sizes.
+.\" Set up GNU troff for various paper formats. See groff(1).
.\"
.\" Usage:
.\"
diff --git a/tmac/pic.tmac b/tmac/pic.tmac
index e2c5e5ae1..5b15e790c 100644
--- a/tmac/pic.tmac
+++ b/tmac/pic.tmac
@@ -1,4 +1,6 @@
-.\" pic.tmac
+.\" Define support macros for GNU pic(1) where a full-service macro
+.\" package does not do so, or a full-service macro package is not used.
+.\" See pic(1) and groff_tmac(5).
.
.de PS
.br
diff --git a/tmac/ps.tmac b/tmac/ps.tmac
index c8580a008..2ad3433f9 100644
--- a/tmac/ps.tmac
+++ b/tmac/ps.tmac
@@ -1,9 +1,9 @@
-.\" ps.tmac
+.\" Configure groff output device "ps". See grops(1).
.
.do nr *groff_ps_tmac_C \n[.cp]
.cp 0
.
-.\" These font translations will be withdrawn in groff 1.25.
+.\" These font translations will be withdrawn sometime after groff 1.24.
.ftr AX ABI
.ftr KR BMR
.ftr KI BMI
diff --git a/tmac/psatk.tmac b/tmac/psatk.tmac
index ba256e706..56abe899a 100644
--- a/tmac/psatk.tmac
+++ b/tmac/psatk.tmac
@@ -1,9 +1,7 @@
-.\" -*- nroff -*-
+.\" Define PB and PE macros (used by the Andrew Tooklit, ATK) suitable
+.\" for use with groff(1) and grops(1).
.\"
-.\" psatk.tmac
-.\"
-.\" Implementation of the ATK PB and PE macros for use with groff and grops.
-.\" Load this after atk.tmac.
+.\" Load this macro file after atk.tmac, supplied by ATK.
.
.do nr *groff_psatk_tmac_C \n[.cp]
.cp 0
diff --git a/tmac/psfig.tmac b/tmac/psfig.tmac
index 5b6132ee2..61dd50e56 100644
--- a/tmac/psfig.tmac
+++ b/tmac/psfig.tmac
@@ -1,9 +1,14 @@
-.\" -*- nroff -*-
+.\" Define macros to support use of Trevor Darnell's "psfig",
+.\" distributed in volume 11 of comp.unix.sources, and not to be
+.\" confused with the unrelated TeX macro package "psfig" available at
+.\" CTAN. (Neither is Free Software.)
.\"
-.\" psfig.tmac
+.\" These macros require that psfig be patched as described in
+.\" "src/devices/grops/psfig.diff".
.\"
-.\" These are macros to make psfig work with groff.
-.\" They require that psfig be patched as described in ../grops/psfig.diff.
+.\" This file is likely to disappear in a future groff release.
+.\"
+.\" Use groff's `PSPIC` macro instead. See groff_tmac(5).
.
.do nr *groff_psfig_tmac_C \n[.cp]
.cp 0
diff --git a/tmac/psold.tmac b/tmac/psold.tmac
index d390412ca..a6668f974 100644
--- a/tmac/psold.tmac
+++ b/tmac/psold.tmac
@@ -1,13 +1,10 @@
-.\" -*- nroff -*-
-.\"
-.\" psold.tmac
-.\"
.\" In newer PostScript printers, text fonts contain all ISO Latin-1
.\" characters. The font description files that comes with groff match
-.\" these fonts. The text fonts in older PostScript printers are missing
-.\" some of these characters. This file prevents those characters from
-.\" being used. This will allow the PostScript output to be printed on
-.\" such old printers.
+.\" these fonts. The text fonts in older PostScript printers are
+.\" missing some of these characters. This file prevents those
+.\" characters from being used, allowing grops(1)'s output to be printed
+.\" on such old printers. See section "Old fonts" of grops(1).
+.
.do nr *groff_psold_tmac_C \n[.cp]
.cp 0
.\" Define an accented character.
diff --git a/tmac/pspic.tmac b/tmac/pspic.tmac
index 5f0871aaa..a2b4f922b 100644
--- a/tmac/pspic.tmac
+++ b/tmac/pspic.tmac
@@ -1,4 +1,4 @@
-.\" Define the PSPIC macro.
+.\" Define the `PSPIC` macro.
.\"
.\" When used with output devices other than ps, dvi, html, or xhtml,
.\" draw a box where the picture would go.
diff --git a/tmac/ptx.tmac b/tmac/ptx.tmac
index 2235610ed..0349dcad1 100644
--- a/tmac/ptx.tmac
+++ b/tmac/ptx.tmac
@@ -1,7 +1,5 @@
-.\" ptx.tmac
-.\"
-.\" Provide '.xx' macro to format permuted index entries as created
-.\" by GNU ptx.
+.\" Define an `xx` macro to format permuted index entries as created by
+.\" GNU ptx.
.\"
.\" Written 2008 by Werner Lemberg ([email protected])
.\"
diff --git a/tmac/refer.tmac b/tmac/refer.tmac
index 4fd030f20..b4cba7c60 100644
--- a/tmac/refer.tmac
+++ b/tmac/refer.tmac
@@ -1,4 +1,4 @@
-.\" This is an interface to 'refer', originally part of 's.tmac'.
+.\" This is an interface to refer(1), originally part of "s.tmac".
.
.\" Copyright 2011-2020 Free Software Foundation, Inc.
.\"
diff --git a/tmac/tty.tmac b/tmac/tty.tmac
index 3da10f5e4..246463665 100644
--- a/tmac/tty.tmac
+++ b/tmac/tty.tmac
@@ -1,4 +1,5 @@
-.\" Configure groff output devices "ascii", "latin1", and "utf8".
+.\" Configure groff output devices "ascii", "latin1", and "utf8". See
+.\" grotty(1).
.
.do nr *groff_tty_tmac_C \n[.cp]
.cp 0
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
