Jump to content

Template:CodeCommentary/doc

From mediawiki.org

Usage

[edit]

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

[edit]

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

[edit]

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.

ParameterDescriptionTypeStatus
Block typetype

"code" for a code block, "commentary" for a commentary block, "pre" for an unnumbered pre-style block

Default
code
Stringoptional
Block contentcontent

Content of a code commentary block, or code in the case of a code block

Example
Here is some code commentary.
Contentoptional
Icon positionpos

If an icon is specified, place that icon next to this line in the code block

Example
3
Numberoptional
Iconicon

In a code block, "eyes" {eye icon) or "hand" (hand icon), in a pre block, "arrow" (arrow icon)

Example
eyes
Stringoptional
Hand link targetlink

In a code block, if "hand" is specified, it can be given a link target via this parameter.

Example
https://www.mediawiki.org
URLoptional
Block code languagelang

One of the languages known to the SyntaxHighlight extension

Example
python
Stringoptional
Start number of code blockstart

For code blocks, number the lines in this block starting from this number

Example
5
Numberoptional