[groff] 01/17: pic(1): Improve PF support and documentation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit cbab3f3cec56c7e2a942902da46e6e86a3db41f9
Author: Dave Kemper <saint.snit@gmail.com>
AuthorDate: Tue Jun 1 09:06:29 2021 +0000

    pic(1): Improve PF support and documentation.
    
    GNU pic recognizes two possible endings of a pic block: .PE or .PF.
    This fact was documented in doc/pic.ms but not in the pic man page.  The
    minimal pic implementation provided by pic.tmac also did not include a
    .PF definition.
    
    * src/preproc/pic/main.cpp (main): Add dummy definition of `PF` macro.
    * tmac/pic.tmac (PF): Add macro that performs indentation only.
      (PE): Call PF for indentation.
    
    * doc/pic.ms (Interface to [gt]roff/How Scaling is Handled):
    * src/preproc/pic/pic.1.man (Description, Options): Mention `PF` in
      addition to `PS` and `PE`.
    
    Fixes <https://savannah.gnu.org/bugs/?60504>.
    
    Also fixes an extraneous parenthesis in pic.ms.
    
    [Changes to pic(1) hand-merged with my recent updates to the page text.
    --GBR]
---
 ChangeLog                 | 18 ++++++++++++++++++
 doc/pic.ms                | 10 +++++-----
 src/preproc/pic/main.cpp  |  3 ++-
 src/preproc/pic/pic.1.man | 30 ++++++++++++++++++++++--------
 tmac/pic.tmac             |  5 ++++-
 5 files changed, 51 insertions(+), 15 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 8ff7512..5cde9c1 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,21 @@
+2021-08-06  Dave Kemper <saint.snit@gmail.com>
+
+       GNU pic recognizes two possible endings of a pic block: .PE or
+       .PF.  This fact was documented in doc/pic.ms but not in the pic
+       man page.  The minimal pic implementation provided by pic.tmac
+       also did not include a .PF definition.
+
+       * src/preproc/pic/main.cpp (main): Add dummy definition of `PF`
+       macro.
+       * tmac/pic.tmac (PF): Add macro that performs indentation only.
+       (PE): Call PF for indentation.
+
+       * doc/pic.ms (Interface to [gt]roff/How Scaling is Handled):
+       * src/preproc/pic/pic.1.man (Description, Options): Mention `PF`
+       in addition to `PS` and `PE`.
+
+       Fixes <https://savannah.gnu.org/bugs/?60504>.
+
 2021-08-05  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * tmac/refer-ms.tmac:
diff --git a/doc/pic.ms b/doc/pic.ms
index 22588ec..cfe3db3 100644
--- a/doc/pic.ms
+++ b/doc/pic.ms
@@ -2150,7 +2150,7 @@ With two non-zero arguments, it scales to the maximum 
height.
 How Scaling is Handled
 .PP
 When \fBpic\fP processes a picture description on input, it passes
-\fB.PS\fP and \fB.PE\fP through to the postprocessor.
+\fB.PS\fP, \fB.PE\fP, and \fB.PF\fP through to the postprocessor.
 The \fB.PS\fP gets decorated with two numeric arguments which are the X
 and Y\~dimensions of the picture in inches.
 The post-processor can use these to reserve space for the picture and
@@ -2182,9 +2182,9 @@ the following definitions:
 .vs
 .KE
 .LP
-Equivalent definition is supplied by GNU \fIpic\/\fP(1) if you use
-the \-mpic option; this should make it usable with macro pages other
-than \fIms\/\fR(1).
+Equivalent definitions of these and of \fB.PF\fP are supplied by GNU
+\fIpic\/\fP(1) if you use the \-mpic option; this should make it usable
+with macro pages other than \fIms\/\fR(1).
 .PP
 If \fB.PF\fP is used instead of \fB.PE\fP, the \fBtroff\fP position is
 restored to what it was at the picture start (Kernighan notes that
@@ -2196,7 +2196,7 @@ The invocation
 .DE
 .LP
 causes the contents of \fIfile\fP to replace the \fB.PS\fP line.
-This feature is deprecated; use `\fBcopy\fP \fIfile\fR' instead).
+This feature is deprecated; use `\fBcopy\fP \fIfile\fR' instead.
 .
 .NH 2
 PIC and [gt]roff commands
diff --git a/src/preproc/pic/main.cpp b/src/preproc/pic/main.cpp
index 34f81f1..7c6be9a 100644
--- a/src/preproc/pic/main.cpp
+++ b/src/preproc/pic/main.cpp
@@ -621,7 +621,8 @@ int main(int argc, char **argv)
   {
     out = make_troff_output();
     printf(".do if !dPS .ds PS\n"
-          ".do if !dPE .ds PE\n");
+          ".do if !dPE .ds PE\n"
+          ".do if !dPF .ds PF\n");
   }
 #ifdef FIG_SUPPORT
   if (whole_file_flag) {
diff --git a/src/preproc/pic/pic.1.man b/src/preproc/pic/pic.1.man
index 0a6b9f3..3d410f9 100644
--- a/src/preproc/pic/pic.1.man
+++ b/src/preproc/pic/pic.1.man
@@ -101,10 +101,21 @@ It copies the contents of each
 to the standard output stream,
 except that lines between
 .B .PS
-and
+and either
 .B .PE
+or
+.B .PF
 are interpreted as picture descriptions.
 .
+Ending a
+.I \%@g@pic
+picture with
+.B .PE
+leaves the page position at the bottom of the picture;
+ending it with
+.B .PF
+leaves the position at the top.
+.
 Normally,
 .I \%@g@pic
 is not executed directly by the user,
@@ -126,9 +137,10 @@ the standard input stream is read.
 .LP
 It is the user's responsibility to provide appropriate definitions
 of the
-.B PS
+.BR PS ,
+.BR PE ,
 and
-.B PE
+.B PF
 macros.
 .
 When the macro package being used does not supply such definitions
@@ -136,7 +148,7 @@ When the macro package being used does not supply such 
definitions
 old versions of \-ms),
 appropriate definitions can be
 obtained with
-.BR \-mpic :
+.BR \-mpic ;
 these will center each picture.
 .
 .
@@ -193,9 +205,10 @@ variable.
 .TP
 .B \-C
 Recognize
-.B .PS
+.BR .PS ,
+.BR .PE ,
 and
-.B .PE
+.B .PF
 even when followed by a character other than space or newline.
 .
 .
@@ -1432,9 +1445,10 @@ package.
 .TP
 .I @MACRODIR@/pic.tmac
 Example definitions of the
-.B PS
+.BR PS ,
+.BR PE ,
 and
-.B PE
+.B PF
 macros.
 .
 .
diff --git a/tmac/pic.tmac b/tmac/pic.tmac
index 217b7d8..6bbe874 100644
--- a/tmac/pic.tmac
+++ b/tmac/pic.tmac
@@ -8,8 +8,11 @@
 .ne 0\\$1+1v+\n(.Vu
 .in \\n(.lu-\\n(.iu-0\\$2/2u>?0
 ..
-.de PE
+.de PF
 .in
+..
+.de PE
+.PF
 .sp .3v+.5m
 ..
 .