Template:CodeCommentary
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
<templatedata> { "params": { "type": { "label": "Block type", "description": "\"code\" for a code block, \"commentary\" for a commentary block, \"pre\" for an unnumbered pre-style block", "type": "string", "default": "code" }, "content": { "label": "Block content", "description": "Content of a code commentary block, or code in the case of a code block", "example": "Here is some code commentary.", "type": "content" }, "pos": { "label": "Icon position", "description": "If an icon is specified, place that icon next to this line in the code block", "example": "3", "type": "number" }, "icon": { "label": "Icon", "description": "In a code block, \"eyes\" {eye icon) or \"hand\" (hand icon), in a pre block, \"arrow\" (arrow icon)", "example": "eyes", "type": "string" }, "link": { "label": "Hand link target", "description": "In a code block, if \"hand\" is specified, it can be given a link target via this parameter.", "example": "https://www.mediawiki.org", "type": "url" }, "lang": { "label": "Block code language", "description": "One of the languages known to the SyntaxHighlight extension", "example": "python", "type": "string" }, "start": { "label": "Start number of code block", "description": "For code blocks, number the lines in this block starting from this number", "example": "5", "type": "number" } }, "description": "Display code blocks interspersed with blocks of commentary.", "format": "block" } </templatedata>
