Wikibooks

Template:Code/doc

< Template:Code
The latest reviewed version was checked on 9 August 2022. There are template/file changes awaiting review.

Documentation

edit

The purpose of this series of templates is to increase the readability of code examples in programming books. Each template includes a div with an colored outline and colored background, and a second div with a colored outline and white background. Inside the first div is a space which allows a comment or other instruction; inside the second div is the code space. The include code is used along with two arguments, the first being the comment and the second being the code.

Due to parsing limitations, the current version of the code template requires the user to include <pre></pre> tags around the code sample. (Inclusion of the <pre></pre> tags causes the wiki parser to render the wiki include code as plain text instead of parsing it.) This may change if I am able to hack around the parser and insert the include tag manually. (Note you can now do this using {{#tag:pre|content}} Yan (talk) 21:38, 13 November 2008 (UTC))

Templates initially created by banzaimonkey 01:04, 6 August 2006 (UTC) for the PHP wikibook. These templates are intended to be usable in all programming wikibooks, but specific alterations or exceptions may be required for a particular programming language. Please be extremely careful when modifying these templates, as your changes may be propagated across a large number of pages unbeknownst to you. If you'd like to use a code template that is not described below, feel free to add your own and include it in the list (please also include the "Code Template" category on each new template's page, inside <noinclude></noinclude> tags; see an existing template as an example).

Another concern I have is that these will add large sections of color to "Print" pages on wikibooks that use them, thus vastly increasing printing costs. If anyone has a suggestion on how to filter these to white (see template Misc2, below), please leave a note on the discussion page.

Why Use Code Templates?

edit

Why use code templates? Isn't there already a blue box around code?

The design presentation using the code template / code box highlights the code much more obviously, allowing the reader to see the code much more easily. Thus, the user is able to focus his or her energy on parsing the code only, rather than having to parse the wiki page to figure out which sections actually are code. Because there is room for comment text inside the code template, it is easier to attach a specific note, instruction, or link to a particular piece of code. This affords the author greater clarity when making reference to code examples. The code template also allows the code to be easily recognized and edited inside the wiki source because it has distinct bracketing (from the template code itself). Finally, some of the alternate stylesheets to not designate code with anything more than monospace font.

Usage Notes

edit
  • I highly recommend the use of <pre></pre> tags to format code inside the code template. This allows code to break lines and allows additional code to be added easily. It also allows authors to establish an indentation scheme, which increases readability.
  • With the inclusion of the Highlight extension to wikibooks, you can now use <source lang="x"> </source> which is automatically converted to <pre></pre> with colour-formatted code.
  • All code templates must include the correct number of vertical lines |, even if the argument is blank. If you don't want to enter text after a particular argument, that's fine, but you still need the vertical line.

Code Templates

edit
  • Template:Code:Alt - Compare two programming examples using logical "or"/"and" connector.

Example Template Usage

edit

Code:Basic

edit
This box can show code or simply be used to highlight a particular section of text with a blue outline.
Pie
  1. Cherry
  2. Apple
  3. Peach
$array_pie = {Cherry, Apple, Peach};
The explanation can be continued after the code sample.


The code for the above code box can be seen here: 

{{Code:Basic
|This box can show code or simply be used to highlight a particular section of text with a blue outline.
|Pie
#Cherry
#Apple
#Peach
<source lang="perl">$array_pie = {Cherry, Apple, Peach};</source>
|The explanation can be continued after the code sample.
}}

Code:Valid

edit
The following code is valid: 
$valid code example;
The explanation can be continued after the code sample.


The code for the above code box can be seen here: 

{{Code:Valid
|The following code is valid:
|<pre>$valid code example;</pre>
|The explanation can be continued after the code sample.
}}

Code:Error

edit
The following code contains an error: 
$this line does not end with a semicolon
The explanation can be continued after the code sample.


The code for the above code box can be seen here: 

{{Code:Error
|The following code contains an error:
|<pre>$this line does not end with a semicolon</pre>
|The explanation can be continued after the code sample.
}}

Code:Alt

edit
You can use either "echo" or "print" to output text. 
echo "Hello World.";

and / or / not / etc. 

print "Hello World.";
The explanation can be continued after the code sample.


The code for the above code box can be seen here: 

{{Code:Alt
|You can use either "echo" or "print" to output text.
|<pre>echo "Hello World.";</pre>
|and / or / not / etc.
|<pre>print "Hello World.";</pre>
|The explanation can be continued after the code sample.
}}

Code:Output

edit
In this example, you'll be able to see the code and the output it generates.

Code: 

print "Hello World.";

Output: 

Hello World.
The explanation can be continued after the code sample.

The code for the above code box can be seen here: 

{{Code:Output
|In this example, you'll be able to see the code and the output it generates.
|<pre>print "Hello World.";</pre>
|<pre>Hello World.</pre>
|The explanation can be continued after the code sample.
}}

Code:Interpreted

edit

This is a rather more complex code template, intended to present code that can be typed in to an interpreter, rather than compiled. It is expected that this sort of code will be copied and pasted directly into an interactive shell-like environment. The same template can also be used for a variety of formats, such as basic input, or input plus output. This is achieved by using a template that accepts a variable number of arguments.

If a language is specified, then syntax highlighting of code is automatically included, using the <source> tag (courtesy of GeSHi). This also allows line numbering, or (with a few user CSS lines, as described below), displays a cursor character which will not be copied and pasted. This allows readers to copy and paste example code directly into the interpreter.

Named arguments

edit

Called with 4 unnamed arguments, the output generated looks something like Template:Code:Output

The 1st argument is for the initial explanation. The entire box is contained in a div of class "code".
Input:
The 2nd argument is the text typed into the interpreter.

It will be enclosed in either <source> or <pre> tags, depending on if an input language has been specified which themselves are contained in a div of class "input". (N. B. If this parameter is blank, then the whole thing is omitted

Result:
The 3rd argument is the output. This should be in <pre> </pre> tags: you probably don't want to use <source>, because syntax-highlighting the output would be silly e.g. 
>cd /bin
>ls
bash            df              ln              rm
cat             echo            ls              rmdir
chmod           ed              mkdir           sh
cp              expr            mv              sleep
csh             hostname        ps              stty
date            kill            pwd             sync
dd              ksh             rcp             tcsh
and the 4th argument is the continuation of the explanation.

The main use of this template is to produce input text with an auto-generated prompt character, using the :before pseudo-element available in CSS. This has one major advantage, and another possible benefit

  • When copying and pasting the text, the prompt character is not copied in most browsers. This allows the user to copy the text and paste it in to the interpreter verbatim, without removing the prompt
  • The prompt character is user-defined, so can be set to the user's personal prompt character, if desired. This is of dubious benefit.
To see this in action, you need to add something like the following to your user CSS file (usually located at Special:Mypage/monobook.css)
.code .input pre{padding:0; border: none;}
.code .input pre:before {content: "\003E \0020";}
This will put a "> " prompt in front of each <pre> tag in the input box.


Called with three unnamed arguments, the Results box vanishes, as does the (now unneeded) "Input" heading

This is a script in Python. If you wish to format Python scripts differently from other scripts, add the following to your user CSS file
.code * pre.source-python:before, .code .source-python pre:before {content: "\003E \003E \003E \0020";}
hello = "Hello, World!"

print hello #does what it says
See?


However, you might want an Input/Results box with no end explanation. If so, just use a blank 4th argument

You might want to provide a Python-specific prompt in the output too. If so, just call <pre> with the appropriate class
Input:
hello = "Hello, World!"

print hello #does what it says
Result:
hello = "Hello, World!"
print hello #does what it says
Hello, World!


Now it gets simpler. With two unnamed arguments:

There is no "after" text.
cd /bin
ls


With one unnamed argument

{{{2}}}


Named arguments

edit

There are 2 named arguments: "title", "lang". (Note it would be nice to have a 3rd, whether or not to apply an output prompt)

The effect of the "title" argument should be obvious:

A simple example with 2 unnamed arguments and a "title" argument set to "Title example".
Title example
cd /bin
ls


The named argument "lang" is a shortcut, so that you don't need to put the class="source-python" or equivalent in every <pre> tag.

An example with all 6 possible arguments. The "lang" argument adds another class to the input div, called source-"lang"
A title Input:
'"`UNIQ--syntaxhighlight-00000023-QINU`"'
'"`UNIQ--pre-00000025-QINU`"'
Result:
hello = "Hello, World!"
print hello #does what it says
much easier, if you don't want to use <source>.


Wiki Code

edit

The code for all the above codeboxes is 

Called with 4 unnamed arguments, the output generated looks something like Template:Code:Output
{{Code:Interpreted
|The 1st argument is for the initial explanation. The entire box is contained in a div of class "code".
|The 2nd argument is the text typed into the interpreter. It is contained in a div of class "input". Normally the contents should be enclosed in one or more <pre> </pre> or <source> </source> tags, like so
<source lang="bash">cd /bin #a comment</source><pre>ls</pre>
|The 3rd argument is the output. This should be in <pre> </pre> tags: you probably don't want to use <source>, because syntax-highlighting the output would be silly e.g.
<pre>>cd /bin</pre>
<pre>>ls
bash            df              ln              rm
cat             echo            ls              rmdir
chmod           ed              mkdir           sh
cp              expr            mv              sleep
csh             hostname        ps              stty
date            kill            pwd             sync
dd              ksh             rcp             tcsh
</pre>
|and the 4th argument is the continuation of the explanation. 
The main use of this template is to produce input text with an auto-generated prompt character, using the :before pseudo-element available in [[CSS]]. This has one major advantage, and another possible benefit
*When copying and pasting the text, the prompt character is not copied in most browsers. This allows the user to copy the text and paste it in to the interpreter verbatim, without removing the prompt
*The prompt character is user-defined, so can be set to the user's personal prompt character, if desired. This is of dubious benefit.
To see this in action, you need to add something like the following to your [[Special:MyPage/skin.css|user CSS]] file)

<pre>.code .input pre{padding:0; border: none;}
.code .input pre:before {content: "\003E \0020";}</pre>
This will put a " >" prompt in front of each <pre> tag in the input box.
}}

Called with three unnamed arguments, the Results box vanishes, as does the (now unneeded) "Input" heading
{{Code:Interpreted
|This is a script in Python. If you wish to format Python scripts differently from other scripts, add the following to your user CSS file<pre>.code .input pre.source-python:before, .code .source-python pre:before {content: "\003E \003E \003E \0020";}</pre>
|<source lang="python">hello = "Hello, World!"</source>
<source lang="python">print hello #does what it says</source>
|See?
}}

However, you might want an Input/Results box with no end explanation. If so, just use a blank 4th argument
{{Code:Interpreted
|You might want to provide a Python-specific prompt in the output too. If so, just call <pre> with the appropriate class
|<source lang="python">hello = "Hello, World!"</source>
<source lang="python">print hello #does what it says</source>
|<pre class="source-python">hello = "Hello, World!"</pre>
<pre class="source-python">print hello #does what it says
Hello, World!</pre>
|
}}

Now it gets simpler. With two unnamed arguments: 
{{Code:Interpreted
|There is no "after" text.
|<pre>cd /bin</pre><pre>ls</pre>
}}

With one unnamed argument
{{Code:Interpreted
|there is no before text. The first argument is the code<pre>cd /bin</pre><pre>ls</pre>
}}

There are 2 named arguments: "title" and "lang". The effect of the "title" argument should be obvious:
{{Code:Interpreted
|title=Title example
|A simple example with 2 unnamed arguments and a "title" argument set to "Title example".
|<pre>cd /bin</pre><pre>ls</pre>
}}

The named argument "lang" is a shortcut, so that you don't need to put the class="source-python" or equivalent in every <pre> tag. 
{{Code:Interpreted
|A simple example with 3 unnamed arguments and a "lang" argument. The "lang" argument adds another class to the input div, called source-"lang"
|<pre>hello = "Hello, World!"</pre>
<pre>print hello #does what it says</pre>
|much easier, if you don't want to use <source>.
|code=python
}}


Code:Tip

edit
It's a good idea to add comments to your code. 
//This variable controls the loop
$loopvar1;
The explanation can be continued after the code sample.


The code for the above code box can be seen here: 

{{Code:Tip
|It's a good idea to add comments to your code.
|<pre>//This variable controls the loop
$loopvar1;</pre>
|The explanation can be continued after the code sample.
}}

Code:Transclude

edit

This can be used to create a transcluded, titled page, like so

PrettyTextBox

edit

Should this use the PrettyTextBox css class?


Retrieved from "https://en.wikibooks.org/w/index.php?title=Template:Code/doc&oldid=4089900"