Description
Now that every message has been inventoried and binned into an appropriate category (not a lot of changes, but a necessary audit), and the message system is mostly very, very modular and flexible now, I'd like to propose some changes to enhance the granularity of messages that Tidy outputs. This will break existing diffs and introduce/deprecate some existing config options, but a little bit of pain brings a lot of consistency to Tidy's output.
From the old, closed #561:
The TidyInfo isn't used very much; perhaps it should be used a little bit more for cases like this, i.e., "silent changes" become TidyInfo messages that we can handle appropriately.
There are often issues raised about whether or not Tidy should emit or not emit a message based on silent changes, things we don't want to see, etc. Although @geoffmcl indicates that he added TidyInfo as a quick fix, I say, let's embrace this. If something isn't an error or warning, then it's appropriate to potentially output it as TidyInfo. For example, the new TidyShowMetaChange added an entire new option for whether or not to show this change as a TidyInfo message. While this is granular control, and this issue is about adding granular control, I think it would be sufficient to delete this option and simply count on hiding TidyInfo if the user doesn't want to see this level of message.
Also from #561:
- show-info will squelch any TidyInfo messages, but it also squelches some of the "dialogue-like" output that Tidy delivers (the new TidyDialogueInfo) category.
- show-warnings can be used to hide the warnings
- show-errors isn't a boolean, but places a limit to the amount of errors that will be output, and setting this to zero does squelch all errors. Now the thing about show-errors is that it only limits errors, not warnings or info. So if you set show-errors to, say, 10, but have 100 warnings, you'll still see all of them.
- If you're using a callback filter, none of these options have any effect, as it becomes the responsibility of the host program to implement all of this functionality.
Here's the current state of options that affect output:
| OptID | Option | Effect |
|---|---|---|
| TidyShowErrors | show-errors | Limits the number of errors (only) to show. |
| TidyShowInfo | show-info | Hides TidyInfo messages (only) |
| TidyShowWarnings | show-warnings | Hides TidyWarning messages (only) |
| TidyQuiet | quiet | This option specifies if Tidy should output the summary of the numbers of errors and warnings, or the welcome or informational messages. It's also suppressing footnotes. It's mostly used to squelch console output, and in tidyRunDiagnostics to squelch TY_(ReportMarkupVersion)( doc ) and TY_(ReportNumWarnings)( doc ). We should classify these messages as a different report level, and worry about squelching them. Used in triggering tidyErrorSummary (the footnotes) and tidyGeneralInfo. |
| TidyShowMetaChange | show-meta-change | WTF? Why a whole option for this? If used, it's TidyInfo, so why not just count on TidyInfo? |
Proposed replacement:
| OptID | Option | Type | Effect |
|---|---|---|---|
| TidyLimitReports | limit-reports | Int | Limits the number of any reports, in the order they are found, where 0 is all. |
| TidyShowReports | show-reports | Enum | None, Errors, Warnings, Info, default is Info, i.e., it shows everything up to and including TidyInfo. Set it to Warnings, and it only shows Errors and Warnings. Etc. |
| TidyShowFootnotes | show-footnotes | Enum | None, All, Condensed, default is Condensed. Until "real" footnotes are working, enum is None or Condensed. Further explanation below. |
| TidyQuiet | Quiet | Bool | If quiet, turns off everything except report messages as configured above. |
Alternatively, simply keep TidyShowErrors, but give it the new behavior as described for TidyLimitReports.
Footnotes: right now, several content-related helpful messages really are footnotes; they're triggered by the bit fields encountered during parsing or cleaning. This is a really useful feature, and I'd like to expand on this a bit in the future. In the meantime, this option would turn these off or on, and TidyQuiet would override this setting if TidyQuiet is used, i.e., one TidyQuiet squelches everything except reports at the selected report level.
Other TidyReportLevel handling:
| Level | How Treated per the above |
|---|---|
| TidyInfo | Hidden according to TidyShowReports |
| TidyWarning | Treated as TidyWarning |
| TidyConfig | Treated as TidyError |
| TidyAccess | Treated as TidyWarning |
| TidyError | Treated as TidyError |
| TidyBadDocument | Treated as TidyError |
| TidyFatal | Treated as TidyError |
| TidyDialogueInfo | Hidden with TidyQuiet. |
| TidyDialogueSummary | Hidden with TidyQuiet. |
| TidyDialogueFootnote | Hidden according to TidyShowFootnotes, or TidyQuiet |
| TidyDialogueDoc = TidyDialogueFootnote | Deprected, same as TidyDialogueFootnote |
It's a fairly simple change at this point, and I'll see about adding a PR just for preview purposes in case none of this makes any damned sense in text!
tl;dr
This change would give us:
- Control over total reports generated (not just errors)
- Control over the report detail with a single option ( info, warning, error )
- Control over footnote-like text separately from other noise.
- The ability to control all non-report noise.