[Groff] [PATCH] groff_tmac(5): Discuss stripping macros.

[G. Branden Robinson]

Since the tmac-u discussion turned out to be a FAQ, I thought I'd do
something about it.

Comments and especially corrections welcome.  My explanation of groff's
input handling is partly based on Werner's explanation and partly
guesswork.  I confess I didn't attempt a deep comprehension of
src/roff/troff/input.cpp.

Diff inlined and attached for your convenience.

diff --git a/man/groff_tmac.5.man b/man/groff_tmac.5.man
index 3180bd96..34ca7b19 100644
--- a/man/groff_tmac.5.man
+++ b/man/groff_tmac.5.man
@@ -1170,6 +1170,53 @@ the diversion and can be manipulated from within the 
macros.
 .
 .
 .\" ====================================================================
+.SS "Stripping Your Macros"
+.\" ====================================================================
+.
+In the
+.I groff
+source distribution, some of the macro packages (corresponding to
+.BR groff_hdtbl (@MAN7EXT@),
+.BR groff_mdoc (@MAN7EXT@),
+.BR groff_me (@MAN7EXT@),
+and
+.BR groff_mom (@MAN7EXT@)
+as of this writing)
+are maintained in \[lq]unstripped\[rq] forms that are then reduced for
+installation.
+.
+These files are named with a
+.B \-u
+suffix, e.g.,
+.BR tmac/e.tmac\-u .
+.
+The stripping process primarily eliminates spaces between dots and
+request or macro names (used for indentation and readability of the
+macro sources) and most comments.
+.
+This process is done because
+.I groff
+stores no internal representation of its language; every line is
+lexically analyzed and parsed afresh every time it is read.
+.
+No tokenization or caching is performed.
+.
+.
+.P
+If you experience performance problems with your macro package (or even
+an individual macro, if it has a
+.B .while
+loop that iterates many times, for instance), you may wish to consider
+performing a similar reduction process.
+.
+If you strip your macros, we strongly recommend that you follow GNU
+.IR roff 's
+example, and
+.I maintain
+your macros in unstripped form.
+.
+.
+.\" ====================================================================
 .SH FILES
 .\" ====================================================================
 .

-- 
Regards,
Branden

groff_tmac_stripping.diff
Description: Text Data

signature.asc
Description: PGP signature