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

[V.Krishn]

On 6/17/22 13:28, Petko Yotov wrote:
> 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?

Can a /Test page be setup ?

Thanks
-- 
Regards,
V.Krishn

> 
> Petko
>