Template:CodeCommentary/doc
This is a documentation subpage for Template:CodeCommentary. It contains usage information, categories and other content that is not part of the original Template page. |
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.
Parameter | Description | Type | Status | |
---|---|---|---|---|
Block type | type | "code" for a code block, "commentary" for a commentary block, "pre" for an unnumbered pre-style block
| String | optional |
Block content | content | Content of a code commentary block, or code in the case of a code block
| Content | optional |
Icon position | pos | If an icon is specified, place that icon next to this line in the code block
| Number | optional |
Icon | icon | In a code block, "eyes" {eye icon) or "hand" (hand icon), in a pre block, "arrow" (arrow icon)
| String | optional |
Hand link target | link | In a code block, if "hand" is specified, it can be given a link target via this parameter.
| URL | optional |
Block code language | lang | One of the languages known to the SyntaxHighlight extension
| String | optional |
Start number of code block | start | For code blocks, number the lines in this block starting from this number
| Number | optional |