[groff] 02/15: doc/pic.ms (PIC Error Messages): Update.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit cf0f73c637f92d34a8014ae1738cf59e7f79f851
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Aug 12 00:06:24 2021 +1000

    doc/pic.ms (PIC Error Messages): Update.
    
    * Update example error diagnostic to more closely resemble today's
      output.
    * Metavariablize the filename.  Not every error is going to be in pic.ms
      (indeed, we hope for zero in this document...).
    * Recast opening sentence to rely less on the reader's existing
      knowledge of the jargon "syntax error".
    * Bracket the whole subsection in a keep since it is very short and
      there is no natural place for a (non-awkward) page break within it.
    * Switch font families instead of using `CW` macro.
    * Use \[aq] special character instead of typographer's quotes in example
      diagnostic.
    * Use italic/oblique font instead of angle brackets (hiss, recoil).
    
    Pick the usual style nits.
    * Break input lines after commas.
    * Use an empty request between sentences.
    * Use two empty requests where vertical space is expected.
    
    The urge to exterminate these font escapes (especially the pre-groff,
    spell-check-ruining variety) is unbearable...
---
 doc/pic.ms | 39 ++++++++++++++++++++++++++++-----------
 1 file changed, 28 insertions(+), 11 deletions(-)

diff --git a/doc/pic.ms b/doc/pic.ms
index ed7b19e..5e9928d 100644
--- a/doc/pic.ms
+++ b/doc/pic.ms
@@ -144,23 +144,40 @@ The normal definitions of \fB.PS\fP and \fB.PE\fP in the 
\fIms\fP macro
 package and elsewhere have also the side-effect of centering the
 \fBpic\fP output on the page.
 .
+.KS
 .NH 2
 PIC Error Messages
 .PP
-If you make a \fBpic\fP syntax error, \fIgpic\/\fP(1) issues an
-error message in the standard \fIgcc\/\fP(1)-like syntax.
-A typical error message looks like this
-.KS
+If you make a mistake in \fBpic\fP input such that the program cannot
+interpret what you mean,
+\fIgpic\/\fP(1) issues a diagnostic message in the format prescribed by
+the GNU Coding Standards.
+.
+A typical error message looks like
+.
+.
+.ds FAM C
 .DS
-.CW
-pic:pic.ms:<nnn>: parse error before `<token>'
-pic:pic.ms:<nnn>: giving up on this picture
+pic:\fIfile\fP:\fInnn\fP: syntax error before \[aq]\fItoken\fP\[aq]
+pic:\fIfile\fP:\fInnn\fP: giving up on this picture
 .DE
-.R
-.KE
+.ds FAM T
+.
+.
 .LP
-where \[la]nnn\[ra] is a line number, and \[la]token\[ra] is a token near 
(usually
-just after) the error location.
+where
+.I file
+is the name of the file being processed,
+.I nnn
+is a line number within that file,
+and
+.I token
+is a symbol in the \fBpic\fP language
+(often a keyword)
+near
+(usually just after)
+the error location.
+.KE
 .
 .
 .NH 1