miscellaneous_tips:00_dokuwiki:a_codedoc_plugin_test_page

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 
              u76bxu9x36mre79sykr41r8rx6sya1wg@burnicki.net
sub   rsa4096 2021-02-13 [SEA]


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

  • miscellaneous_tips/00_dokuwiki/a_codedoc_plugin_test_page.txt
  • Zuletzt geändert: 2021-02-16 16:31
  • von martin