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

[Petko Yotov]

На 19/06/2022 06:12, 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.

Yes.

> or
> 
> %hlt html%@@<div some html>@@ (no html generated by PmWiki - and is
> html_escaped)

Yes.

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

Yes. Whereas [@$DefaultName@] produces neither a link nor a warning.

> 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)

No. With the latest commit I pushed today, we record all links to 
documented PmWiki variables before highlighting the block, and re-link 
them after.

> 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.

On some pages, absolutely all PHP snippets are highlighted, and with the 
previous situation there was no link to the PmWiki.Variables 
documentation.

With the latest commit, variables inside %hlt php%@@...@@ code snippets 
will retain their links to the documentation.

This is acceptable to me.

Petko


> 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