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@pmichaud.com
http://www.pmichaud.com/mailman/listinfo/pmwiki-users
