From f09bf35275045ba3d8f50f0017257a0a8a353096 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Ankarstr=C3=B6m?= <john@ankarstrom.se>
Date: Mon, 21 Jun 2021 20:35:58 +0200
Subject: Change macro/register naming scheme

---
 example.t | 110 ++++++++++++++++++++++++++++++++++++++++++--------------------
 1 file changed, 74 insertions(+), 36 deletions(-)

(limited to 'example.t')

diff --git a/example.t b/example.t
index 29f0452..78a3879 100644
--- a/example.t
+++ b/example.t
@@ -1,16 +1,16 @@
 .so g.tmac
 .
 . \" configure environments
-._e p
+.@e p
 . nr sq \n(sp
 . nr sp 0
-._e l
+.@e l
 . fam M
 . vs +1p
-._e n
-. _ec p
+.@e n
+. @c p
 . ta 3n +3n +3n +3n
-._e
+.@e
 .
 . \" define macros
 .eo
@@ -24,7 +24,7 @@
 . \}
 . nr ni +1
 . br
-. _e n
+. @e n
 . ti \n(tiu
 \n(ni\*(n.	\c
 ..
@@ -154,8 +154,8 @@ the indentation of the first line in some environments
 These can be set inside a given environment
 to control its behavior when invoked.
 The only exception are the margin and footnote environments
-.c _m , (
-.c _f ),
+.c @m , (
+.c @f ),
 which are treated specially
 and do not support these registers.
 .
@@ -204,7 +204,9 @@ defines a number of macros.
 Some of them are used internally by
 .i mg
 itself;
-these carry an underscore prefix
+these carry an at
+.c @ ) (
+prefix
 and are going to be explored later.
 For now, we will focus on the external macros provided by
 .i mg .
@@ -377,14 +379,40 @@ Internal macros
 .i Mg 's
 internal macros are generally not meant to be used outside of
 .i g.tmac .
-.c _E ,
-.c _e
+The group of macros controlling the environment \(en
+.c (e ,
+.c @e
 and
-.c _ec ,
-a group of macros controlling the environment,
-are excepted from this rule,
+.c @c
+\(en are excepted from this rule,
 as it may be desirable to define custom environments
 for advanced documents.
+.p
+At the present,
+.c (e
+is nothing more than a wrapper around troff's built-in
+.c ev ,
+but it may eventually be redefined in order to offer
+compatibility with implementations of troff
+without support for named environments.
+.c @e
+and
+.c @c
+are equivalent to troff's
+.c ev
+and
+.c evc ,
+but keep track of a few extra variables (see
+.i Environments
+above).
+.p
+For examples of how
+.c (e ,
+.c @e
+and
+.c @c
+are used in practice,
+see the FAQ section below.
 .
 .
 .h
@@ -437,24 +465,24 @@ you can switch to that environment and use the relevant troff requests:
 If you are merely configuring the environment
 without printing anything in it,
 you can also use the
-.c _e
+.c @e
 macro:
 .l
-\&._e q
+\&.@e q
 \&.ps +1p
 .
 .w s ll
 .s
 How do I customize the default appearance of the margin text?
 .l
-\&._E _m \\" margin environment
+\&.(e @m \\" margin environment
 \&.ps +1p
 .
 .w s ll
 .s
 How do I customize the default appearance of footnotes?
 .l
-\&._E _f \\" footnote environment
+\&.(e @f \\" footnote environment
 \&.ps +1p
 .
 .s
@@ -464,24 +492,34 @@ Some macro packages have a concept of
 .q keeps ,
 sections that are kept together across page breaks.
 .i Mg
-does not define any helper macros for this purpose by default.
-The user is recommended to use troff's
+does not define any such macros by default.
+The simplest way to achieve the same is to use troff's
 .c ne
 request:
 .l
-\&.q
-\&.ne 7
-Four score and seven years ago...
+\&.ne 7 \\" break page if seven lines won't fit on this page
+\&.\\" ... some text ...
 .p
-In some cases,
+If you want to keep text of various styles together,
+you can use
 .i mg 's
 own
 .c w
-macro may be useful:
+macro:
 .l
-\&.w qqqqqqq
-\&.q
-Four score and seven years ago...
+\&.w s qq \\" break page if a subheading and two lines of a quotation won't fit
+\&.\\" ... some text ...
+.ig
+.p
+For a more general solution, you can use a diversion:
+.l
+\&.di keep
+\&.\\" ... some text ...
+\&.br
+\&.di
+\&.ne \\n(dnu
+\&.keep
+..
 .
 .s
 How do I define my own environments?
@@ -495,19 +533,19 @@ extends environments with additional functionality,
 it provides special macros to be used instead of
 .c ev :
 .n 1
-.c _E ,
+.c (e ,
 set environment (same as
 .c ev )
 .n
-.c _e ,
+.c @e ,
 set extended environment
 .n
-.c _ec ,
+.c @c ,
 copy environment (same as
 .c evc )
 .p
 The
-.c _e
+.c @e
 macro
 can be used to activate any environment that supports
 .i mg 's
@@ -518,12 +556,12 @@ The following code configures an environment called
 .c n
 and defines a corresponding macro:
 .l
-\&._e n
-\&. _ec 0 \\" copy default environment
+\&.@e n
+\&. @c 0 \\" copy default environment
 \&. ps -1p
-\&._e
+\&.@e
 \&.
 \&.de n
 \&. br \\" finish current environment
-\&. _e n \\" activate new environment
+\&. @e n \\" activate new environment
 \&..
-- 
cgit v1.2.3