Template:CodeCommentary

Template documentation

Usage

Use the template to display blocks of code with syntax highlighting interspersed with blocks of commentary.

Additionally, you can add an icon next to a specific line of the code block, of an eye (indicating "look here!") or of a pointing hand (this may take a link; since we cannot directly add a link a class name in a code block, this is the next best thing.

And finally, you can add a block of not-quite-code with pre-style formatting (no line numbers, monospace font, etc) with an optional arrow icon next to a line.

To add a commentary block, do the following:

{{CodeCommentary|type=comment|content=
Here goes all my lovely lovely commentary.
}}

To add a code block with no icon, do the following (using the language of your choice from this list:

{{CodeCommentary|type=code|lang=python|content=
#!/usr/bin/python3 ...
}}

To add a code block with an eyes icon at line 3 in the block (counting from 1 always), do:

{{CodeCommentary|type=code|lang=python|icon=eyes|pos=3|content=
#!/usr/bin/python3

import this
import that
}}

To add a code bloc with a hand icon at line 3 in the block and a link, do:

{{CodeCommentary|type=code|lang=python|icon=hand|pos=3|link=https://www.pylint.org/|content=
#!/usr/bin/python3

import this
import that
}}

You may also change the line numbering to start with a different number, if you are spltting up a longer piece of code into blocks for commentary, as intended with this template. TO start a code block with line 5, do:

{{CodeCommentary|type=code|lang=python|start=5|content=
#!/usr/bin/python3

import this
import that
}}

To add a block of ...stuff... with pre-style formatting and an arrow icon, use

{{CodeCommentary|type=pre|icon=arrow|pos=2|content=
1 max continue none /bin/bash ./worker --skipdone --exclusive --log --configfile /etc/dumps/confs/wikidump.conf.dumps --date {STARTDATE} --onepass --prereqs --skipjobs metahistorybz2dump,metahistorybz2dumprecombine,metahistory7zdump,metahistory7zdumprecombine,xmlflowhistorydump
6 max continue none /bin/bash ./worker --skipdone --exclusive --log --configfile /etc/dumps/confs
}}

Warnings

The syntax highlighter, or maybe it's MediaWiki, will toss leading blanks on the first and last lines of content of your code blocks. Stop this from happening by putting a zero-width-space () as the first character of such a line.

You can use the template Template:ZWS to add one at the beginning of such lines.

You may also need to use Template:( to replace left curly brackets in some circumstances, or Template:)) to replace double right curly brackets.

Pre-blocks next to commentary blocks may be displayed with extra white space between them during an edit preview. After save they should look fine.

Examples

Do:

{{CodeCommentary|type=comment|content=
Here is a wee bit of text because, meh, we need it for an example

A bit more text because that's how we roll.

Ok done now.
}}
{{CodeCommentary|type=code|start=1|lang=python|icon=hand|pos=3|link=User:ArielGlenn|content=
import os
import sys
from subprocess import PIPE

# just a few line of crap to illustrate the point
}}
{{CodeCommentary|type=pre|icon=arrow|pos=2|content=
dblist=/srv/mediawiki/dblists/all.dblist
privatelist=/srv/mediawiki/dblists/private.dblist
closedlist=/srv/mediawiki/dblists/closed.dblist
skipdblist=/etc/dumps/dblists/skip.dblist
flowlist=/srv/mediawiki/dblists/flow.dblist
}}

to get

Here is a wee bit of text because, meh, we need it for an example

A bit more text because that's how we roll.

Ok done now.

import os
import sys
from subprocess import PIPE

# just a few line of crap to illustrate the point

dblist=/srv/mediawiki/dblists/all.dblist
privatelist=/srv/mediawiki/dblists/private.dblist
closedlist=/srv/mediawiki/dblists/closed.dblist
skipdblist=/etc/dumps/dblists/skip.dblist
flowlist=/srv/mediawiki/dblists/flow.dblist

Display code blocks interspersed with blocks of commentary.

Template parameters[Edit template data]
This template prefers block formatting of parameters.
Parameter		Description	Type	Status
Block type	`type`	"code" for a code block, "commentary" for a commentary block, "pre" for an unnumbered pre-style block Default code	String	optional
Block content	`content`	Content of a code commentary block, or code in the case of a code block Example Here is some code commentary.	Content	optional
Icon position	`pos`	If an icon is specified, place that icon next to this line in the code block Example 3	Number	optional
Icon	`icon`	In a code block, "eyes" {eye icon) or "hand" (hand icon), in a pre block, "arrow" (arrow icon) Example eyes	String	optional
Hand link target	`link`	In a code block, if "hand" is specified, it can be given a link target via this parameter. Example https://www.mediawiki.org	URL	optional
Block code language	`lang`	One of the languages known to the SyntaxHighlight extension Example python	String	optional
Start number of code block	`start`	For code blocks, number the lines in this block starting from this number Example 5	Number	optional