[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 10/11: [mdoc]: Improve diagnostic message format (4/4).
|
From: |
G. Branden Robinson |
|
Subject: |
[groff] 10/11: [mdoc]: Improve diagnostic message format (4/4). |
|
Date: |
Wed, 13 Mar 2024 16:16:26 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit 6a6d17fc23d09e71bbd24e8e376907b800b46d0d
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Mar 12 16:07:04 2024 -0500
[mdoc]: Improve diagnostic message format (4/4).
* tmac/doc.tmac (doc-report-usage): Add internal macro for reporting
usage error diagnostics. Arrange message per GNU Coding Standards,
including report of input filename.
* tmac/doc.tmac (doc-generic-macro, Cd, Fd, In, Nm, Tn, Ns, Ap, Bf, Ek)
(El, doc-Xr-usage, doc-column-list, Dl, D1, Vt, Ft, Fa, Fn, Fo, Rs)
(Re, %A, %B, %C, %D, %I, %J, %N, %O, %P, %Q, %R, %T, %U, %V, An, Rv)
(Ex, doc-Mt-usage, doc-Lk-usage):
* tmac/mdoc/doc-common (Sh, Ss):
* tmac/mdoc/doc-ditroff (Ql):
* tmac/mdoc/doc-nroff (Ql):
* tmac/mdoc/doc-syms (Lb): Use it.
Fixes <https://savannah.gnu.org/bugs/?52463> (at long last).
See <https://www.gnu.org/prep/standards/standards.html#Errors>.
---
ChangeLog | 19 ++++++++
tmac/doc.tmac | 118 ++++++++++++++++++++++++++------------------------
tmac/mdoc/doc-common | 12 ++---
tmac/mdoc/doc-ditroff | 2 +-
tmac/mdoc/doc-nroff | 2 +-
tmac/mdoc/doc-syms | 4 +-
6 files changed, 91 insertions(+), 66 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 40ae25afa..5502e8213 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,22 @@
+2024-03-12 G. Branden Robinson <g.branden.robinson@gmail.com>
+
+ [mdoc]: Improve diagnostic message format (4/4).
+
+ * tmac/doc.tmac (doc-report-usage): Add internal macro for
+ reporting usage error diagnostics. Arrange message per GNU
+ Coding Standards, including report of input filename.
+
+ * tmac/doc.tmac (doc-generic-macro, Cd, Fd, In, Nm, Tn, Ns, Ap)
+ (Bf, Ek, El, doc-Xr-usage, doc-column-list, Dl, D1, Vt, Ft, Fa)
+ (Fn, Fo, Rs, Re, %A, %B, %C, %D, %I, %J, %N, %O, %P, %Q, %R, %T)
+ (%U, %V, An, Rv, Ex, doc-Mt-usage, doc-Lk-usage):
+ * tmac/mdoc/doc-common (Sh, Ss):
+ * tmac/mdoc/doc-ditroff (Ql):
+ * tmac/mdoc/doc-nroff (Ql):
+ * tmac/mdoc/doc-syms (Lb): Use it.
+
+ Fixes <https://savannah.gnu.org/bugs/?52463> (at long last).
+
2024-03-12 G. Branden Robinson <g.branden.robinson@gmail.com>
[mdoc]: Improve diagnostic message format (3/4).
diff --git a/tmac/doc.tmac b/tmac/doc.tmac
index 64474c775..595632672 100644
--- a/tmac/doc.tmac
+++ b/tmac/doc.tmac
@@ -72,6 +72,12 @@
. tm \*[doc]:\\n[.F]:\\n[.c]: warning: \\$*
..
.
+.\" XXX: Report "commands" with leading dot before macro name?
+.\" XXX: Omit ellipsis from usage of macros that aren't "parsed"?
+.de doc-report-usage
+. tm \*[doc]:\\n[.F]:\\n[.c]: usage: \\$* ...
+..
+.
.\" Handle most rendering options.
.
.\" We don't have to worry about "xhtml" (it's mapped to "html"), but we
@@ -757,7 +763,7 @@
. doc-parse-args \$@
. \}
. el \
-. tm Usage: .\$0 \*[doc-\$0-usage] ... (#\n[.c])
+. doc-report-usage .\$0 \*[doc-\$0-usage] ...
. \}
.
. if !\n[doc-arg-count] \
@@ -783,7 +789,7 @@
.\" \}
. \}
. el \{\
-. tm Usage: .\$0 \*[doc-\$0-usage] ... (#\n[.c])
+. doc-report-usage .\$0 \*[doc-\$0-usage] ...
. doc-reset-args
. \}
..
@@ -889,7 +895,7 @@
. doc-parse-args \$@
. \}
. el \
-. tm Usage: .Cd configuration_file_declaration ... (#\n[.c])
+. doc-report-usage .Cd configuration_file_declaration ...
. \}
.
. if !\n[doc-arg-count] \
@@ -921,7 +927,7 @@
. doc-print-recursive
. \}\}
. el \{\
-. tm Usage: .Cd configuration_file_declaration ... (#\n[.c])
+. doc-report-usage .Cd configuration_file_declaration ...
. doc-reset-args
. \}
..
@@ -1035,7 +1041,7 @@
. ft \n[doc-curr-font]
. \}
. el \{\
-. tm Usage: .Fd function_declaration -- Fd is not callable (#\n[.c])
+. doc-report-usage .Fd function_declaration -- Fd is not callable
. doc-reset-args
. \}
..
@@ -1064,7 +1070,7 @@
. doc-parse-args \$@
. \}
. el \
-. tm Usage: .In include_file ... (#\n[.c])
+. doc-report-usage .In include_file ...
. \}
.
. if !\n[doc-arg-count] \
@@ -1098,7 +1104,7 @@
. doc-print-recursive
. \}\}
. el \{\
-. tm Usage: .In include_file ... (#\n[.c])
+. doc-report-usage .In include_file ...
. doc-reset-args
. \}
..
@@ -1182,7 +1188,7 @@
. \}
. el \{\
. ie "\*[doc-topic-name]"" \
-. tm Usage: .Nm name ... (#\n[.c])
+. doc-report-usage .Nm name ...
. el \
. doc-parse-args \*[doc-topic-name]
. \}\}
@@ -1195,7 +1201,7 @@
. ie (\n[doc-arg-count] < \n[doc-arg-ptr]) \{\
. \" last argument
. ie "\*[doc-topic-name]"" \{\
-. tm Usage: .Nm name ... (#\n[.c])
+. doc-report-usage .Nm name ...
. doc-reset-args
. \}
. el \{\
@@ -1207,7 +1213,7 @@
.
. ie !(\n[doc-type\n[doc-arg-ptr]] == 2) \{\
. ie "\*[doc-topic-name]"" \
-. tm Usage: .Nm name ... (#\n[.c])
+. doc-report-usage .Nm name ...
. el \{\
. \" replace previous argument (Nm) with default value
. nr doc-arg-ptr -1
@@ -1331,7 +1337,7 @@
. doc-parse-args \$@
. \}
. el \
-. tm Usage: .Tn trade_name ... (#\n[.c])
+. doc-report-usage .Tn trade_name ...
. \}
.
. if !\n[doc-arg-count] \
@@ -1349,7 +1355,7 @@
. doc-do-references
. \}
. el \{\
-. tm Usage: .Tn trade_name ... (#\n[.c])
+. doc-report-usage .Tn trade_name ...
. doc-reset-args
. \}
..
@@ -2356,7 +2362,7 @@
. doc-parse-args \$@
. \}
. el \
-. tm Usage: .Ns must be called with arguments (#\n[.c])
+. doc-report-usage .Ns must be called with arguments
. \}
.
. if \n[doc-arg-count] \{\
@@ -2378,7 +2384,7 @@
.eo
.de Ap
. ie !\n[doc-arg-count] \
-. tm Usage: 'Ap' cannot be first macro on a line (no '.Ap') (#\n[.c])
+. doc-report-usage 'Ap' cannot be first macro on a line (no '.Ap')
. el \{\
. nop \)'\)\c
. nr doc-arg-ptr +1
@@ -2818,7 +2824,7 @@
. doc-warn unknown keyword '\$1' in .Bf macro
. \}\}\}\}\}\}\}
. el \
-. tm Usage: .Bf [Em | -emphasis | Li | -literal | Sy | -symbolic] (#\n[.c])
+. doc-report-usage .Bf [Em | -emphasis | Li | -literal | Sy | -symbolic]
..
.ec
.
@@ -2912,7 +2918,7 @@
\#. nr doc-nesting-level -1
.
. ie \n[.$] \
-. tm Usage: .Ek (does not take arguments) (#\n[.c])
+. doc-report-usage .Ek (does not take arguments)
. el \{\
. if !\n[doc-keep-type] \
. doc-warn .Ek found without .Bk before
@@ -3950,7 +3956,7 @@ macro
.eo
.de El
. if \n[.$] \{\
-. tm Usage: .El (does not take arguments) (#\n[.c])
+. doc-report-usage .El (does not take arguments)
. return
. \}
.
@@ -4617,7 +4623,7 @@ arguments
.
.eo
.de doc-Xr-usage
-. tm Usage: .Xr manpage_name [section#] ... (#\n[.c])
+. doc-report-usage .Xr manpage_name [section#] ...
. doc-reset-args
..
.ec
@@ -4845,7 +4851,7 @@ arguments
. nr doc-arg-ptr +1
.
. if (\n[doc-arg-count] < \n[doc-arg-ptr]) \{\
-. tm Usage: .It column_string [Ta [column_string ...] ] (#\n[.c])
+. doc-report-usage .It column_string [Ta [column_string ...] ]
. return
. \}
.
@@ -4911,7 +4917,7 @@ arguments
. in +\n[doc-display-indent]u
.
. ie \n[doc-arg-count] \{\
-. tm Usage: .Dl not callable by other macros (#\n[.c])
+. doc-report-usage .Dl not callable by other macros
. doc-reset-args
. \}
. el \{\
@@ -4924,7 +4930,7 @@ arguments
. doc-print-recursive
. \}
. el \
-. tm Usage: .Dl argument ... (#\n[.c])
+. doc-report-usage .Dl argument ...
. \}
.
. in -\n[doc-display-indent]u
@@ -4947,7 +4953,7 @@ arguments
. in +\n[doc-display-indent]u
.
. ie \n[doc-arg-count] \{\
-. tm Usage: .D1 not callable by other macros (#\n[.c])
+. doc-report-usage .D1 not callable by other macros
. doc-reset-args
. \}
. el \{\
@@ -4958,7 +4964,7 @@ arguments
. doc-print-recursive
. \}
. el \
-. tm Usage: .D1 argument ... (#\n[.c])
+. doc-report-usage .D1 argument ...
. \}
.
. in -\n[doc-display-indent]u
@@ -4987,7 +4993,7 @@ arguments
. doc-parse-args \$@
. \}
. el \
-. tm Usage: .Vt variable_type ... (#\n[.c])
+. doc-report-usage .Vt variable_type ...
. \}
.
. if !\n[doc-arg-count] \
@@ -4995,7 +5001,7 @@ arguments
.
. nr doc-arg-ptr +1
. if (\n[doc-arg-count] < \n[doc-arg-ptr]) \{\
-. tm Usage: .Vt variable_type ... (#\n[.c])
+. doc-report-usage .Vt variable_type ...
. doc-reset-args
. return
. \}
@@ -5059,7 +5065,7 @@ arguments
. doc-parse-args \$@
. \}
. el \
-. tm Usage: .Ft function_type ... (#\n[.c])
+. doc-report-usage .Ft function_type ...
. \}
.
. if !\n[doc-arg-count] \
@@ -5067,7 +5073,7 @@ arguments
.
. nr doc-arg-ptr +1
. if (\n[doc-arg-count] < \n[doc-arg-ptr]) \{\
-. tm Usage: .Ft function_type ... (#\n[.c])
+. doc-report-usage .Ft function_type ...
. doc-reset-args
. return
. \}
@@ -5155,7 +5161,7 @@ arguments
. doc-parse-args \$@
. \}
. el \
-. tm Usage: .Fa function_arguments ... (#\n[.c])
+. doc-report-usage .Fa function_arguments ...
. \}
.
. ie \n[doc-func-arg-count] \
@@ -5275,7 +5281,7 @@ arguments
. doc-parse-args \$@
. \}
. el \
-. tm Usage: .Fn function_name [function_arg] ... (#\n[.c])
+. doc-report-usage .Fn function_name [function_arg] ...
. \}
.
. if !\n[doc-arg-count] \
@@ -5320,7 +5326,7 @@ arguments
. nr doc-arg-ptr +1
. doc-print-prefixes
. if (\n[doc-arg-count] < \n[doc-arg-ptr]) \{\
-. tm Usage: .Fn function_name [function_arg] ... (#\n[.c])
+. doc-report-usage .Fn function_name [function_arg] ...
. doc-reset-args
. return
. \}
@@ -5445,7 +5451,7 @@ arguments
. doc-parse-args \$@
. \}
. el \
-. tm Usage: .Fo function_name (#\n[.c])
+. doc-report-usage .Fo function_name
. \}
.
. if \n[doc-in-synopsis-section] \{\
@@ -5630,7 +5636,7 @@ arguments
.eo
.de Rs
. ie \n[.$] \
-. tm Usage: .Rs (does not take arguments) (#\n[.c])
+. doc-report-usage .Rs (does not take arguments)
. el \{\
. nr doc-is-reference 1
. doc-reset-reference
@@ -5653,7 +5659,7 @@ arguments
.eo
.de Re
. ie \n[.$] \
-. tm Usage: .Re (does not take arguments) (#\n[.c])
+. doc-report-usage .Re (does not take arguments)
. el \{\
. if !\n[doc-is-reference] \{\
. doc-warn extraneous .Re
@@ -5945,7 +5951,7 @@ arguments
.eo
.de %A
. if (\n[doc-arg-count] : (\n[.$] == 0)) \{\
-. tm Usage: .%A author_name ... (#\n[.c])
+. doc-report-usage .%A author_name ...
. return
. \}
.
@@ -5999,7 +6005,7 @@ arguments
.eo
.de %B
. if (\n[doc-arg-count] : (\n[.$] == 0)) \{\
-. tm Usage: .%B book_name ... (#\n[.c])
+. doc-report-usage .%B book_name ...
. return
. \}
.
@@ -6062,7 +6068,7 @@ arguments
.eo
.de %C
. if (\n[doc-arg-count] : (\n[.$] == 0)) \{\
-. tm Usage: .%C city_name ... (#\n[.c])
+. doc-report-usage .%C city_name ...
. return
. \}
.
@@ -6116,7 +6122,7 @@ arguments
.eo
.de %D
. if (\n[doc-arg-count] : (\n[.$] == 0)) \{\
-. tm Usage: .%D date ... (#\n[.c])
+. doc-report-usage .%D date ...
. return
. \}
.
@@ -6170,7 +6176,7 @@ arguments
.eo
.de %I
. if (\n[doc-arg-count] : (\n[.$] == 0)) \{\
-. tm Usage: .%I issuer/publisher_name ... (#\n[.c])
+. doc-report-usage .%I issuer/publisher_name ...
. return
. \}
.
@@ -6225,7 +6231,7 @@ arguments
.eo
.de %J
. if (\n[doc-arg-count] : (\n[.$] == 0)) \{\
-. tm Usage: .%J journal_name ... (#\n[.c])
+. doc-report-usage .%J journal_name ...
. return
. \}
.
@@ -6280,7 +6286,7 @@ arguments
.eo
.de %N
. if (\n[doc-arg-count] : (\n[.$] == 0)) \{\
-. tm Usage: .%N issue_number ... (#\n[.c])
+. doc-report-usage .%N issue_number ...
. return
. \}
.
@@ -6334,7 +6340,7 @@ arguments
.eo
.de %O
. if (\n[doc-arg-count] : (\n[.$] == 0)) \{\
-. tm Usage: .%O optional_information ... (#\n[.c])
+. doc-report-usage .%O optional_information ...
. return
. \}
.
@@ -6388,7 +6394,7 @@ arguments
.eo
.de %P
. if (\n[doc-arg-count] : (\n[.$] == 0)) \{\
-. tm Usage: .%P page_number ... (#\n[.c])
+. doc-report-usage .%P page_number ...
. return
. \}
.
@@ -6442,7 +6448,7 @@ arguments
.eo
.de %Q
. if (\n[doc-arg-count] : (\n[.$] == 0)) \{\
-. tm Usage: .%Q corporate_or_foreign_author ... (#\n[.c])
+. doc-report-usage .%Q corporate_or_foreign_author ...
. return
. \}
.
@@ -6496,7 +6502,7 @@ arguments
.eo
.de %R
. if (\n[doc-arg-count] : (\n[.$] == 0)) \{\
-. tm Usage: .%R reference_report ... (#\n[.c])
+. doc-report-usage .%R reference_report ...
. return
. \}
.
@@ -6557,7 +6563,7 @@ arguments
.eo
.de %T
. if (\n[doc-arg-count] : (\n[.$] == 0)) \{\
-. tm Usage: .%T reference_title ... (#\n[.c])
+. doc-report-usage .%T reference_title ...
. return
. \}
.
@@ -6645,7 +6651,7 @@ arguments
.eo
.de %U
. if (\n[doc-arg-count] : (\n[.$] == 0)) \{\
-. tm Usage: .%U URL ... (#\n[.c])
+. doc-report-usage .%U URL ...
. return
. \}
.
@@ -6687,7 +6693,7 @@ arguments
.eo
.de %V
. if (\n[doc-arg-count] : (\n[.$] == 0)) \{\
-. tm Usage: .%V volume ... (#\n[.c])
+. doc-report-usage .%V volume ...
. return
. \}
.
@@ -6829,7 +6835,7 @@ arguments
. doc-print-recursive
. \}
. el \{\
-. tm Usage: .An author_name ... (#\n[.c])
+. doc-report-usage .An author_name ...
. doc-reset-args
. \}\}
..
@@ -6875,20 +6881,20 @@ arguments
.\" XXX: what does this function without '-std'?
.
. if \n[doc-arg-count] \{\
-. tm Usage: .Rv not callable by other macros (#\n[.c])
+. doc-report-usage .Rv not callable by other macros
. doc-reset-args
. return
. \}
.
. if !\n[.$] \{\
-. tm Usage: .Rv [-std] [<function> ...] (#\n[.c])
+. doc-report-usage .Rv [-std] [<function> ...]
. return
. \}
.
. if "\$1"-std" \{\
. nr doc-reg-Rv \*[doc-section]
. if ((\n[doc-reg-Rv] < 2) : (\n[doc-reg-Rv] > 3)) \
-. tm Usage: .Rv -std in sections 2 and 3 only (#\n[.c])
+. doc-report-usage .Rv -std in sections 2 and 3 only
. br
. shift
. ie (\n[.$] > 1) \{\
@@ -6941,20 +6947,20 @@ arguments
.\" XXX: what does this function without '-std'?
.
. if \n[doc-arg-count] \{\
-. tm Usage: .Ex not callable by other macros (#\n[.c])
+. doc-report-usage .Ex not callable by other macros
. doc-reset-args
. return
. \}
.
. if !\n[.$] \{\
-. tm Usage: .Ex [-std] [<utility> ...] (#\n[.c])
+. doc-report-usage .Ex [-std] [<utility> ...]
. return
. \}
.
. if "\$1"-std" \{\
. nr doc-reg-Ex \*[doc-section]
. if !((\n[doc-reg-Ex] == 1) : (\n[doc-reg-Ex] == 6) : (\n[doc-reg-Ex] ==
8)) \
-. tm Usage: .Ex -std in sections 1, 6 and 8 only (#\n[.c])
+. doc-report-usage .Ex -std in sections 1, 6 and 8 only
. br
. shift
. ie (\n[.$] > 1) \{\
@@ -6984,7 +6990,7 @@ arguments
.
.eo
.de doc-Mt-usage
-. tm Usage: .Mt email_address ... (#\n[.c])
+. doc-report-usage .Mt email_address ...
. doc-reset-args
..
.ec
@@ -7053,7 +7059,7 @@ arguments
.
.eo
.de doc-Lk-usage
-. tm Usage: .Lk uri [link_text ...] (#\n[.c])
+. doc-report-usage .Lk uri [link_text ...]
. doc-reset-args
..
.ec
diff --git a/tmac/mdoc/doc-common b/tmac/mdoc/doc-common
index a840cf54e..91ffcedb9 100644
--- a/tmac/mdoc/doc-common
+++ b/tmac/mdoc/doc-common
@@ -1411,16 +1411,16 @@
. doc-print-recursive
. \}
. el \{\
-. tm Usage: .Sh section_name ... (#\n[.c])
+. doc-report-usage .Sh section_name ...
. doc-reset-args
. \}\}
. el \{\
-. tm Usage: .Sh not callable by other macros (#\n[.c])
+. doc-report-usage .Sh not callable by other macros
. doc-reset-args
. \}\}
. el \{\
. if !\n[.$] \{\
-. tm Usage: .Sh section_name ... (#\n[.c])
+. doc-report-usage .Sh section_name ...
. return
. \}
.
@@ -1541,16 +1541,16 @@
. doc-print-recursive
. \}
. el \{\
-. tm Usage: .Ss subsection_name ... (#\n[.c])
+. doc-report-usage .Ss subsection_name ...
. doc-reset-args
. \}\}
. el \{\
-. tm Usage: .Ss not callable by other macros (#\n[.c])
+. doc-report-usage .Ss not callable by other macros
. doc-reset-args
. \}\}
. el \{\
. if !\n[.$] \{\
-. tm Usage: .Ss subsection_name ... (#\n[.c])
+. doc-report-usage .Ss subsection_name ...
. return
. \}
.
diff --git a/tmac/mdoc/doc-ditroff b/tmac/mdoc/doc-ditroff
index 928c2b6da..56c6e60c7 100644
--- a/tmac/mdoc/doc-ditroff
+++ b/tmac/mdoc/doc-ditroff
@@ -217,7 +217,7 @@
. doc-parse-args \$@
. \}
. el \
-. tm Usage: .Ql argument ... (#\n[.c])
+. doc-report-usage .Ql argument ...
. \}
.
. nr doc-reg-Ql (\n[doc-arg-ptr] + 1)
diff --git a/tmac/mdoc/doc-nroff b/tmac/mdoc/doc-nroff
index aab8179d7..47d0d9946 100644
--- a/tmac/mdoc/doc-nroff
+++ b/tmac/mdoc/doc-nroff
@@ -197,7 +197,7 @@
. ie \n[.$] \
. ds doc-macro-name Ql
. el \
-. tm Usage: .Ql argument ... (#\n[.c])
+. doc-report-usage .Ql argument ...
. \}
.
. ds doc-quote-left "\*[doc-left-singlequote]
diff --git a/tmac/mdoc/doc-syms b/tmac/mdoc/doc-syms
index 8f5998c68..1f38513e5 100644
--- a/tmac/mdoc/doc-syms
+++ b/tmac/mdoc/doc-syms
@@ -865,7 +865,7 @@
. doc-parse-args \$@
. \}
. el \
-. tm Usage: .Lb library_name ... (#\n[.c])
+. doc-report-usage .Lb library_name ...
. \}
.
. if !\n[doc-arg-count] \
@@ -894,7 +894,7 @@
. br
. \}
. el \{\
-. tm Usage: .Lb library_name ... (#\n[.c])
+. doc-report-usage .Lb library_name ...
. doc-reset-args
. \}
..
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 10/11: [mdoc]: Improve diagnostic message format (4/4).,
G. Branden Robinson <=