[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 14/18: groff(7): Add "Copy mode" section.
From: |
G. Branden Robinson |
Subject: |
[groff] 14/18: groff(7): Add "Copy mode" section. |
Date: |
Thu, 3 Jun 2021 11:03:24 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit 0a8cfd7d02d7245d84df8fca22cdfb17eaa9f1b3
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Jun 4 00:13:22 2021 +1000
groff(7): Add "Copy mode" section.
* man/groff.7.man (Copy mode): Replace existing approximate discussion
of copy mode with new section.
---
ChangeLog | 4 ++
man/groff.7.man | 116 ++++++++++++++++++++++++++++++++++----------------------
2 files changed, 74 insertions(+), 46 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 55ac136..38bac5b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
2021-06-03 G. Branden Robinson <g.branden.robinson@gmail.com>
+ * man/groff.7.man (Copy mode): Add new section.
+
+2021-06-03 G. Branden Robinson <g.branden.robinson@gmail.com>
+
* src/roff/troff/input.cpp (else_request, while_request,
pipe_source, open_request, opena_request, pipe_output,
system_request): Update diagnostic messages to not presume the
diff --git a/man/groff.7.man b/man/groff.7.man
index 86ea3b7..d53233c 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -335,52 +335,6 @@ and
.squoted_char ] .
.
.
-.P
-The roff language provides flexible instruments for writing language
-extension, such as macros.
-.
-When interpreting macro definitions, the roff system enters a special
-operating mode, called the
-.BR "copy mode" .
-.
-.
-.P
-The copy mode behaviour can be quite tricky, but there are some rules
-that ensure a safe usage.
-.
-.IP 1.
-Printable backslashes must be denoted as
-.esc e .
-To be more precise,
-.esc e
-represents the current escape character.
-.
-To get a backslash glyph, use
-.esc (rs
-or
-.esc [rs] .
-.IP 2.
-Double all backslashes.
-.IP 3.
-Begin all text lines with the non-printing input break
-.esc & .
-.
-.
-.P
-This does not produce the most efficient code, but it should work as a
-first measure.
-.
-For better strategies, see the
-.I groff
-Texinfo manual and
-.BR groff_tmac (@MAN5EXT@).
-.
-.
-.P
-Reading roff source files is easier, just reduce all double backslashes
-to a single one in all macro definitions.
-.
-.
.\" ====================================================================
.SH "\f[I]groff\f[] elements"
.\" ====================================================================
@@ -5256,6 +5210,76 @@ Texinfo manual for further details.
.
.
.\" ====================================================================
+.SH "Copy mode"
+.\" ====================================================================
+.
+When
+.I \%@g@troff
+processes certain requests,
+most importantly those which define or append to a macro,
+string,
+or diversion,
+it does so in
+.IR "copy mode" :
+it copies the characters of the definition into a dedicated storage
+region,
+interpolating the escape sequences
+.esc n ,
+.esc g ,
+.esc $ ,
+.esc * ,
+and
+.esc V
+normally;
+interpreting
+.esc .\&
+and
+.BI \[rs] newline
+immediately;
+discarding comments
+.esc "
+and
+.esc # ;
+interpolating the current leader,
+escape,
+or tab character with
+.esc a ,
+.esc e
+or
+.esc E ,
+and
+.esc t ,
+respectively;
+and storing all other escape sequences in an encoded form.
+.
+See section \[lq]Character Translations\[rq] of the
+.I groff
+Texinfo manual
+for more on the use of
+.esc e
+and
+.esc E ,
+and the distinction between them.
+.
+.
+.P
+Since the escape character escapes itself,
+you can control whether any escape sequence is interpreted at macro
+definition time or when it is later interpolated by preceding it with an
+additional instance of the escape character.
+.
+The complement of copy mode\[em]a
+.I roff
+formatter's behavior when not defining or appending to a macro,
+string,
+or diversion\[em]where all macros are interpolated,
+requests invoked,
+and valid escape sequences processed immediately upon recognition,
+can be termed
+.IR "interpretation mode" .
+.
+.
+.\" ====================================================================
.SH Traps
.\" ====================================================================
.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 14/18: groff(7): Add "Copy mode" section.,
G. Branden Robinson <=