[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Groff] [PATCH] groff_tmac(5): Discuss stripping macros.
From: |
G. Branden Robinson |
Subject: |
[Groff] [PATCH] groff_tmac(5): Discuss stripping macros. |
Date: |
Tue, 7 Nov 2017 09:04:56 -0500 |
User-agent: |
NeoMutt/20170113 (1.7.2) |
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
- [Groff] [PATCH] groff_tmac(5): Discuss stripping macros.,
G. Branden Robinson <=