626375346d
option every time we might want to allow or disallow new output. Adds two new
options:
- `squelch-id` (default **no**) will provide tags during Tidy's output that
can be used to silence warnings. For example, `MISSING_ENDTAG_OPTIONAL`
will be shown after warnings of that type. Then in the future, the user can
use...
- `squelch` (default NULL) takes a list of message identification tags.
Messages of this tag type will then be muted from output.
This gives the user great control over hiding things that he or she doesn't care
about seeing. However, muted errors/warnings still count toward error summaries.
If we merge this, then TidyShowMetaChange and TidyWarnPropAttrs are candidates
for removal (using the deprecation mechanism Tidy now has, these will continue
to work, though).
305 lines
9.9 KiB
C
305 lines
9.9 KiB
C
#ifndef __MESSAGE_H__
|
|
#define __MESSAGE_H__
|
|
|
|
/******************************************************************************
|
|
* @file
|
|
* Provides General Message Writing Routines
|
|
*
|
|
* This module handles LibTidy's high level output routines, as well as
|
|
* provides lookup functions and management for keys used for retrieval
|
|
* of these messages.
|
|
*
|
|
* LibTidy emits two general types of output:
|
|
*
|
|
* - Reports, which contain data relating to what Tidy discovered in your
|
|
* source file, and/or what Tidy did to your source file. In some cases
|
|
* general information about your source file is emitted as well. Reports
|
|
* are emitted in the current output buffer, but LibTidy users will probably
|
|
* prefer to hook into a callback in order to take advantage of the data
|
|
* that are available in a more flexible way.
|
|
*
|
|
* - Dialogue, consisting of footnotes related to your source file, and of
|
|
* general information that's not related to your source file in particular.
|
|
* This is also written to the current output buffer when appropriate, and
|
|
* available via callbacks.
|
|
*
|
|
* Report information typically takes the form of a warning, an error, info,
|
|
* etc., and the output routines keep track of the count of these.
|
|
*
|
|
* The preferred way of handling Tidy diagnostics output is either
|
|
* - define a new output sink, or
|
|
* - use a message filter callback routine.
|
|
*
|
|
* @author HTACG, et al (consult git log)
|
|
*
|
|
* @copyright
|
|
* Copyright (c) 1998-2017 World Wide Web Consortium (Massachusetts
|
|
* Institute of Technology, European Research Consortium for Informatics
|
|
* and Mathematics, Keio University) and HTACG.
|
|
* @par
|
|
* All Rights Reserved.
|
|
* @par
|
|
* See `tidy.h` for the complete license.
|
|
*
|
|
* @date Additional updates: consult git log
|
|
*
|
|
******************************************************************************/
|
|
|
|
#include "forward.h"
|
|
#include "config.h"
|
|
|
|
/** @addtogroup internal_api */
|
|
/** @{ */
|
|
|
|
|
|
/***************************************************************************//**
|
|
** @defgroup message_releaseinfo Tidy Release Information
|
|
**
|
|
** These functions return information about the current release version date
|
|
** and version number. Note that the latest release date or the highest
|
|
** version number alone do not guarantee the latest Tidy release, as we may
|
|
** backport important fixes to older releases of Tidy.
|
|
**
|
|
** @{
|
|
******************************************************************************/
|
|
|
|
/**
|
|
* Returns the release date of this instance of HTML Tidy.
|
|
*/
|
|
ctmbstr TY_(ReleaseDate)(void);
|
|
|
|
/**
|
|
* Returns the release version of this instance of HTML Tidy.
|
|
*/
|
|
ctmbstr TY_(tidyLibraryVersion)(void);
|
|
|
|
|
|
/** @} message_releaseinfo group */
|
|
|
|
|
|
/***************************************************************************//**
|
|
** @defgroup message_reporting Report and Dialogue Writing Functions
|
|
**
|
|
** These simple functions perform the vast majority of Tidy's output, and
|
|
** one these should be your first choice when adding your own output.
|
|
**
|
|
** A report is typically diagnostic output that is generated each time Tidy
|
|
** detects an issue in your document or makes a change. A dialogue is a piece
|
|
** of information such as a summary, a footnote, or other non-tabular data.
|
|
** Some of these functions emit multiple reports or dialogue in order to
|
|
** effect a summary.
|
|
**
|
|
** @{
|
|
******************************************************************************/
|
|
|
|
/** @name General Report Writing
|
|
** If one of the convenience reporting functions does not fit your required
|
|
** message signature, then this designated reporting function will fit the
|
|
** bill. Be sure to see if a message formatter exists that can handle the
|
|
** variable arguments.
|
|
*/
|
|
/** @{ */
|
|
|
|
|
|
/**
|
|
* The designated report writing function. When a proper formatter exists,
|
|
* this one function can hanle all report output.
|
|
*/
|
|
void TY_(Report)(TidyDocImpl* doc, Node *element, Node *node, uint code, ...);
|
|
|
|
|
|
/** @} */
|
|
/** @name Convenience Reporting Functions
|
|
** These convenience reporting functions are able to handle the bulk of Tidy's
|
|
** necessary reporting, and avoid the danger of using a variadic if you are
|
|
** unfamiliar with Tidy.
|
|
*/
|
|
/** @{ */
|
|
|
|
|
|
void TY_(ReportAccessError)( TidyDocImpl* doc, Node* node, uint code );
|
|
void TY_(ReportAttrError)(TidyDocImpl* doc, Node *node, AttVal *av, uint code);
|
|
void TY_(ReportBadArgument)( TidyDocImpl* doc, ctmbstr option );
|
|
void TY_(ReportEntityError)( TidyDocImpl* doc, uint code, ctmbstr entity, int c );
|
|
void TY_(ReportFileError)( TidyDocImpl* doc, ctmbstr file, uint code );
|
|
void TY_(ReportEncodingError)(TidyDocImpl* doc, uint code, uint c, Bool discarded);
|
|
void TY_(ReportEncodingWarning)(TidyDocImpl* doc, uint code, uint encoding);
|
|
void TY_(ReportMissingAttr)( TidyDocImpl* doc, Node* node, ctmbstr name );
|
|
void TY_(ReportSurrogateError)(TidyDocImpl* doc, uint code, uint c1, uint c2);
|
|
void TY_(ReportUnknownOption)( TidyDocImpl* doc, ctmbstr option );
|
|
|
|
|
|
/** @} */
|
|
/** @name General Dialogue Writing
|
|
** These functions produce dialogue output such as individual messages, or
|
|
** several messages in summary form.
|
|
*/
|
|
/** @{ */
|
|
|
|
|
|
/**
|
|
* Emits a single dialogue message, and is capable of accepting a variadic
|
|
* that is passed to the correct message formatter as needed.
|
|
*/
|
|
void TY_(Dialogue)( TidyDocImpl* doc, uint code, ... );
|
|
|
|
|
|
/** @} */
|
|
/** @name Output Dialogue Information */
|
|
/** @{ */
|
|
|
|
|
|
/**
|
|
* Outputs the footnotes and other dialogue information after document cleanup
|
|
* is complete. LibTidy users might consider capturing these individually in
|
|
* the message callback rather than capturing this entire buffer.
|
|
* Called by `tidyErrorSummary()`, in console.
|
|
* @todo: This name is a bit misleading and should probably be renamed to
|
|
* indicate its focus on printing footnotes.
|
|
*/
|
|
void TY_(ErrorSummary)( TidyDocImpl* doc );
|
|
|
|
|
|
/**
|
|
* Outputs document HTML version and version-related information as the final
|
|
* report(s) in the report table.
|
|
* Called by `tidyRunDiagnostics()`, from console.
|
|
* Called by `tidyDocReportDoctype()`, currently unused.
|
|
*/
|
|
void TY_(ReportMarkupVersion)( TidyDocImpl* doc );
|
|
|
|
|
|
/**
|
|
* Reports the number of warnings and errors found in the document as dialogue
|
|
* inforation.
|
|
* Called by `tidyRunDiagnostics()`, from console.
|
|
*/
|
|
void TY_(ReportNumWarnings)( TidyDocImpl* doc );
|
|
|
|
|
|
/** @} */
|
|
/** @} message_reporting group */
|
|
|
|
|
|
/***************************************************************************//**
|
|
** @defgroup message_squelching Message Squelching
|
|
**
|
|
** Message types included in the `squelch` option will be be printed in
|
|
** messageOut().
|
|
**
|
|
** @{
|
|
******************************************************************************/
|
|
|
|
/** Maintains a list of messages not to display. */
|
|
typedef struct _squelchedMessages {
|
|
tidyStrings* list; /**< A list of messages that won't be output. */
|
|
uint count; /**< Current count of the list. */
|
|
uint capacity; /**< Current capacity of the list. */
|
|
} TidySquelchedMessages;
|
|
|
|
|
|
/** Frees the list of squelched messages.
|
|
** @param doc The Tidy document.
|
|
*/
|
|
void TY_(FreeSquelchedMessageList)( TidyDocImpl* doc );
|
|
|
|
/** Adds a new message ID to the list of squelched messages.
|
|
** @param doc The Tidy document.
|
|
** @param name The message code as a string.
|
|
*/
|
|
void TY_(DefineSquelchedMessage)( TidyDocImpl* doc, const TidyOptionImpl* opt, ctmbstr name );
|
|
|
|
|
|
/** @} */
|
|
/** @} message_squelching group */
|
|
|
|
|
|
/***************************************************************************//**
|
|
** @defgroup message_keydiscovery Key Discovery
|
|
**
|
|
** LibTidy users may want to use `TidyReportCallback` to enable their own
|
|
** localization lookup features. Because Tidy's report codes are enums the
|
|
** specific values can change over time. Using these functions provides the
|
|
** ability for LibTidy users to use LibTidy's enum values as strings for
|
|
** lookup purposes.
|
|
**
|
|
** @{
|
|
******************************************************************************/
|
|
|
|
/**
|
|
* This function returns a string representing the enum value name that can
|
|
* be used as a lookup key independent of changing string values.
|
|
* `TidyReportCallback` will return this general string as the report
|
|
* message key.
|
|
*/
|
|
ctmbstr TY_(tidyErrorCodeAsKey)(uint code);
|
|
|
|
/**
|
|
* Given an error code string, return the integer value of it, or UINT_MAX
|
|
* as an error flag.
|
|
*/
|
|
uint TY_(tidyErrorCodeFromKey)(ctmbstr code);
|
|
|
|
|
|
/**
|
|
* Initializes the TidyIterator to point to the first item
|
|
* in Tidy's list of error codes that can be return with
|
|
* `TidyReportFilter3`.
|
|
* Items can be retrieved with getNextErrorCode();
|
|
*/
|
|
TidyIterator TY_(getErrorCodeList)(void);
|
|
|
|
/**
|
|
* Returns the next error code having initialized the iterator
|
|
* with `getErrorCodeList()`. You can use tidyErrorCodeAsKey
|
|
* to determine the key for this value.
|
|
*/
|
|
uint TY_(getNextErrorCode)( TidyIterator* iter );
|
|
|
|
|
|
/** @} message_keydiscovery group */
|
|
/** @} internal_api addtogroup */
|
|
|
|
|
|
|
|
/* accessibility flaws */
|
|
|
|
#define BA_MISSING_IMAGE_ALT 1
|
|
#define BA_MISSING_LINK_ALT 2
|
|
#define BA_MISSING_SUMMARY 4
|
|
#define BA_MISSING_IMAGE_MAP 8
|
|
#define BA_USING_FRAMES 16
|
|
#define BA_USING_NOFRAMES 32
|
|
#define BA_INVALID_LINK_NOFRAMES 64 /* WAI [6.5.1.4] */
|
|
#define BA_WAI (1 << 31)
|
|
|
|
/* presentation flaws */
|
|
|
|
#define USING_SPACER 1
|
|
#define USING_LAYER 2
|
|
#define USING_NOBR 4
|
|
#define USING_FONT 8
|
|
#define USING_BODY 16
|
|
|
|
/* badchar bit field */
|
|
|
|
#define BC_VENDOR_SPECIFIC_CHARS 1
|
|
#define BC_INVALID_SGML_CHARS 2
|
|
#define BC_INVALID_UTF8 4
|
|
#define BC_INVALID_UTF16 8
|
|
#define BC_ENCODING_MISMATCH 16 /* fatal error */
|
|
#define BC_INVALID_URI 32
|
|
#define BC_INVALID_NCR 64
|
|
|
|
/* other footnote bit field (temporary until formalized) */
|
|
|
|
#define FN_TRIM_EMPTY_ELEMENT 1
|
|
|
|
/* Lexer and I/O Macros */
|
|
|
|
#define REPLACED_CHAR 0
|
|
#define DISCARDED_CHAR 1
|
|
|
|
|
|
#endif /* __MESSAGE_H__ */
|