[groff] 08/11: [mdoc]: Improve diagnostic message format (2/4).

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 7271313941d567bebd4cc41f6e73e89e5fe830eb
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Mar 12 15:52:45 2024 -0500

    [mdoc]: Improve diagnostic message format (2/4).
    
    * tmac/doc.tmac (doc-err): Add internal macro for reporting error
      diagnostics.  Arrange message per GNU Coding Standards, including
      report of input filename.
      (It, doc-fo-func-args, Fo, Fc, %V, Lk, doc-defunct-macro): Use it.
    
    See <https://www.gnu.org/prep/standards/standards.html#Errors>.
---
 ChangeLog     | 10 ++++++++++
 tmac/doc.tmac | 26 ++++++++++++++------------
 2 files changed, 24 insertions(+), 12 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 9fcaf83f1..9730c04db 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2024-03-12  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [mdoc]: Improve diagnostic message format (2/4).
+
+       * tmac/doc.tmac (doc-err): Add internal macro for reporting
+       error diagnostics.  Arrange message per GNU Coding Standards,
+       including report of input filename.
+       (It, doc-fo-func-args, Fo, Fc, %V, Lk, doc-defunct-macro): Use
+       it.
+
 2024-03-12  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [mdoc]: Improve diagnostic message format (1/4).
diff --git a/tmac/doc.tmac b/tmac/doc.tmac
index 45f12cda5..7424c86d6 100644
--- a/tmac/doc.tmac
+++ b/tmac/doc.tmac
@@ -64,6 +64,10 @@
 .  ab \*[doc-msg]
 .\}
 .
+.de doc-err
+.  tm \*[doc]:\\n[.F]:\\n[.c]: error: \\$*
+..
+.
 .\" Handle most rendering options.
 .
 .\" We don't have to worry about "xhtml" (it's mapped to "html"), but we
@@ -4024,12 +4028,10 @@
 .  ds doc-str-It \*[doc-list-type-stack\n[doc-list-depth]]
 .
 .  if "\*[doc-str-It]"" \
-.    tm mdoc error: .It without preceding .Bl (#\n[.c])
+.    doc-err .It without preceding .Bl
 .
-.  if \n[doc-nesting-level] \{\
-.    tmc "mdoc error: .It found in enclosing (e.g. .Ac ... .It ... .Ao)
-.    tm1 " (#\n[.c])
-.  \}
+.  if \n[doc-nesting-level] \
+.    doc-err .It found in enclosing (e.g. .Ac ... .It ... .Ao)
 .
 .  br
 .  if !\n[cR] \
@@ -5428,7 +5430,7 @@
 .eo
 .de Fo
 .  if (\n[doc-in-func-enclosure]) \{\
-.    tm mdoc error: .Fo/.Fc can't be nested (#\n[.c])
+.    doc-err .Fo/.Fc can't be nested
 .    return
 .  \}
 .
@@ -5513,7 +5515,7 @@
 .eo
 .de Fc
 .  if !\n[doc-in-func-enclosure] \{\
-.    tm mdoc warning: Extraneous .Fc (#\n[.c])
+.    doc-err extraneous .Fc
 .    return
 .  \}
 .
@@ -5524,7 +5526,7 @@
 .  \}
 .
 .  if !(\n[doc-saved-nesting-level] == \n[doc-nesting-level]) \
-.    tm mdoc warning: Unbalanced enclosure commands within .Fo/.Fc
+.    doc-err unbalanced enclosure commands within .Fo/.Fc
 .
 .  nr doc-func-arg-count 0
 .  nr doc-in-func-enclosure 0
@@ -6720,7 +6722,7 @@
 .eo
 .de doc-do-references
 .  if !\n[doc-is-reference] \
-.    tm mdoc error: .\*[doc-macro-name] found outside of .Rs ... .Re (#\n[.c])
+.    doc-err .\*[doc-macro-name] found outside of .Rs ... .Re
 .
 .  nr doc-reg-ddr1 \n[doc-type\n[doc-arg-ptr]]
 .
@@ -7148,7 +7150,7 @@
 .
 .eo
 .de doc-defunct-macro
-.  tmc mdoc error: .\$0 defunct
+.  doc-err .\$0 defunct
 .  if d doc-\$0-usage \
 .    tmc , \*[doc-\$0-usage]
 .  tm1 " (#\n[.c])
@@ -7173,8 +7175,8 @@
 .
 .eo
 .de em
-.  tm1 "mdoc error: end-macro (.em) respecification is not allowed. (#\n[.c])
-.  tm1 "            Should this have been '.Em ...'?
+.  doc-err end-macro (.em) respecification is not allowed; \
+should this have been '.Em ...'?
 .  ab
 ..
 .ec