* doc/groff.texinfo: Add another example for .em request

Based on a patch from Anton Shepelev <anton.txt@gmail.com>.

2 files changed, 32 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index dfa41c0b..11e00770 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2011-02-14  Werner LEMBERG  <wl@gnu.org>
+
+	* doc/groff.texinfo: Add another example for .em request
+	Based on a patch from Anton Shepelev <anton.txt@gmail.com>.
+
 2011-01-31  Werner LEMBERG  <wl@gnu.org>
 
 	More fixes for Savannah bug #32301.
diff --git a/doc/groff.texinfo b/doc/groff.texinfo
index 941095fe..bc2cba72 100644
--- a/doc/groff.texinfo
+++ b/doc/groff.texinfo
@@ -12676,6 +12676,33 @@ line three
 Note that this specific feature affects only the first potential page
 break caused by the end macro; further page breaks emitted by the end
 macro are handled normally.
+
+Another possible use of the @code{em} request is to make @code{gtroff}
+emit a single large page instead of multiple pages.  For example, one
+may want to produce a long plain-text file for reading on-screen.  The
+idea is to set the page length at the beginning of the document to a
+very large value to hold all the text, and automatically adjust it to
+the exact height of the document after the text has been output.
+
+@Example
+.de adjust-page-length
+.  br
+.  pl \\n[nl]u   \" \n[nl] holds the current page length
+..
+.
+.de single-page-mode
+.  pl 99999
+.  em adjust-page-length
+..
+.
+.\" activate the above code
+.single-page-mode
+@endExample
+
+Since only one end-of-input trap does exist and other macro packages
+may already use it, care must be taken not to break the mechanism.  A
+simple solution would be to append the above macro to the macro
+package's end-of-input macro using the @code{.am} request.
 @endDefreq