[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 02/15: doc/pic.ms (PIC Error Messages): Update.
From: |
G. Branden Robinson |
Subject: |
[groff] 02/15: doc/pic.ms (PIC Error Messages): Update. |
Date: |
Wed, 11 Aug 2021 17:04:02 -0400 (EDT) |
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 02/15: doc/pic.ms (PIC Error Messages): Update.,
G. Branden Robinson <=