• View
• Edit
• History
• Attach
• Print
• Backlinks

MarkupRulesetDebugging

Goal

Markup issues are often difficult to resolve. This has many reasons:

• Information on the exact regular expression used to identify the markup is often nonexistent, or listed by example.
• Markups are substituted sequentially. If a markup emits text that looks like another markup, it will be recognized if the new markup is processed later in the sequence, and passed through unchanged if that markup was already done. Finding the right place to insert the markup can be tricky. (See CustomMarkup.)

Installation

Copy ruletable.phpΔ to your cookbook/ directory.

In local/config.php, add the following lines:

  if (IsEnabled($EnableDiag,0) && $action == 'ruletable') {
    $RuleTableBaseFilePat = '!^.*?/(baseDirForBacktraceFileName/)!i';  // optional
    include_once ("$FarmD/cookbook/ruletable.php");
  }

$RuleTableBaseFilePat is a pattern which will be used to remove the (sometimes long) base directory portion when ruletable displays information about the source file in which the markup function was used. This can occur when a markup pattern contains the deprecated /e flag. Its use is optional. Example:

    $RuleTableBaseFilePat = '!^.*?/(pmwiki/)!i';

As of pmwiki-2.2.109, specifying "$EnableMarkupDiag = 1;" in your config.php file will cause ruletable (also, ruleset) to display source file information for all markups.

Usage

Call up the URL https://path/to/wiki/pmwiki.php?action=ruletable.

By default, all columns will be shown. If you wish to see only a specific set of columns, add the string ?columns=column,column,... to the url (no blanks allowed here).
The list of available columns is taken directly from the internal data structures. The most useful ones are pat and rep (these specify the pattern to be searched for, and what it's to be replaced with). seq is used to establish the order in which rules are applied. The remaining fields are for internal use, i.e. mostly interesting to Pm when he's debugging the markup rule engine.

If you find the column display too wide, add ?columnwidth=<number>, where <number> is any valid HTML width specification such as 100px or 10em (again, no blanks allowed). A horizontal scrollbar will appear for values too long to fit the column. To wrap rather than scroll long values, add ,wrap to the columnwidth parameter, e.g., ?columnwidth=30em,wrap.

Customisation

The script generates CSS style tags that define the ways how various types of values (arrays, strings, nulls, etc.) are displayed.

The CSS styles used are:

Note that there is no provision for configuring the styles in config.php - it would definitely be preferable over editing the PHP code that generates the styles which is the current method, but I didn't have the nerve to implement it.

Notes

See Also

• PmWiki.AvailableActions for ?action=ruleset, which is built-in but gives less information.
• PmWiki.CustomMarkup for general information about defining your own markup.

Contributors

• Joachim Durchholz- Original author
• Chuck Goldstein - Maintainer 2015-2018
• Petko - Maintainer 2024-

Change History

Comments

See discussion at MarkupRulesetDebugging-Talk?