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

[Simon]

If I understand this correctly:
This is about the html inserted by PmWki, rather than as follows:
%hlt html%[@<div some html>@] will highlight correctly and *will not *generate
warnings from the html.
or
%hlt html%@@<div some html>@@ (no html generated by PmWiki - and is
html_escaped)

Instead it is about
%hlt html%@@'''PmWiki markup generating  html'''@@
such as
%hlt html%@@$DefaultName@@

Is it possible to restrict  the highlighting, for example, to the text
only  between the <a> and </a> tags? (i.e. excluding the tags)
Otherwise I favour stripping the HTML within @@ @@ (but am interested in
more discussion)

I think that links to  $pmwikivariables in HTML are less important than
highlighting. These variables, and thus links, can be incorporated
elsewhere in the documentation outside of the example code
This is the practice I have taken in updating documentation.

This means that we should not use @@$variable@@ in the markup any more to
use the mono font to distinguish it from normal text, a practice we
also use for file names. e.g. @@local/config.php@@ and some similar .
Of course not all $variables documented are core pmwiki variables and have
links.


thanks

Simon


On Fri, 17 Jun 2022 at 19:59, Petko Yotov <5ko at 5ko.fr> 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?
>
> Petko
>
> _______________________________________________
> pmwiki-users mailing list
> pmwiki-users at pmichaud.com
> http://www.pmichaud.com/mailman/listinfo/pmwiki-users
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.pmichaud.com/pipermail/pmwiki-users/attachments/20220619/48c2babe/attachment.html>