search

turnermm / codedoc

Dokuwiki plugin for documenting and displaying extended blocks of code
https://www.dokuwiki.org/plugin:codedoc
6 stars 1 forks source link

Feature request: optionally disable DW substitution in a whole code block #7

Open mburnicki opened 3 years ago

mburnicki commented 3 years ago

I'm often prefering the codedoc plugin over the builtin DW <code> syntax because <codedoc code> supports highlighting of specific parts of the sample text. This is very helpful e.g. if you want to highlight a specific part of a command, or a specific piece of text of the output from a command.

However, usage can be a bit tricky because parts of the text can be unexpectedly changed by DW's substitution, which is often not even obvious.

For example, a long command line parameter like --version is displayed correctly in a <code> block, but shows up as -version (with a single dash) in a <codedoc code> block. You can only avoid this if you explicitly use a codedoc-specific syntax (~~codedoc:clean: ... ~~) to escape every single of such potential substitutions, and you can easily overlook places like -- being substituted by -.

Also, if the output text from a command contains an email address enclosed in angle brackets, you individually have to escape each of the angle brackets < and > to see the real output of the command.

Even though I find codedoc very useful, I've often stumbled across things like this and it takes quite some time to review the generated web page to see if the DW substitution hasn't unexpectedly changed something.

I've also set up a sample page that tries to explain this in more detail: https://wiki.burnicki.net/miscellaneous_tips:00_dokuwiki:a_codedoc_plugin_test_page

So unless I'm missing something that already does this, it would be a great feature (IMO) to be able to disable DW substitution in specific code blocks, using syntax like

<codedoc code:raw> </codedoc>

or similar. I have to admit that I'm not very familiar with the way DW and the plugins work in detail, if it comes to syntax parsing. So I can't tell if it's easily possible to implement this, but it would be great if all substitutions except the codedoc-specific things like

~~codedoc:<em>~~ ... </em>~~

could be disabled.

turnermm commented 3 years ago

It's been a long time since I put codedoc together. So I'd need more time to look at the code. But initially, what I can see without having to examine codedoc is the conversion of the double dash to a single dash. That is the result of entity conversions. So editing conf/entities.conf can deal with that. Either remove -- from the entities list or redefine it. As for the angle brackets, I'm afraid you will have to live with that until (and unless) I find a reasonable solution.

turnermm commented 3 years ago

After re-examining the code, and making some tests, I see that it's not the angle brackets that cause the problem but that at-sign in the email address: <martin.burnicki@Burnicki.net>. Angle brackets are automatically converted to entities and so have no HTML effect. But in the case of the angle-bracketed email address, the at-sign forces the construction to be treated by the parser as a standard email address, and that can't be easily intercepted. So you can do one of two things. Enter an entity substitution for the @-sign into the entities.conf file or escape it using ~~codedoc:clean:@~~.

mburnicki commented 3 years ago

Thanks for looking into this. As said earlier, I really like this plugin and use it pretty often, so if you see a chance to change or improve it when you find some spare time ;-) would be much appreciated. Thanks for the hint related to email addresses. I'm going to give it a try.