Author guidelines

Note: Do not use internet Explorer for editing the wiki. Some functions don't work properly!

HTML2WIKI Migration

The ADVANCE wiki has been migrated from the UCL Confluence Wiki to the PBL Semantic Media Wiki. A HTML2WIKI conversion tool has been used to do so. The text, figures, and links are copied but the formatting can look odd, certain links can not work anymore or symbols can not be interpreted and are displayed as a question mark. For that reason all teams should check every page of your model documentation to see if the formatting is correct. In the troubleshooting section, solutions to specific errors that have come up so far can be found.

In addition, the structure of the pages of the model documentation have been changed. Some pages have new names, some have been merged or split and several new pages have been added to the wiki. Therefore it is important to check whether the content placed on the page is still correct for your model.

There are some new features in the Media Wiki:

• Creating Tables
• Creating Equations
• Dynamic referencing to Figures, Tables and Equations
• Dynamic referencing to Citations

More information on these topics can be found below.

Please go through your model documentation pages and update/add these new features where relevant.

Our experience is that editing all the citations in your reference page to the correct format is the most cumbersome task, and that starting with this before editing the pages eases the work.

Note: Wikitext contains all the features required to follow Wikipedia's formatting conventions. However, its formatting capabilities are limited. If you want to have more control of the formatting, such as using colors, text and paragraph styles, and page layout you can use HTML. HTML is the language used to format web pages in the Internet. It is more powerful than Wikitext, but it's also more complex and harder to use.

Edit text

To insert or edit text use the Edit or Edit with form tabs on the top of the page. To see how your edits are displayed save the page. To go back directly to the webpage use the Read tab.

The Edit tab contains some build in functions to format text, such as text style or linking to internal or external webpages.

More tips and tricks on text editing can be found through the following Wiki help pages:

• Wiki markup help page to format text
• Creating lists through bulletpoints or headings
• Cheatsheet containing some basic commands
• Overview of different types of way to place a link

To get you started, some basic examples:

You type	You get
''italic''	italic
'''bold'''	bold
'''''bold italic'''''	bold italic
SO<sub>4</sub><sup>2-</sup>	SO42-
Text before ---- Text after	Text before Text after
*bullet	bullet
[[Model_Documentation_-_IMAGE|Model_Documentation of IMAGE]]	Model Documentation of IMAGE
[http://fp7-advance.eu FP7-ADVANCE]	FP7-ADVANCE

Headers

Headings are created using sequences of "=" characters, placed before the heading title and after the heading title, on the same line. The level of headings is determined by the number of "=" characters.

Examples:

Level	Example
2.	==Plants==
3.	===Plants===
4.	====Plants====

Table of content

If you insert four or more headers on your page by default a table of content is displayed. The table of content gives a good overview of what can be found on the page. If you want to force display when you have three or less headings use:

__FORCETOC__

More information on the table of content can be found here.

Footnotes

Footnotes can be added to the text by placing the footnote in between the following command:

You type	You get
<ref>footnote text</ref>

By default the footnot is displayed at the bottom of the page. If you want to display the footnote at the end of the section - as we have done in this example - type

<references />

at the end of your section.

More information on footnotes can be found here

Figures

To insert a figure to your text there are a few steps to be followed:

1. Upload figure by using the Tools|Upload file link on the left panel of this website.
2. You can place the figure in the text by linking to the created file page, which typically is named File:uploadname. File pages can be found by navigating to the Tools|Special Pages on the left panel, and then navigate to Media reports and uploads|File list, or directly through this link. Place the figure in the text as followed:

[[File:uploadname]]

3. The figure can be formatted by extending the placed reference:

[[File:uploadname|size|format|caption text]]

.

4. To harmonize figure formatting in this platform we use the thumb format option. In addition figures are numbered by using the cross reference extension. For that purpose every figure must have a figure id, as follows:

<figure id="fig:myobject">
[[File:uploadname|size|format|<caption>caption text</caption>]]
</figure>

Note that the cross reference only works if the the caption text is enclosed by the <caption></caption> statement.

Example:

</figure>

MESSAGE Area projection

You type	You get
<figure id="fig:MESSAGE_1"> [[File:54067461.png|600px|thumb|<caption>MESSAGE Area projection</caption>]] </figure>	<figure id="fig:MESSAGE_1">

If you want to reference to the figure in the text:

You type	You get
<xr id="fig:MESSAGE_1"/>	<xr id="fig:MESSAGE_1"/>

More information on figure formatting can be found here

Tables

In this platform we use the standard "wikitable" format to display tables.

Examples:

The following table lacks borders and good spacing but shows the simplest wiki markup table structure.

You type	You get
{| class="wikitable" !Fruit !Price |- |Orange |$1 |- |Apple |$0.50 |}	Fruit Price Orange $1 Apple $0.50

For tables we also use cross references to number the tables on the page, and link to the table in text. In order to do so the tables must have a table id and a caption - similar to the figure cross references.

You type	You get
<figtable id="tab:example"> {| class="wikitable" |+<caption>Fruit price</caption> !Fruit !Price |- |Orange |$1 |- |Apple |$0.50 |} </figtable>	<figtable id="tab:example"> Fruit price Fruit Price Orange $1 Apple $0.50 </figtable>

Note that the cross reference only works if the the caption text is enclosed by the <caption></caption> statement.

To refer in the text to the table you can place a link to the tables id. Here it is important that the id is unique.

You type	You get
<xr id="tab:example"/>	<xr id="tab:example"/>

More information on table formatting can be found here Or look at the table generator here

Equations

We use a latex style equation writer. Equations can be inserted in the text as followed:

You type	You get
<math style="font-size: 1.5em;"> \dfrac{k}{k-1} = 0.5</math>	${\dfrac {k}{k-1}}=0.5$

The equation text must in latex language. More information on formatting equations can be found here Check if your equation text works can be done through this link

Note: Currently the extension is not working. The issue is known and will be solved in the coming 1-2 months. If you use the latex style equation writer your equation will then automatically be displayed in a correct manner.

Cross Reference

A referenced object is an object which has an identifier and a caption. In the figures and in the tables section it has been explained how this can be used for figure and table numbering and referencing.

Several types of referenced objects are supported:

• fig: a figure,
• tab: a table,
• eqn: an equation,
• def: a definition, and

Each of these types have a dedicated HTML tag to declare an object instance:

• <figure id="fig:identifier"> text </figure>
• <figtable id="tab:identifier"> text </figtable>
• <equation id=":eqn:identifier"> text </equation>
• <theorem id="def:identifier"> text </theorem>

In the text describing the referenced object, the tag <caption/> may enclose the caption of the object.

You can cross reference to the object by using the following command:

You type	You get
|<xr id="fig:MESSAGE_1"/>	<xr id="fig:MESSAGE_1"/>

It is important that your object id is unique. Therefore start the id with the type of object and follow with your model name, e.g.

fig:MESSAGE

More information on cross referencing can be found here.

Input reference card

The reference card can be filled in through the following link, also displayed on the left panel. Each field in the reference card has a specific id and to compare models input data you can use the Models - attribute tool. A selection of the reference card information is displayed on your model documentation pages in the right panel and in the table on the IAMC Wiki introduction page.

Citation Management

To place a reference to journal paper, book or other literature in your text the following steps need do be performed:

1. Look up references in a format that can be recognized by the semantic cite extention that we use in this platform. More information about semantic cite can be found here. There are two easy options:
   • Use the Citation web search function in the left panel.
   • Collect reference information in bibtext format.

Here is an example of how this could look like:

{{#scite:
 |reference=van vuuren2013a 
 |type=journal-article
 |title=A new scenario framework for Climate Change Research: scenario matrix architecture
 |author=Detlef P. van Vuuren;Elmar Kriegler;Brian C. O’Neill;Kristie L. Ebi;Keywan Riahi;Timothy R. Carter;Jae Edmonds;Stephane Hallegatte;Tom Kram;Ritu Mathur;Harald Winkler|+sep=;
 |journal=Climatic Change
 |publisher=Springer Science + Business Media
 |year=2013
 |volume=122
 |issue=3
 |pages=373-386
 |doi=10.1007/s10584-013-0906-1
 |subject=Atmospheric Science;Global and Planetary Change|+sep=;
 |issn=0165-0009;1573-1480|+sep=;
}}

2. The first line, folowing |references= indicates the key (or id) of the reference, to which you can refer to in your text. It is important you specify a key that is unique. For example by starting the key with your model name.
3. The second line, following |type= indicates the type of reference. In this wiki we have specified 5 reference types, namely journal, book, report, book chapter and website. If your reference does not fall under one of these categorization you can specify yourself how the reference is displayed, by adding an extra line with |citation text=. Several examples of the 5 supported reference types in this platform -their required and optional fields can be found on the Citation Resources example page. To avoid incorrect citation display or other errors it is important to follow these instructions carefully.
4. Add the collected reference description to the Reference page of your model,see for example the Reference page of IMAGE
5. Add the reference key to the top row of the page after |references=. This will display your reference on the References page. The list |references=<ref1;ref2;…;refn> must end with |+sep=;. This tells the system that we use the ‘;’ as list separator.
6. Insert the key in your model documentation text where you would like to add the reference by using:

   [[CiteRef::Referencekey]]

   .

The reference is indicated by a footnote, for example:

You type	You get
Van Vuuren et al. [[CiteRef::van vuuren2013a]] conclude...	Van Vuuren et al. van vuuren2013a conclude...

Note that the reference is automatically displayed at the bottom of the page, and when you render with your mouse over the citation reference it shows you the full reference details.

More information of the Citation Manager can be found here

Empty documentation pages, deletion and recreation

In order to facilitate model comparability, the sections and sub-sections are standardized for all models, and therefore all models need to be documented within a similar set of sections (the sections are presented in the table of contents in the text box on the right-hand side of each model page). Not all models have the same scope, and therefore not all pages will be filled by all models.

You may delete empty pages under the following conditions:

1. The page is not in the main branch of the documentation tree (Model scope and methods;Socio-economic drivers; Macro-economy; Energy; Land-use; Emissions; Climate; Non-climate sustainability dimension; Appendices; References)
2. The page is a leaf in the documentation tree and not a node.

You can recreate a page via Editor tools=>Model pages setup. Do not use Internet explorer for this action!.

• Open the setup page of your model. All pages of the model documentation are listed here. If a page does not exist it is displayed as a red link, preceded with Create: .

• Clicking the red link will create the page for your model and take care of the documentation tree.
• You should see a message like this one: Capital and labour markets - IMAGE: Successfully modified Capital and labour markets - IMAGE using form ModelDocumentationForm.
• Navigate via the 'Model documentation' to your recreated page and refresh the page with top-menu option: more=>refresh

Troubleshooting

If you have come across issues during the HTML2WIKI editing process that you have solved, please describe your solutions here.

Overlap of figure and Model documentation box

To force the placement of a figure beneath the Model Documentation box add the following line in your text:

<div style="clear:both"> </div>

Citation not displayed correctly

The 5 citation templates used here are sensitive to the required field. Check whether you have filled in all the required fields and have named the fields correctly. For example certain bibtext exports include citation types that are not supported by this template, or use pubdate instead of year to indicate the publication date.

Questionmarks in the text

Questionmarks in the text indicate that a symbol that you used in the Confluence Wiki is not recognized. Best is to check the original text in the Confluence Wiki and insert the intended symbol manually.

Red links

Links have been automatically copied but in some cases do not work anymore. If you see a red link in your text the page to which a link is made cannot be found. Check the link and refer to the correct webpage. More infomation on how to insert links can be found under the #Edit text header on this page.

Forced spacings

In some model documentation pages originally the paragraphs were forced by using the

<br></br>

commands. These are recognized by the current Media Wiki, however results in sometimes strange display of the text. Please remove the these statements and if you want to seperate paragraphs just use the enter key.

Copying of Tables

The tables from the original Confluence Wiki have been copied but rows or columns can be slightly mixed up. Also the formatting might need to be edited to fit the current Wiki. Some models, such as TIAM-UCL on the Energy conversion page, have used tables to display lists of input values. Using list formatting might give a better overview. More information on how to insert tables can be found under the #Tables header on this page and how to display list under the #Edit text header.