Skip to content

Messages increment #593

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 22 commits into from
Sep 8, 2017
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
8326346
Cleanup ReportNotice() a bit by introducing an HTMLVersion() function.
balthisar Sep 2, 2017
0017811
A *complete* inventory of every message has been completed, and the d…
balthisar Sep 2, 2017
46aa960
All reports that can use formatAttributeReport are now using it. Move…
balthisar Sep 2, 2017
0c8f684
Migrated messages using formatter formatBadArgument to new message sy…
balthisar Sep 2, 2017
66e4d1f
Migrated reports using formatter formatCustomTagDetected.
balthisar Sep 2, 2017
1d2c019
Added a new string to disambiguate between config files and other fil…
balthisar Sep 4, 2017
283f897
Migrated reports using formatFileError and formatStandard to flexible…
balthisar Sep 4, 2017
be22ad3
Move file errors into the standard formatter. Local context is preser…
balthisar Sep 4, 2017
e3893eb
Also merged reportBadArgument into standard formatter as above.
balthisar Sep 4, 2017
18754c7
Transitioned formatCustomTagDetected to the general formatter.
balthisar Sep 4, 2017
8cb4198
Entity errors migrated.
balthisar Sep 4, 2017
f49c419
Implement formatter for encoding reports.
balthisar Sep 4, 2017
5b6edb5
EncodingWarning and MissingAttr migrated.
balthisar Sep 4, 2017
bc4388e
Migrated surrogate errors; removed break after return.
balthisar Sep 4, 2017
832b477
A bit of organizational cleanup.
balthisar Sep 4, 2017
d8220c0
Updated the remaining items, including all of the accessibility modul…
balthisar Sep 4, 2017
a743c86
Removed comments from and sorted error messages, as they are document…
balthisar Sep 4, 2017
80cb74f
Removed comments from and sorted error messages, as they are document…
balthisar Sep 4, 2017
279dd55
Regenerated PO's and POT.
balthisar Sep 4, 2017
6b3dfda
Updated the MESSAGES.md readme for the updated message system.
balthisar Sep 7, 2017
6bce1b3
Updated the POs and POT to reflect the re-sorted strings.
balthisar Sep 7, 2017
4509695
Updated documentation in file.
balthisar Sep 7, 2017
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 13 additions & 7 deletions README/MESSAGES.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Message System

Tidy has quite complex warning/error messaging system. This is all about adding a **new** warning or error message to **libTidy**.
Tidy has a quite complex warning/error report and footnote messaging system, but most of this complexity is completely hidden away from you in order to make adding messages as simple as possible. This particular README instructs you how to add a new warning/error report to **libTidy**.

First assign the message a key value. This is done in `tidyenum.h`, in one of the two enumerations that are listed there.
First assign the message a **key** value. This is done in `tidyenum.h`, in one of the two enumerations that are listed there.

1. `tidyStrings` - starts with the value `TIDYSTRINGS_FIRST = 500`, and it must be first. This is the list of all strings available in Tidy with the exception of strings provided by other enumerations. **However** don't modify this enum directly. You'll modify a preprocessor macro instead.

Expand All @@ -12,24 +12,30 @@ First assign the message a key value. This is done in `tidyenum.h`, in one of th

4. `TidyReportLevel` - And you probably won't need this, either.


All enum values are only ever used by name within **libTidy** (and incidentally, should only ever be used by name in your client applications; never trust the value!), so feel free to enter new strings wherever they make the most sense.
All enum values are only ever used by name within **libTidy** (and incidentally, should only ever be used by name in your client applications; never trust the value!), so feel free to enter new strings in English alphabetical order (this helps us audit all of the strings from time to time).

As mentioned above, `tidyStrings` messages must be defined in one of the existing macros named like `FOREACH_...(FN)`, such as `FOREACH_DIALOG_MSG(FN)`. These macros ensure that another data structure used for localization and key lookup is updated automatically any time strings are added or removed, thus limiting the possibility of developer error.


## Step 1

So in this case I want to add 3 warning messages: `BAD_SURROGATE_PAIR`, `BAD_SURROGATE_TAIL`, and `BAD_SURROGATE_LEAD`. Because these are error messages, they belong in the `tidyStrings` enum, and they fit into nicely into the macro beginning `FOREACH_DIALOG_MSG(FN)`. Please look at the comments for the category which indicates which output routine is used to generate the error, and keep this list in order!
So in this case I want to add 3 warning messages: `BAD_SURROGATE_PAIR`, `BAD_SURROGATE_TAIL`, and `BAD_SURROGATE_LEAD`. Because these are error reports, they belong in the `tidyStrings` enum, and they fit into nicely into the macro beginning `FOREACH_REPORT_MSG(FN)`. Add the message key values into this macro, ensuring they are nested in the `FN()` syntax.


## Step 2

The next step is adding a `format` string to `language_en.h`. This string may later be translated to various supported language strings, but at present it is important that the other language translated strings, like `language_fr.h`, `language_es.h`, etc, keep the same format order.
The next step is adding a `format` string to `language_en.h`. This string may later be translated to various supported language strings, but even if you wish to support another language, it’s critical that you add the message format string to `language_en.h`, which serves as the base language for `LibTidy`.

Where to add this seems a bit of a mess, but in general things are grouped by where they're used in `libTidy`, and often in alphabetical order within those groups. Here I've added them relative to where they were placed in the other enums and structs.
Where to add this seems a bit of a mess, but in general things are grouped by where they're used in `libTidy`, and often in alphabetical order within those groups. Here I've added them in alphabetical order in the section where all of the other report messages are.

Depending on which of the output routines you use (consult `message.c`) you may be able to use parameters such as `%u` and `%s` in your format strings. The available data is currently limited to the available message output routines. Please don't use `printf` for message output within **libTidy**.

Note that Tidy doesn't currently support numbered `printf` parameters; parameters will be consumed in the order the report output function calls them.

## Step 3

The last step — hopefully — is adding the message key to the `dispatchTable[]` structure in `message.c`. This structure determines the `TidyReportLevel` (report severity) and message formatter (how to print the message). Then whenever you issue the report with `TY_(Report)()` or one of the existing convenience report functions, the correct message formatter will be used for the parameters that you specify.

Please read the source code in `message.c` for help on how to choose a message formatter, or how to modify one of the existing message formatters if you need to accomodate a new function signature for your report.

eof;
126 changes: 58 additions & 68 deletions include/tidyenum.h
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,7 @@ extern "C" {
*/
#define FOREACH_MSG_MISC(FN) \
/** File can't be opened */ FN(FILE_CANT_OPEN) \
/** File can't be opened */ FN(FILE_CANT_OPEN_CFG) \
/** Not a file */ FN(FILE_NOT_FILE) \
/** line %d column %d */ FN(LINE_COLUMN_STRING) \
/** Document content looks like %s */ FN(STRING_CONTENT_LOOKS) \
Expand Down Expand Up @@ -162,111 +163,100 @@ extern "C" {
** of errors and warnings.
*/
#define FOREACH_REPORT_MSG(FN) \
/* ReportAttrError */ \
FN(ADDED_MISSING_CHARSET) \
FN(ANCHOR_NOT_UNIQUE) \
FN(APOS_UNDEFINED) \
FN(ATTR_VALUE_NOT_LCASE) \
FN(ATTRIBUTE_IS_NOT_ALLOWED) \
FN(ATTRIBUTE_VALUE_REPLACED) \
FN(BACKSLASH_IN_URI) \
FN(BAD_ATTRIBUTE_VALUE_REPLACED) \
FN(BAD_ATTRIBUTE_VALUE) \
FN(ATTRIBUTE_VALUE_REPLACED) \
FN(BAD_CDATA_CONTENT) \
FN(BAD_SUMMARY_HTML5) \
FN(BAD_SURROGATE_LEAD) \
FN(BAD_SURROGATE_PAIR) \
FN(BAD_SURROGATE_TAIL) \
FN(CANT_BE_NESTED) \
FN(COERCE_TO_ENDTAG) \
FN(CONTENT_AFTER_BODY) \
FN(CUSTOM_TAG_DETECTED) \
FN(DISCARDING_UNEXPECTED) \
FN(DOCTYPE_AFTER_TAGS) \
FN(DUPLICATE_FRAMESET) \
FN(ELEMENT_NOT_EMPTY) \
FN(ELEMENT_VERS_MISMATCH_ERROR) \
FN(ELEMENT_VERS_MISMATCH_WARN) \
FN(ENCODING_MISMATCH) \
FN(ESCAPED_ILLEGAL_URI) \
FN(FIXED_BACKSLASH) \
FN(FOUND_STYLE_IN_BODY) \
FN(ID_NAME_MISMATCH) \
FN(ILLEGAL_NESTING) \
FN(ILLEGAL_URI_CODEPOINT) \
FN(ILLEGAL_URI_REFERENCE) \
FN(INSERTING_AUTO_ATTRIBUTE) \
FN(INSERTING_TAG) \
FN(INVALID_ATTRIBUTE) \
FN(INVALID_NCR) \
FN(INVALID_SGML_CHARS) \
FN(INVALID_UTF8) \
FN(INVALID_UTF16) \
FN(INVALID_XML_ID) \
FN(JOINING_ATTRIBUTE) \
FN(MALFORMED_COMMENT) \
FN(MALFORMED_DOCTYPE) \
FN(MISMATCHED_ATTRIBUTE_ERROR) \
FN(MISMATCHED_ATTRIBUTE_WARN) \
FN(MISSING_ATTR_VALUE) \
FN(MISSING_ATTRIBUTE) \
FN(MISSING_DOCTYPE) \
FN(MISSING_ENDTAG_BEFORE) \
FN(MISSING_ENDTAG_FOR) \
FN(MISSING_IMAGEMAP) \
FN(MISSING_QUOTEMARK) \
FN(NEWLINE_IN_URI) \
FN(PROPRIETARY_ATTR_VALUE) \
FN(PROPRIETARY_ATTRIBUTE) \
FN(REPEATED_ATTRIBUTE) \
FN(UNEXPECTED_END_OF_FILE_ATTR) \
FN(UNEXPECTED_EQUALSIGN) \
FN(UNEXPECTED_GT) \
FN(UNEXPECTED_QUOTEMARK) \
FN(WHITE_IN_URI) \
FN(XML_ID_SYNTAX) \
/* ReportEncodingError */ \
FN(INVALID_NCR) \
FN(INVALID_SGML_CHARS) \
FN(INVALID_UTF16) \
FN(INVALID_UTF8) \
FN(VENDOR_SPECIFIC_CHARS) \
/* ReportEncodingWarning */ \
FN(ENCODING_MISMATCH) \
/* ReportEntityError */ \
FN(APOS_UNDEFINED) \
FN(MISSING_SEMICOLON_NCR) \
FN(MISSING_SEMICOLON) \
FN(UNESCAPED_AMPERSAND) \
FN(UNKNOWN_ENTITY) \
/* ReportError */ \
FN(BAD_CDATA_CONTENT) \
FN(CANT_BE_NESTED) \
FN(CONTENT_AFTER_BODY) \
FN(DISCARDING_UNEXPECTED) \
FN(DOCTYPE_AFTER_TAGS) \
FN(ELEMENT_VERS_MISMATCH_ERROR) \
FN(ELEMENT_VERS_MISMATCH_WARN) \
FN(ILLEGAL_NESTING) \
FN(INSERTING_TAG) \
FN(MALFORMED_COMMENT) \
FN(MALFORMED_DOCTYPE) \
FN(MISSING_DOCTYPE) \
FN(MISSING_ENDTAG_BEFORE) \
FN(MISSING_ENDTAG_FOR) \
FN(MISSING_STARTTAG) \
FN(MISSING_TITLE_ELEMENT) \
FN(MOVED_STYLE_TO_HEAD) \
FN(NESTED_EMPHASIS) \
FN(NESTED_QUOTATION) \
FN(NEWLINE_IN_URI) \
FN(NOFRAMES_CONTENT) \
FN(NON_MATCHING_ENDTAG) \
FN(OBSOLETE_ELEMENT) \
FN(PREVIOUS_LOCATION) \
FN(PROPRIETARY_ATTR_VALUE) \
FN(PROPRIETARY_ATTRIBUTE) \
FN(PROPRIETARY_ELEMENT) \
FN(REMOVED_HTML5) \
FN(REPEATED_ATTRIBUTE) \
FN(REPLACING_ELEMENT) \
FN(REPLACING_UNEX_ELEMENT) \
FN(SPACE_PRECEDING_XMLDECL) \
FN(SUSPECTED_MISSING_QUOTE) \
FN(TAG_NOT_ALLOWED_IN) \
FN(TOO_MANY_ELEMENTS_IN) \
FN(TOO_MANY_ELEMENTS) \
FN(USING_BR_INPLACE_OF) \
/* ReportFatal */ \
FN(DUPLICATE_FRAMESET) \
FN(SUSPECTED_MISSING_QUOTE) \
FN(TRIM_EMPTY_ELEMENT) \
FN(UNESCAPED_AMPERSAND) \
FN(UNEXPECTED_END_OF_FILE_ATTR) \
FN(UNEXPECTED_END_OF_FILE) \
FN(UNEXPECTED_ENDTAG_ERR) \
FN(UNEXPECTED_ENDTAG_IN) \
FN(UNEXPECTED_ENDTAG) \
FN(UNEXPECTED_EQUALSIGN) \
FN(UNEXPECTED_GT) \
FN(UNEXPECTED_QUOTEMARK) \
FN(UNKNOWN_ELEMENT_LOOKS_CUSTOM) \
FN(UNKNOWN_ELEMENT) \
/* ReportMissingAttr */ \
FN(MISSING_ATTRIBUTE) \
/* ReportNotice */ \
FN(CUSTOM_TAG_DETECTED) \
FN(REPLACING_ELEMENT) \
FN(TRIM_EMPTY_ELEMENT) \
/* ReportSurrogateError */ \
FN(BAD_SURROGATE_LEAD) \
FN(BAD_SURROGATE_PAIR) \
FN(BAD_SURROGATE_TAIL) \
/* ReportWarning */ \
FN(BAD_SUMMARY_HTML5) \
FN(NESTED_EMPHASIS) \
FN(NESTED_QUOTATION) \
FN(OBSOLETE_ELEMENT) \
FN(REMOVED_HTML5) \
FN(UNKNOWN_ENTITY) \
FN(USING_BR_INPLACE_OF) \
FN(VENDOR_SPECIFIC_CHARS) \
FN(WHITE_IN_URI) \
FN(XML_DECLARATION_DETECTED) \
/* Report, mixed use */ \
FN(ADDED_MISSING_CHARSET) \
FN(COERCE_TO_ENDTAG) \
FN(ELEMENT_NOT_EMPTY) \
FN(FOUND_STYLE_IN_BODY) \
FN(MOVED_STYLE_TO_HEAD) \
FN(UNEXPECTED_END_OF_FILE) \
FN(UNEXPECTED_ENDTAG) \
FN(UNEXPECTED_ENDTAG_ERR)
FN(XML_ID_SYNTAX)


/** These are report messages added by Tidy's accessibility module.
Expand Down
Loading