MarkupRulesetDebugging

Summary: Debugging Markup Ruleset
Version: 2024-02-26
Prerequisites: PmWiki 2.2.58 or more recent
Status: stable
Maintainer: Petko
License: BSD 2-clause

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:

.type_unsetNot set in PHP (i.e. PHP's NULL value).
.type_nullSQL NULL value.
.type_resourceAn external resource (file handle etc.).
.type_syntaxDelimiters (such as commas between array elements).
.type_boolTrue and False values.
.type_scalarA scalar (number or string).
.type_controlcodeA control code within a string.
.type_unkownSome PHP type that ruletable.php doesn't know about. (This Should Not Happen.)

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

Contributors

Change History

2024-02-26Update for PHP 8.3, fix RecipeInfo to work with recipecheck, add license after emailing with Joachim Durchholz (Petko)
2018-09-22Improve the Installation and Usage sections of this document
2018-05-03Improve columnwidth processing, add wrap option.
2017-10-21Update for PHP 7.2
 Make lambda replacement processing more flexible.
 Allow replacements to be closure objects.
2017-05-23Add a test for duplicate patterns.
2016-02-17Change Maintainer to Chuck G.
2015-05-12Chuck Goldstein:
 Fix misplaced <html> and missing <body> tags.
 Add global version info.
 Make Markup_e replacement code display properly (instead of *lambda_*).
 Highlight patterns that use the deprecated /e flag.
 Display ['dbg'] backtrace info, added in pmwiki 2.2.71, if present.
 Add global configuration variable $RuleTableBaseFilePat to allow abbreviation of the PHP file name in backtrace items.
 Add the $KeepToken character to the html escape table to correct the display for pmwiki versions < 2.2.41.
2006-01-25Fixed PHP5 incompatibility.
2005-04-15Made column and width settings configurable via URL (in the query string).
 Available column names now taken from PmWiki variable, not from hardcoded list.
 Improvements for control code handling: catches all nonprinting codes, and makes them their own CSS class now.
2005-04-03Initial revision.

Comments

See discussion at MarkupRulesetDebugging-Talk?

User notes? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.