Template:CodeCommentary/doc

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

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