A 'codedoc' Plugin Test Page
I'm often prefering the dokuwiki codedoc plugin over the builtin <code> wiki syntax
because <codedoc code> supports highlighting of specific parts of the sample text.
This is very helpful e.g. if you want to show a specific command, or output from a command, and want to highlight the important parts of the text.
However, usage can be a bit tricky.
For example, the command below is tagged with <code>. The result looks good,
but there is no way to e.g. highlight the email address, which is just an example here
and will vary for other users:
gpg --with-wkd-hash --fingerprint martin.burnicki@burnicki.net
If the same command is quoted using <codedoc code> instead of <code>,
the email address can be highlighted by some codedoc-specific formatting like
~~codedoc:<em>~~martin.burnicki@burnicki.net</em>~~. The result is:
gpg –with-wkd-hash –fingerprint martin.burnicki@burnicki.net
However, this is not quite as expected. While the text in a <code> section is not checked for wiki syntax,
the text in a <codedoc code> section obviously is. In the example above, the command line parameters with 2 dashes
are displayed correctly in the <code> block, but are only rendered with a single dash in the <codedoc code> block,
resulting in a wrong command syntax.
Of course it is possible to also fix this by putting the command line parameters into some other codedoc-specific extension,
e.g. ~~codedoc:clean:–with-wkd-hash –fingerprint~~
gpg --with-wkd-hash --fingerprint martin.burnicki@burnicki.net
However, in a larger code block it is pretty easy to overlook this requirement in one or more places of the source code of the wiki page, resulting in a wrong command syntax displayed to the reader of the page.
A similar problem shows up if the output of the command contains something like an email address.
For example, the command above gives the following output on my machine, formatted in a <code> section:
pub rsa4096 2021-02-13 [SCEA]
DEFC 20F7 9CE8 F293 6E98 E491 0346 2EB9 BBB4 BE8F
uid [ultimate] Martin Burnicki <martin.burnicki@burnicki.net>
u76bxu9x36mre79sykr41r8rx6sya1wg@burnicki.net
sub rsa4096 2021-02-13 [SEA]
As you can see, the output contains my email address enclosed by angle brackets < and >.
On the other hand, the relevant part of the output that would have to be used for further processing
is the hash u76bxu9x36mre79sykr41r8rx6sya1wg.
So I try to put the output of the command into a <codedoc code> section. The result is:
pub rsa4096 2021-02-13 [SCEA]
DEFC 20F7 9CE8 F293 6E98 E491 0346 2EB9 BBB4 BE8F
uid [ultimate] Martin Burnicki martin.burnicki@burnicki.net
u76bxu9x36mre79sykr41r8rx6sya1wg@burnicki.net
sub rsa4096 2021-02-13 [SEA]
The relevant part of the output is now highlighted as expected.
However, in addition the email address is displayed as a clickable link, preceded by an email icon.
That's not what I want, and to avoid this, I also have to put each of the angle brackets
into a ~~codedoc:clean: block, e.g.:
~~codedoc:clean:<~~martin.burnicki@burnicki.net~~codedoc:clean:>~~
This finally yields the expected result that matches the real output of the example command, with the interesting part of the text highlighted:
pub rsa4096 2021-02-13 [SCEA]
DEFC 20F7 9CE8 F293 6E98 E491 0346 2EB9 BBB4 BE8F
uid [ultimate] Martin Burnicki <martin.burnicki@burnicki.net>
u76bxu9x36mre79sykr41r8rx6sya1wg@burnicki.net
sub rsa4096 2021-02-13 [SEA]
Unfortunately, it is not possible to put the whole email address including the angle brackets
into a single ~~codedoc:clean: block, e.g.:
~~codedoc:clean:<martin.burnicki@burnicki.net>~~
With this approach, the bracketed email address after the real name is totally omitted, and not displayed at all:
pub rsa4096 2021-02-13 [SCEA]
DEFC 20F7 9CE8 F293 6E98 E491 0346 2EB9 BBB4 BE8F
uid [ultimate] Martin Burnicki
Unfortunately, even though it looks like the text inside a <codedoc> block is rendered according to
the normal wiki syntax, disabling the rendering by using a <nowiki> block or its equivalent %%
doesn't seem to have any effect inside the <codedoc> block, but maybe I'm just missing something.
A simply way to prevent all standard wiki syntax parsing and only account for codedoc-specific formatting would be highly appreciated.
— Martin Burnicki martin.burnicki@burnicki.net, last updated 2021-02-16