From 94aa325325dc02da6b1c09e31baca5e27013464a Mon Sep 17 00:00:00 2001
From: Werner LEMBERG <wl@gnu.org>
Date: Sun, 28 Sep 2008 14:39:44 +0000
Subject: [PATCH] If a macro is called as a string, inherit value of \n[.br]
 from the caller.  This is useful for `trace.tmac'.

* src/roff/troff/input.cpp (string_iterator): New members
`with_break' and `get_break_flag'.
(string_iterator::string_iterator): Updated.

* doc/groff.texinfo: Improve documentation of \$0 and string syntax
calling of macros.
Document behaviour of \n[.br] within strings.
---
 ChangeLog                | 13 ++++++++++
 doc/groff.texinfo        | 63 +++++++++++++++++++++++++++++++++++++++++-------
 src/roff/troff/input.cpp |  6 ++++-
 3 files changed, 72 insertions(+), 10 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index d319805d..7664678b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,16 @@
+2008-09-28  Werner LEMBERG  <wl@gnu.org>
+
+	If a macro is called as a string, inherit value of \n[.br] from the
+	caller.  This is useful for `trace.tmac'.
+
+	* src/roff/troff/input.cpp (string_iterator): New members
+	`with_break' and `get_break_flag'.
+	(string_iterator::string_iterator): Updated.
+
+	* doc/groff.texinfo: Improve documentation of \$0 and string syntax
+	calling of macros.
+	Document behaviour of \n[.br] within strings.
+
 2008-09-26  Werner LEMBERG  <wl@gnu.org>
 
 	* tmac/trace.tmac: Add copyright message.
diff --git a/doc/groff.texinfo b/doc/groff.texinfo
index 6a201c36..b5912abb 100644
--- a/doc/groff.texinfo
+++ b/doc/groff.texinfo
@@ -5447,6 +5447,9 @@ This allows to reliably modify requests.
 
 Using this register outside of a macro makes no sense (it always returns
 zero in such cases).
+
+If a macro is called as a string (this is, using @code{\*}), the value
+of the @code{.br} register is inherited from the calling macro.
 @endDefreg
 
 @menu
@@ -5549,7 +5552,7 @@ Use the double quote glyph @code{\(dq}.  This works with and without
 compatibility mode enabled since @code{gtroff} doesn't convert
 @code{\(dq} back to a double quote input character.
 
-Not that this method won't work with @acronym{UNIX} @code{troff} in
+Note that this method won't work with @acronym{UNIX} @code{troff} in
 general since the glyph `dq' isn't defined normally.
 @end itemize
 
@@ -10419,6 +10422,24 @@ This is
     @result{} This is a funny test.
 @endExample
 
+In particular, interpolating a string does not hide existing macro
+arguments.  Thus in a macro, a more efficient way of doing
+
+@Example
+.xx \\$@@
+@endExample
+
+@noindent
+is
+
+@Example
+\\*[xx]\\
+@endExample
+
+@noindent
+Note that the latter calling syntax doesn't change the value of
+@code{\$0}, which is then inherited from the calling macro.
+
 Diversions and boxes can be also called with string syntax.
 
 Another consequence is that you can copy one-line diversions or boxes to
@@ -10947,6 +10968,7 @@ restarting the next iteration.
 
 A @dfn{macro} is a collection of text and embedded commands which can be
 invoked multiple times.  Use macros to define common operations.
+@xref{Strings}, for a (limited) alternative syntax to call macros.
 
 @DefreqList {de, name [@Var{end}]}
 @DefreqItem {de1, name [@Var{end}]}
@@ -11251,17 +11273,40 @@ which redefines some requests and macros for debugging purposes.
 The name used to invoke the current macro.  The @code{als} request can
 make a macro have more than one name.
 
+If a macro is called as a string (within another macro), the value of
+@code{\$0} isn't changed.
+
 @Example
-.de generic-macro
-.  ...
-.  if \\n[error] \@{\
-.    tm \\$0: Houston, we have a problem.
-.    return
-.  \@}
+.de foo
+.  tm \\$0
+..
+.als foo bar
+.
+@endExample
+@Example
+.de aaa
+.  foo
+..
+.de bbb
+.  bar
+..
+.de ccc
+\\*[foo]\\
+..
+.de ddd
+\\*[bar]\\
 ..
 .
-.als foo generic-macro
-.als bar generic-macro
+@endExample
+@Example
+.aaa
+    @result{} foo
+.bbb
+    @result{} bar
+.ccc
+    @result{} ccc
+.ddd
+    @result{} ddd
 @endExample
 @endDefesc
 
diff --git a/src/roff/troff/input.cpp b/src/roff/troff/input.cpp
index 58e576b4..5605b232 100644
--- a/src/roff/troff/input.cpp
+++ b/src/roff/troff/input.cpp
@@ -3373,15 +3373,17 @@ class string_iterator : public input_iterator {
   int count;			// of characters remaining
   node *nd;
   int saved_compatible_flag;
+  int with_break;		// inherited from the caller
 protected:
   symbol nm;
   string_iterator();
 public:
-  string_iterator(const macro &m, const char *p = 0, symbol s = NULL_SYMBOL);
+  string_iterator(const macro &, const char * = 0, symbol = NULL_SYMBOL);
   int fill(node **);
   int peek();
   int get_location(int, const char **, int *);
   void backtrace();
+  int get_break_flag() { return with_break; }
   void save_compatible_flag(int f) { saved_compatible_flag = f; }
   int get_compatible_flag() { return saved_compatible_flag; }
   int is_diversion();
@@ -3402,6 +3404,7 @@ string_iterator::string_iterator(const macro &m, const char *p, symbol s)
     nd = 0;
     ptr = eptr = 0;
   }
+  with_break = input_stack::get_break_flag();
 }
 
 string_iterator::string_iterator()
@@ -3413,6 +3416,7 @@ string_iterator::string_iterator()
   how_invoked = 0;
   lineno = 1;
   count = 0;
+  with_break = input_stack::get_break_flag();
 }
 
 int string_iterator::is_diversion()
-- 
2.11.4.GIT