[pmwiki-users] Syntax highlighting in the core documentation?

[Petko Yotov]

Hello,

There is an effort in progress to beautify / syntax highlight the PHP 
snippets in the documentation.

The benefit is obvious -- it is very nice, it allows to easily notice 
the different parts of the configuration.

There are unfortunately 2 relatively important downsides.


1. The Highlight.js library only expects plain text in the code blocks, 
and if there is any HTML, it strips it keeping the plain text, and it 
outputs many rather ominous warnings in the JavaScript console of the 
browser saying:

   One of your code blocks includes unescaped HTML.
   This is a potentially serious security risk.
   One of your code blocks includes unescaped HTML.
   This is a potentially serious security risk.
   One of your code blocks includes unescaped HTML.
   This is a potentially serious security risk.

This is for every processed/highlighted block, sometimes 20 times in a 
page.

These warnings are unacceptable to me, I don't want a wiki admin to 
install PmWiki and Highlight.js and to have these warnings appear out of 
the box from the core documentation.

How can unescaped HTML happen? It can if the code is surrounded with 
@@...@@ instead of [@...@], then there may be some HTML inside, like 
bold, or a PmWiki variable like $EnableDiag or $DefaultPasswords.

This leads to:

2. In highlighted blocks stripped of inner HTML, PmWiki variables from 
the documentation like $DefaultPasswords or $EnableUpload no longer link 
to the PmWiki/Variables documentation sections where these variables are 
explained.


What do you think is more useful to wiki admins installing and 
configuring PmWiki?

* Is it the nice colors for the PHP code?

* Is is the automatic links to the PmWiki Variables documentation?


I suspect in a short PHP snippet the documentation links are more useful 
to admins than the colors (and BTW the links are colored blue so they 
already stand out).


I see 2 options:

1. If the syntax highlighting is more important, we can strip all HTML 
in the blocks before highlighting them, just to keep the warnings from 
appearing: the Highlight library will strip it anyway, while 
complaining.

2. We can omit PHP blocks containing HTML, especially links to core 
variables, from being highlighted. However, this might surprise some 
editors with their own code.We can configure a "title" attribute for the 
block that explains the reason?

What do you think?

Petko