[Groff-commit] groff ChangeLog doc/groff.texinfo

[Werner LEMBERG]

CVSROOT:        /cvsroot/groff
Module name:    groff
Changes by:     Werner LEMBERG <wl>     09/04/14 11:10:38

Modified files:
        .              : ChangeLog 
        doc            : groff.texinfo 

Log message:
        Fix documentation of `em' request.
        Reported by Joachim Walsdorff
        <address@hidden>.
        
        * doc/groff.texinfo (End-of-input Traps): Rewrite.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/groff/ChangeLog?cvsroot=groff&r1=1.1201&r2=1.1202
http://cvs.savannah.gnu.org/viewcvs/groff/doc/groff.texinfo?cvsroot=groff&r1=1.284&r2=1.285

Patches:
Index: ChangeLog
===================================================================
RCS file: /cvsroot/groff/groff/ChangeLog,v
retrieving revision 1.1201
retrieving revision 1.1202
diff -u -b -r1.1201 -r1.1202
--- ChangeLog   10 Apr 2009 18:13:29 -0000      1.1201
+++ ChangeLog   14 Apr 2009 11:10:36 -0000      1.1202
@@ -1,3 +1,11 @@
+2009-04-14  Werner LEMBERG  <address@hidden>
+
+       Fix documentation of `em' request.
+       Reported by Joachim Walsdorff
+       <address@hidden>.
+
+       * doc/groff.texinfo (End-of-input Traps): Rewrite.
+
 2009-04-10  Werner LEMBERG  <address@hidden>
 
        Fix a memory leak in troff for -Thtml.

Index: doc/groff.texinfo
===================================================================
RCS file: /cvsroot/groff/groff/doc/groff.texinfo,v
retrieving revision 1.284
retrieving revision 1.285
diff -u -b -r1.284 -r1.285
--- doc/groff.texinfo   21 Feb 2009 07:40:22 -0000      1.284
+++ doc/groff.texinfo   14 Apr 2009 11:10:38 -0000      1.285
@@ -12409,8 +12409,9 @@
 
 @Example
 .de approval
-.  ne 5v
-.  sp |(\\n[.t] - 6v)
+\c
+.  ne 3v
+.  sp (\\n[.t]u - 3v)
 .  in +4i
 .  lc _
 .  br
@@ -12421,6 +12422,56 @@
 .
 .em approval
 @endExample
+
+The @code{\c} in the above example needs explanation.  For historical
+reasons (and for compatibility with @acronym{AT&T} @code{troff}), the
+end macro exits as soon as it causes a page break and no remaining
+data is in the partially collected line.
+
+Let us assume that there is no @code{\c} in the above @code{approval}
+macro, and that the page is full and has been ended with, say, a
address@hidden request.  The @code{ne} request now causes the start of a new
+page, which in turn makes @code{troff} exit immediately for the reasons
+just described.  In most situations this is not intended.
+
+To always force processing the whole end macro independently of this
+behaviour it is thus advisable to insert something which starts an
+empty partially filled line (@code{\c}) whenever there is a chance that
+a page break can happen.  In the above example, the call of the
address@hidden request assures that the remaining code stays on the same
+page, so we have to insert @code{\c} only once.
+
+The next example shows how to append three lines, then starting a new
+page unconditionally.  Since @address@hidden 1}} doesn't give the desired
+effect -- there is always one line available or we are already at the
+beginning of the next page -- we temporarily increase the page length
+by one line so that we can use @address@hidden 2}}.
+
address@hidden
+.de EM
+.pl +1v
+\c
+.ne 2
+line one
+.br
+\c
+.ne 2
+line two
+.br
+\c
+.ne 2
+line three
+.br
+.pl -1v
+\c
+'bp
+..
+.em EM
address@hidden
+
+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.
 @endDefreq